Docs: Prepare for table of contents

_config.yml

@@ -13,6 +13,7 @@ gems:
     - algoliasearch-jekyll
 kramdown:
   input: GFM
+  toc_levels: 2..3
 algolia:
   application_id: 'XWXG7MEBSB'
   index_name:     'eslint'

_layouts/rule.html

@@ -0,0 +1,20 @@
+{% include header.html %}
+{% include menu.html %}
+<main class="rule doc">
+  <article class="container">
+    {{ content
+      | replace: '<p>Examples of <strong>incorrect</strong> code', '<p class="incorrect icon">Examples of <strong>incorrect</strong> code'
+      | replace: '<p>Example of <strong>incorrect</strong> code', '<p class="incorrect icon">Example of <strong>incorrect</strong> code'
+      | replace: '<p>Examples of additional <strong>incorrect</strong> code', '<p class="incorrect icon">Examples of additional <strong>incorrect</strong> code'
+      | replace: '<p>Example of additional <strong>incorrect</strong> code', '<p class="incorrect icon">Example of additional <strong>incorrect</strong> code'
+      | replace: '<p>Examples of <strong>correct</strong> code', '<p class="correct icon">Examples of <strong>correct</strong> code'
+      | replace: '<p>Example of <strong>correct</strong> code', '<p class="correct icon">Example of <strong>correct</strong> code'
+      | replace: '<p>Examples of additional <strong>correct</strong> code', '<p class="correct icon">Examples of additional <strong>correct</strong> code'
+      | replace: '<p>Example of additional <strong>correct</strong> code', '<p class="correct icon">Example of additional <strong>correct</strong> code'
+      | replace: '<p>(removed) ', '<p class="removed icon">'
+      | replace: '<p>(recommended) ', '<p class="recommended icon">'
+      | replace: '<p>(fixable) ', '<p class="fixable icon">'
+    }}
+  </article>
+</main>
+{% include footer.html %}

_layouts/rules.html

@@ -0,0 +1,11 @@
+{% include header.html %}
+{% include menu.html %}
+<main class="rules doc">
+  <article class="container">
+    {{ content
+      | replace: '(recommended)', '<span title="recommended" aria-label="recommended" class="glyphicon glyphicon-ok"></span>'
+      | replace: '(fixable)', '<span title="fixable" aria-label="fixable" class="glyphicon glyphicon-wrench"></span>'
+    }}
+  </article>
+</main>
+{% include footer.html %}

styles/overrides.css

@@ -2,16 +2,6 @@
   margin-top: 30px;
 }
 
-/* Prevent long code from wrapping, scroll instead */
-code[data-lang] {
-  white-space: pre;
-}
-
-main.doc .highlight pre {
-  overflow-x: auto;
-  word-wrap: normal;
-}
-
 /* We need to push the content because of the fixed header */
 body {
   padding-top: 80px;
@@ -30,46 +20,154 @@ h6:target:before {
   width: 1px;
 }
 
-/* icon margins for rules page */
 .glyphicon {
-  margin: 0 2px;
+  margin: 0 2px; /* margins for icons in ordinary text */
+  color: #4d4d4d; /* hsl(0,0%,30%) is 10% lighter gray than text */
 }
 
-td .glyphicon {
-  margin: 0; /* within table in rules page */
+tr {
+  vertical-align: baseline;
 }
 
 th,
 td {
-  padding-left: 0.5em;
+  padding-left: 0.25em;
+  padding-right: 0.25em;
+}
+
+/* `main.rules` is the selector for tables in the rules index page */
+/* `tbody:first-child` is the selector for tables of active rules */
+/* `thead` or `thead + tbody` are the selectors for table of removed rules */
+
+main.rules table {
+  max-width: none; /* page cannot have toc, because it could overlap wide tables */
+}
+
+main.rules tr:nth-child(even) {
+  background-color: #f4f4f4; /* hsl(0,0%,96%) zebra stripes have same light gray as pre */
+}
+
+main.rules tr:nth-child(even) code {
+  background-color: #eaeaea; /* hsl(0,0%,92%) just enough darker gray to contrast with zebra stripe */
+}
+
+main.rules tbody:first-child td:nth-child(-n+2) { /* selector idiom for first 2 children */
   min-width: 1em; /* width of glyphicon for a column of empty cells */
 }
 
-th:first-child,
-td:first-child {
+main.rules tbody:first-child td:nth-child(-n+2) .glyphicon {
+  margin: 0; /* cell padding instead of icon margin */
+}
+
+/* align ids of removed rules with left edge of preceding heading and paragraph */
+main.rules thead th:nth-child(1),
+main.rules thead + tbody td:nth-child(1) {
   padding-left: 0;
 }
 
-tr {
-  vertical-align: baseline;
+/* breakpoint is based on content and rounded up to device size */
+/* the max length of a rule-id is about 15em = 30 chars / (2 chars/em) */
+/* 595px = 17 px/em * (0.5 + 2 * (0.25 + 1 + 0.25) + 2 * (0.25 + 15 + 0.25) + 0.5) em */
+
+@media (min-width: 600px) {
+
+  /* prevent id from wrapping if next column has wide contents */
+  main.rules tbody:first-child td:nth-child(3),
+  main.rules thead th:nth-child(1),
+  main.rules thead + tbody td:nth-child(1) {
+    white-space: nowrap;
+  }
+
+  /* hanging indent for multiple lines */
+  main.rules tbody:first-child td:nth-child(4), /* description */
+  main.rules thead + tbody td:nth-child(2) { /* replacements */
+    padding-left: 1.25em; /* add indent to ordinary padding */
+    text-indent: -1em;
+  }
+
+}
+
+@media (max-width: 599px) { /* display table as list if width less than 600px */
+
+  main.rules tr {
+    display: block;
+  }
+
+  main.rules tbody:first-child tr {
+    position: relative;
+  }
+
+  main.rules tbody:first-child td {
+    display: block;
+  }
+
+  main.rules tbody:first-child td:nth-child(-n+2) {
+    position: absolute; /* cell position is equivalent to the table columns */
+    top: auto;
+  }
+
+  main.rules tbody:first-child td:nth-child(1) { /* recommended */
+    left: 0; /* td has padding-left */
+  }
+
+  main.rules tbody:first-child td:nth-child(2) { /* fixable */
+    left: 1.5em; /* width of preceding "column" */
+  }
+
+  main.rules tbody:first-child td:nth-child(3) { /* id */
+    padding-left: 3.25em; /* add width of preceding "columns" to ordinary padding */
+  }
+
+  main.rules tbody:first-child td:nth-child(4) { /* description */
+    padding-left: 5.25em; /* on separate line with hanging indent relative to id */
+    text-indent: -1em;
+  }
+
+  main.rules thead tr,
+  main.rules thead + tbody tr {
+    padding-left: 1em; /* do not include ordinary padding */
+    text-indent: -1em;
+  }
+
+  main.rules thead th,
+  main.rules thead + tbody td {
+    display: inline;
+    padding-left: 0;
+    padding-right: 0;
+  }
+
+  main.rules thead th:nth-child(1):after,
+  main.rules thead + tbody td:nth-child(1):after {
+    content: " \2192"; /* rightwards arrow */
+  }
+
 }
 
 p.incorrect + div + div + div > pre, /* vars-on-top */
 p.incorrect + div + div > pre, /* no-continue */
 p.incorrect + div > pre {
-  background-color: #fff6f6; /* light red hsl(0,100%,98%) */
+  background-color: #fff6f6; /* hsl(0,100%,98%) light red */
 }
 
 p.correct + div + div + div > pre, /* vars-on-top */
 p.correct + div + div > pre, /* no-continue */
 p.correct + div > pre {
-  background-color: #f6fff6; /* light green hsl(120,100%,98%) */
+  background-color: #f6fff6; /* hsl(120,100%,98%) light green */
+}
+
+p.icon {
+  position:relative;
 }
 
 p.icon:before {
+  position: absolute;
+  left: -1.5em; /* negative padding-left of ul */
   font-family: "Glyphicons Halflings";
-  color: #4d4d4d; /* gray hsl(0,0%,30%) */
-  margin-right: 0.5em;
+  color: #4d4d4d; /* hsl(0,0%,30%) is 10% lighter gray than text */
+}
+
+p.removed ~ p.fixable:before {
+  color: #ccc; /* hsl(0,0%,80%) light gray */
 }
 
 p.recommended:before {
@@ -92,23 +190,105 @@ p.correct:before {
   content: "\e125"; /* thumbs-up */
 }
 
-@media (min-width: 768px) {
+ol,
+ul {
+  padding-left: 1.5em; /* same as indent for inline glyphicon at narrow width */
+}
 
-  p.icon:before {
-    position: absolute;
-    left: -20px;
+li ul {
+  list-style: disc;
+}
+
+li p ~ ul {
+  margin-bottom: 12px; /* same as p, ol, ul */
+}
+
+.container {
+  position: relative; /* for toc */
+  overflow: hidden; /* for toc */
+  width: auto; /* override media queries */
+  margin-left: 0; /* not centered */
+  margin-right: 0; /* not centered */
+  padding-left: 2em; /* padding-right plus negative left position of glyphicon in margin */
+  padding-right: 0.5em;
+}
+
+#markdown-toc {
+  position: absolute;
+  top: auto; /* aligned at the top of paragraph of content which follows in document order */
+  left: 51em; /* 2 padding + 43 content + 6 gutter */
+  white-space: nowrap;
+  padding-left: 0;
+}
+
+#markdown-toc, /* is itself ul */
+#markdown-toc ul {
+  list-style: none;
+  margin-bottom: 0;
+}
+
+h2 a, h3 a, h4 a, /* anchor link icons */
+#markdown-toc a {
+  color: inherit; /* same as text */
+}
+
+a:active, a:focus, a:hover, /* needed only to override main.css */
+a {
+  color: #4B32C3; /* hsl(250,59%,48%) is same blue as outer hexagon in ESLint logo */
+}
+
+pre {
+  font-size: 15px; /* for similar chars/line as text font */
+  word-break: normal; /* do not break a line within an ordinary word */
+  word-wrap: break-word; /* break an "unbreakable" word only if there are no otherwise-acceptable break points */
+  padding: 12px 2px; /* vertical same as margin-bottom of p and horizontal same as padding of code */
+  border-width: 1px;
+  border-color: #ccc; /* hsl(0,0%,80%) light gray */
+  border-top-style: solid;
+  border-right-style: none;
+  border-bottom-style: solid;
+  border-left-style: none;
+  border-radius: 0; /* needed only to override main.css */
+}
+
+code {
+  font-size: 0.88235em; /* 15px / 17px ratio because it occurs in headings */
+  padding: 0 4px; /* no vertical padding: to separate from zebra stripe in rules index */
+  color: #000000; /* hsl(0,0%,0%) black is darker than text */
+  background-color: #efefef; /* hsl(0,0%,94%) darker than pre and GitHub code */
+  white-space: normal;
+}
+
+h1 code, h2 code, h3 code, h4 code, /* in heading: same dark gray as text */
+a code { /* in link: blue */
+  color: inherit
+}
+
+main h2, main h3, main h4, main p, main ol, main ul, main table, main div.highlighter-rouge {
+  max-width: 43em; /* about 3 alphabets and just enough for 80 characters in pre */
+}
+
+/* breakpoint is based on content and rounded up to device size */
+/* 765px = 17 px/em * (2 padding + 43 content) em */
+@media (max-width: 767px) { /* width less than 768px */
+
+  .container {
+    padding-left: 0.5em; /* same as padding-right */
   }
 
-  p.icon {
-    position:relative;
+  p.icon:before {
+    position: static;
+    margin-right: 0.5em; /* margin plus glyphicon width is same as padding-left of ul */
   }
 
 }
 
-@media (max-width: 767px) {
+/* breakpoint is based on content and rounded up to device size */
+/* 1020px = 17 px/em * (2 padding + 43 content + 6 gutter + 9 toc) em */
+@media (max-width: 1023px) { /* less than 1024px */
 
-  code {
-    white-space: normal;
+  #markdown-toc {
+    display: none;
   }
 
 }