Docs: Prepare for table of contents

[pedrottimark]

This pull request adds the styles for a table of contents, which was recommended in #186 (comment).

Goals:

• for readability, limit length of lines to 80 characters for code and about 3 alphabets for text (from 1.5 to 2.5 is the guideline for prose reading, so close enough for tech content :)
• and make the lines fit on iPad (non-Pro) in portrait orientation
• be able to display a table of contents of headings level 2 through [EDIT2] 3, aligned at the top of the first ordinary content paragraph, if the width is at least iPad (non-Pro) in landscape orientation
• display inline code similar to GitHub so it looks noticeably different from hyperlinks
• [EDIT3] Instead of Docs: Prepare for table of contents #256 (comment) the change to color of links was to the blue of the outer hexagon and not to change color on hover

Goals in 4 words: content first, mobile second. Our analytics cannot tell whether it is worth the effort to make the site mobile-friendly until we have gone at least halfway. Chicken and egg. Careful effort to improve readability and navigation works for both mobile (especially tablet) and desktop screen.

Some following comments have explanations and pictures. Several pictures show what the proposed table of contents will look like for critique. It will require changes to the Makefile.js build file.

Here is the notation that kramdown uses, see http://kramdown.gettalong.org/converter/html.html#toc

* placeholder for table of contents
{:toc}

Set toc_levels: 2..4 in _config.yml see http://kramdown.gettalong.org/options.html#option-toc-levels

[pedrottimark]

• baseline style for 1280px laptop screen has max-width: 1170px = 69em
• proposed style has max-width: 43em = 731px and displays full contents even for wide heading
• proposed style for simulated 1024px iPad (non-Pro) in landscape orientation truncates contents but displays enough to distinguish headings

baseline 1280px:

proposed 1280px:

proposed 1024px EDIT notice that max-width of paragraphs is same as above:

[pedrottimark]

This page, which might have the longest contents, illustrates why the contents will scroll vertically. Furthermore, I have recently seen complaint how too much fixed stuff makes the content seem crowded.

Although rule docs have plain text for option headings, code style looks good for CLI options. When I experimented removing the backticks, very hard to distinguish hyphen from double hyphen.

proposed 1024px:

EDIT and here is a picture with contents limited to heading levels 2 and 3:

[pedrottimark]

The proposed max-width is just wide enough for 80 characters of code:

• simulated 1024px iPad (non-Pro) in landscape orientation (about the narrowest that has contents)
• simulated 768px iPad (non-Pro) in portrait orientation (does not have contents)

landscape orientation:

portrait orientation EDIT notice that max-width of paragraphs and code is same as above:

[pedrottimark]

The simulators disagree about what happens at width 768px apparently because of the scroll bar:

• Firefox displays icon in left margin, which is what I intended
• Chrome displays icon indented in text

Firefox:

Chrome:

If Chrome is accurate, THEN I WILL NEED to adjust the style later. By the way, at one point in the middle of developing the styles, Search the docs… input box fell out of the heading when I dragged to make the browser screen narrower, but have not been able to reproduce that fault again.

At any width < 768px, the icon is indented, for example in a simulated 600px by 960px screen:

Here is the difference when you drag the right edge of the browser window on a desktop screen:

• baseline style jumps 2 times because there are 3 width breakpoints (to me at least, the Bootstrap stuff to center the text makes it hard to realize that the Web site already works okay on a tablet).
• proposed style has smoother transitions:
  • contents truncates at the right and disappears at 60em = 1020px
  • text wraps normally when line width is less than 43em = 731px
  • left margin decreases and icons become indented (looks a bit like a punch ;) at screen width less than 768px

I hope that for everyone who dislikes the asymmetrical design with more white space at the right for wider screens, the narrow margin at the left makes the icons look more like semantic bullets.

[pedrottimark]

Here is an example why change the colors for inline code:

• baseline style (color and background-color related to ESLint theme) hides the hyperlinks, at least to my eyes (that is the reason for a few Details Here hyperlinks, I think :)
• proposed style (GitHub convention) contrasts more clearly with hyperlinks, but WHAT DO YOU THINK about contrast with the text?

baseline:

proposed:

EDIT and notice how the purple visited links need underline to contrast with black text:

[IanVS]

Honestly I think this is all great. I particularly like the differentiation between code and links. The contrast of code text is more subtle in your proposed version, but I think that's a good thing. It's enough to be noticeable but not so much as to be distracting.

I also really like the TOC. A nice side-effect is that the text is no longer so wide, which I think was a readability problem anyway (the line length in your baseline 1280px example are way too long).

Overall this gets a big 👍 from me.

[pedrottimark]

Forgot to ask whether it is an intentional for visited links to have same color as unvisited?

When I started to use ESLint, not easily seeing which rules I had already read felt confusing.

Here is a picture with the inner hexagon color for visited and the outer hexagon color for unvisited. I agree with first impression feedback from @omerbalyali that the contrast is too subtle and so am inviting him to advise on colors compatible with logo which have enough contrast.

Glad to get responses for situation when you look for technical information, which links are better for you to be more emphasized versus less emphasized in coloring?

I can see two conflicting principles for what to emphasize:

• visited: information I have sought in the past and might need again in the future
• unvisited: new information I have not yet seen

[ilyavolodin]

Would we need to specify TOC in every file we want it to show up, or will it show up automatically? I think it would be great to add TOC to most of the user guide pages as well as developer guide, but not to rule pages.

[pedrottimark]

@ilyavolodin Must insert the snippet in every file (EDIT that has a toc) so you can include in some but not others. Assuming we will want to do it in the build to avoid inconsistency.

* placeholder for table of contents
{:toc}

[pedrottimark]

A helpful insight in #256 (comment) that consistency in structure of rule pages implies little useful information in table of content. Except options, maybe. Here are pictures of a subset TOC for rule pages.

About half of rules have no Options section, such as generator-star, so omit the TOC:
EDIT: Just realized this rule should have an Options section, but you get the idea 😬

About half of rules have Options section with h3 headings, such as comma-dangle:

Only a few rules have Options section with h3 and h4 headings, such as no-shadow:

EDIT and here is a picture of no-shadow with contents limited to h2 and h3:

[IanVS]

I actually really like seeing the options in the TOC, I think that's super-helpful to get a sense for the rule options at-a-glance.

If there's a way to limit to just h3, I think that would be best.

[pedrottimark]

@IanVS What do you think about the picture of Command Line Interface in #256 (comment)

The only h2 headings are Options at the beginning and Ignoring files from linting at the end

Do you think it would make sense to “flatten” the hierarchy: promote the h3 headings like Basic configuraion to h2 and h4 headings like --c, --config to h3?

[IanVS]

Honestly, I think the individual commands in code tags are too much for the TOC as well. I think it would look good with:

Options
    Basic Configuration
    Caching
    Specifying Rules and Plugins
    .
    .
    .
Ignoring Files from Linting

[pedrottimark]

What do you think about this picture?

• unvisited links in same blue as ESLint outer hexagon
• visited links in purple

[omerbalyali]

@pedrottimark This looks better, but maybe a little more blue for unvisited links could be better. But it's already distinctive enough.

[pedrottimark]

@omerbalyali Here is a picture with the “Netscape defaults” for an ahead-to-the-past look, seriously! https://www.w3.org/wiki/Styling_lists_and_links#Example:_recreating_the_Netscape_defaults

• unvisited: blue #0000CC hsl(240,100%,40%)
• visited: purple #660066 hsl(300,100%,20%) differs from the ref, but I am too left-brain for 21%

[pedrottimark]

Here is the rules index with links underlined. If it looks like too much visual complexity, we can make a specific style rule when we replace the lists with tables.

[ilyavolodin]

Underlining brings in too much visual noise. I don't have any preferences for colors, since I don't find it all that useful for documentation site. Just because I visited that link before doesn't mean much to me.

[pedrottimark]

@ilyavolodin Thanks for your clear thinking. The most recent commit gets rid of underline and visited color, changes the link color from 3a33d1 and 272296 on hover to outer hexagon blue 4B32C3 always, because underline appears as visual feedback on hover.

[pedrottimark]

While browsing locally generated site with the proposed format, I noticed about the TOC in rule docs:

• Absence of Options can be misleading, because we have not yet finished consistency editing
• Even then, I made an incorrect assumption about some level-3 headings in the TOC which were property values of an object option instead of simple string options.

Therefore, even a limited table of contents for rule doc pages is on hold.

[nzakas]

Just some additional feedback: it's uncommon to have TOCs on the right of a page. I'd much rather see it on the left or inline.

[mysticatea]

In fact, I have seen sometimes TOCs on the right of a page in Japan. For example:

• http://qiita.com/mysticatea/items/f523dab04a25f617c87d

I think it's good that it doesn't prevent me reading content because we start to read from top-left.

[ilyavolodin]

I'm also good with having TOC on the right. In my mind if TOC is on the left, it's very important to the flow of the information. If it's on the right, it's just a helper (which is what it is in our case).

[IanVS]

I'm another 👍 for the right side. I really like the way it's done on babeljs.io. It serves to orient the user nicely to the content of the page without being in the way.

[ilyavolodin]

Personal preference: I like #1 better. It's much cleaner to me. If we don't want to use colons, then I would rather put rule names into table column, so that they all align.

[nzakas]

I'd like table columns, myself.

[pedrottimark]

Oh, yeah 😀 A fallback for very narrow width will take a bit more thought.

First attempt where cols in separate tables do not align:

Second attempt sets min-width for col from computed max length of ids:

Looks good even down to 600px width equivalent to Nexus 7 in portrait orientation:

[IanVS]

Hmm, that's more difficult to read, IMHO. It's easy to lose your place going from the rule id to its description. I doubt right-aligning the rule IDs would look very good, and I'm not a fan of zebra-striping. Any other thoughts how we could make it easier to track from id to description?

[pedrottimark]

@IanVS What do you think about a dot leader on odd rows?

[IanVS]

Hm, it's better but it seems a little "odd" to have them on every other row (see what I did there? 😜). I assume it's too cluttered-looking to have them on every row?

[nzakas]

Alternating row background colors helps a lot with this. We can probably get away with a light gray on every other row to guide people's eyes.

[pedrottimark]

Here are 3 × 3 pictures of a responsive design for the rules index page:

• At width >= 600px each table has size for its contents. The even rows have a light blue background. The separate description column shows the good work that @alberto and @scriptdaemon did.
• At narrower width, the table cells are styled as inline elements similar to current format.

1a) Beginning of index at screen width 1024px for desktop, laptop, or iPad in landscape orientation

1b) Beginning of index at simulated screen width 600px for Nexus 7 in portrait orientation

1c) Beginning of index at simulated screen width 414px for iPhone 6 Plus in portrait orientation

2a) Middle of index (this is the worst case place for my eyes) at screen width 1024px

2b) Middle of index at screen width 600px

2c) Middle of index at screen width 414px

3a) End of index (the section for Removed rules) at screen width 1024px

3b) End of index at screen width 600px

3c) End of index at screen width 414px

[scriptdaemon]

@pedrottimark That looks great!

Would it make sense to include the background colors behind the "recommended" and "fix" icons? I think it'd be easier on the eyes for some people to identify which rules the icons belong to. What are your thoughts?

[omerbalyali]

Alternating backgrounds (zebra stripes) is the most effective solution but I think gray background color would be better than the purple hue.

For smartphones and tablets, description lines for the rules can start with new line and there can be more margin/padding at the bottom of the each rule row.

By the way, nice work @pedrottimark

[pedrottimark]

Here is another iteration which includes the suggestions in the previous 2 comments.

4a) Variables section (which has fewer icons) at screen width 1024px

4b) Variables section at screen width 600px

4c) Variables section at screen width 414px

[ilyavolodin]

Last iteration looks pretty solid to me. I like the idea of collapsing table in mobile view. Seems like the best use of space.

[nzakas]

Looks nice! Small nitpick would be to give the icons some left/right padding, but otherwise 👍

[pedrottimark]

@nzakas Yes, good eyes! Keep bringing the nitpicks. Every little bit helps.

After I have tested the updated styles on various browsers for current list format and future table format, I will push the changes and summarize them in a comment.

[pedrottimark]

Prerequisites on the site to changes in Makefile.js which will use rule meta data to generate:

• table rows in the index page
• main heading plus removed/recommended/fixable paragraphs in doc pages

The styles are compatible with the current list format. Main goals:

• Add separate layouts rules.html for index page and rule.html for doc pages to include just the relevant replacement rules and to provide distinct classes for CSS selectors. By the way, the script that inserts anchors for heading needs them to have doc class too. Later, we can remove some (or maybe even all) replacement rules from the doc.html layout.
• Add responsive breakpoints for narrow widths based on content and rounded up to device size.
• Limit length of lines except main headings especially for rule docs and tables in rules index:
  • After the consistency editing of rule docs, we might display some information in the right margin on wide screens.
  • If we develop auxiliary categories to make rules easier to find, tables in the rules index might display them at the right.

[pedrottimark]

@omerbalyali Can you share your expert color advice about the following rare situation?

In the original style, there is no color difference between code elements Array.whatever in the bulleted list which are links (children of an a element) and two ordinary code element for return:

In the new style, code elements inherit color from parent: links are blue and others are dark gray:

I noticed something looked different, so I pointed the mouse, and underline appeared to confirm.

• How do you think the blue color on light gray background-color looks?
• Would it help or hurt to have a light blue background-color for a code selector?

[omerbalyali]

@pedrottimark

Light gray (or a blue tint) background for "code" blocks is well known, so this is the best option in my opinion. Maybe there can be a little more padding inside the code blocks. Also I'm really not sure if users can understand that they are links? (Probably they can, at least they will try but again I'm not really sure about it) At least making the normal, non-link code block grayscale differentiates the links and normal code blocks. Again there should be more padding, like 2px. (and maybe the text inside the non-link code block should be darker than the normal text?)

[pedrottimark]

@omerbalyali Brilliant advice. Thank you!

• Restored horizontal padding to 4px same as original style. By the way, I had had to get rid of vertical padding to avoid distraction with zebra stripes in rules index and also multiple lines of some headings.
• Changed color of code element to black (same color as keywords in pre elements) except in headings or links.

[pedrottimark]

Last, but not least, add toc_levels property to kramdown settings in Jekyll config.

[nzakas]

@pedrottimark do you think we're ready to merge?

[pedrottimark]

@nzakas Yes, thank you for your feedback and patience, let’s go for it.

There are immediate changes for readability: limited line length and improved typography.