From 7cfc63e1384d91548fc25810a544b07daacca9d0 Mon Sep 17 00:00:00 2001 From: Henrique Vianna Date: Mon, 1 Jun 2020 14:35:15 -0300 Subject: [PATCH 01/48] Fix native font stack precedence issue on Windows systems. --- _sass/custom/custom.scss | 2 +- _sass/support/_variables.scss | 2 +- docs/ui-components/typography.md | 2 +- 3 files changed, 3 insertions(+), 3 deletions(-) diff --git a/_sass/custom/custom.scss b/_sass/custom/custom.scss index 9ac503b..b608d93 100644 --- a/_sass/custom/custom.scss +++ b/_sass/custom/custom.scss @@ -2,7 +2,7 @@ //// Typography //// -//$body-font-family: -apple-system, BlinkMacSystemFont, "helvetica neue", helvetica, roboto, noto, "segoe ui", arial, sans-serif; +//$body-font-family: -apple-system, BlinkMacSystemFont, "helvetica neue", "segoe ui", helvetica, roboto, noto, arial, sans-serif; //$mono-font-family: "SFMono-Regular", Menlo, Consolas, Monospace; //$root-font-size: 16px; // Base font-size for rems //$body-line-height: 1.4; diff --git a/_sass/support/_variables.scss b/_sass/support/_variables.scss index 76d8b5d..8ee5399 100644 --- a/_sass/support/_variables.scss +++ b/_sass/support/_variables.scss @@ -3,7 +3,7 @@ // $body-font-family: -apple-system, BlinkMacSystemFont, "helvetica neue", - helvetica, roboto, noto, "segoe ui", arial, sans-serif !default; + "segoe ui", helvetica, roboto, noto, arial, sans-serif !default; $mono-font-family: "SFMono-Regular", Menlo, Consolas, Monospace !default; $root-font-size: 16px !default; // Base font-size for rems $body-line-height: 1.4 !default; diff --git a/docs/ui-components/typography.md b/docs/ui-components/typography.md index 2838a79..3db988c 100644 --- a/docs/ui-components/typography.md +++ b/docs/ui-components/typography.md @@ -21,7 +21,7 @@ nav_order: 1 By default, Just the Docs uses a native system font stack for sans-serif fonts: ```scss --apple-system, BlinkMacSystemFont, "helvetica neue", helvetica, roboto, noto, "segoe ui", arial, sans-serif +-apple-system, BlinkMacSystemFont, "helvetica neue", "segoe ui", helvetica, roboto, noto, arial, sans-serif ``` ABCDEFGHIJKLMNOPQRSTUVWXYZ From d7050b3f044e797465efc2bae370a9a10375d130 Mon Sep 17 00:00:00 2001 From: marksie1988 Date: Fri, 26 Jun 2020 10:08:11 +0100 Subject: [PATCH 02/48] :star: change to relative_url --- _includes/head.html | 8 ++++---- _includes/nav.html | 10 +++++----- 2 files changed, 9 insertions(+), 9 deletions(-) diff --git a/_includes/head.html b/_includes/head.html index eae6a5e..79c7d34 100644 --- a/_includes/head.html +++ b/_includes/head.html @@ -10,9 +10,9 @@ {% endif %} {% endif %} - + - + {% if site.ga_tracking != nil %} @@ -27,9 +27,9 @@ {% endif %} {% if site.search_enabled != false %} - + {% endif %} - + diff --git a/_includes/nav.html b/_includes/nav.html index d561a42..92dbbcf 100644 --- a/_includes/nav.html +++ b/_includes/nav.html @@ -6,24 +6,24 @@ {%- if node.parent == nil -%}
  • {%- if page.parent == node.title or page.grand_parent == node.title -%} - {%- assign first_level_url = node.url | absolute_url -%} + {%- assign first_level_url = node.url | relative_url -%} {%- endif -%} - {{ node.title }} + {{ node.title }} {%- if node.has_children -%} {%- assign children_list = site.html_pages | where: "parent", node.title | sort:"nav_order" -%}
      {%- for child in children_list -%}
    • {%- if page.url == child.url or page.parent == child.title -%} - {%- assign second_level_url = child.url | absolute_url -%} + {%- assign second_level_url = child.url | relative_url -%} {%- endif -%} - {{ child.title }} + {{ child.title }} {%- if child.has_children -%} {%- assign grand_children_list = site.html_pages | where: "parent", child.title | sort:"nav_order" -%} From 88759c1cf7b86796ae103c353ffea2261c31c099 Mon Sep 17 00:00:00 2001 From: marksie1988 Date: Fri, 26 Jun 2020 11:41:50 +0100 Subject: [PATCH 03/48] :star: change to relative_url --- lib/tasks/search.rake | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/lib/tasks/search.rake b/lib/tasks/search.rake index 5c03790..1bc762c 100644 --- a/lib/tasks/search.rake +++ b/lib/tasks/search.rake @@ -16,7 +16,7 @@ namespace :search do {% for page in site.html_pages %}{% if page.search_exclude != true %}{% if comma == true%},{% endif %}"{{ forloop.index0 }}": { "title": "{{ page.title | replace: \'&\', \'&\' }}", "content": "\'+content+\'", - "url": "{{ page.url | absolute_url }}", + "url": "{{ page.url | relative_url }}", "relUrl": "{{ page.url }}" }{% assign comma = true %} {% endif %}{% endfor %} From 160cc42e4eeff8cc8dabc2b9195570178fed37ce Mon Sep 17 00:00:00 2001 From: marksie1988 Date: Fri, 26 Jun 2020 11:59:37 +0100 Subject: [PATCH 04/48] show logo on closed nav --- _sass/utilities/_print.scss | 12 ++++++++++++ _sass/utilities/utilities.scss | 1 + 2 files changed, 13 insertions(+) create mode 100644 _sass/utilities/_print.scss diff --git a/_sass/utilities/_print.scss b/_sass/utilities/_print.scss new file mode 100644 index 0000000..6a989b8 --- /dev/null +++ b/_sass/utilities/_print.scss @@ -0,0 +1,12 @@ +@media print{ + .side-bar{ + width: 100%; + height: auto; + .main-nav, footer{ + display: none; + } + } + .main-content{ + margin-left: 20px; + } +} diff --git a/_sass/utilities/utilities.scss b/_sass/utilities/utilities.scss index 6c25bdf..921bb57 100644 --- a/_sass/utilities/utilities.scss +++ b/_sass/utilities/utilities.scss @@ -3,3 +3,4 @@ @import "./typography"; @import "./lists"; @import "./spacing"; +@import "./print"; From 040bef90bb96f15872a4103bbef67f90a7f0efcf Mon Sep 17 00:00:00 2001 From: marksie1988 Date: Fri, 26 Jun 2020 13:42:32 +0100 Subject: [PATCH 05/48] change for https --- _sass/utilities/_print.scss | 12 ------------ _sass/utilities/utilities.scss | 1 - 2 files changed, 13 deletions(-) delete mode 100644 _sass/utilities/_print.scss diff --git a/_sass/utilities/_print.scss b/_sass/utilities/_print.scss deleted file mode 100644 index 6a989b8..0000000 --- a/_sass/utilities/_print.scss +++ /dev/null @@ -1,12 +0,0 @@ -@media print{ - .side-bar{ - width: 100%; - height: auto; - .main-nav, footer{ - display: none; - } - } - .main-content{ - margin-left: 20px; - } -} diff --git a/_sass/utilities/utilities.scss b/_sass/utilities/utilities.scss index 921bb57..6c25bdf 100644 --- a/_sass/utilities/utilities.scss +++ b/_sass/utilities/utilities.scss @@ -3,4 +3,3 @@ @import "./typography"; @import "./lists"; @import "./spacing"; -@import "./print"; From 87a59ef8ef28bad9492843b0226a841073cd472f Mon Sep 17 00:00:00 2001 From: Paul DeBruicker Date: Fri, 26 Jun 2020 11:35:58 -0700 Subject: [PATCH 06/48] make font-sizes sass variables so they can be changed --- _sass/support/mixins/_typography.scss | 52 ++++++++++++++++----------- 1 file changed, 32 insertions(+), 20 deletions(-) diff --git a/_sass/support/mixins/_typography.scss b/_sass/support/mixins/_typography.scss index 1718a93..02e5b86 100644 --- a/_sass/support/mixins/_typography.scss +++ b/_sass/support/mixins/_typography.scss @@ -1,86 +1,98 @@ // Font size +$font-size-1: 9px; +$font-size-1-mq: 10px; +$font-size-2: 11px; //h4 - uppercased!, h6 not uppercased, text-small +$font-size-3: 12px; //h5 +$font-size-4: 15px; +$font-size-5: 16px; //h3 +$font-size-6: 18px; //h2 +$font-size-7: 24px; +$font-size-8: 32px;//h1 +$font-size-9: 36px; +$font-size-10: 42px; +$font-size-10-mq: 48px; @mixin fs-1 { - font-size: 9px !important; + font-size: $font-size-1 !important; @include mq(sm) { - font-size: 10px !important; + font-size: $font-size-1-mq !important; } } @mixin fs-2 { - font-size: 11px !important; + font-size: $font-size-2 !important; @include mq(sm) { - font-size: 12px !important; + font-size: $font-size-3 !important; } } @mixin fs-3 { - font-size: 12px !important; + font-size: $font-size-3 !important; @include mq(sm) { - font-size: 14px !important; + font-size: $font-size-4 !important; } } @mixin fs-4 { - font-size: 15px !important; + font-size: $font-size-4 !important; @include mq(sm) { - font-size: 16px !important; + font-size: $font-size-5 !important; } } @mixin fs-5 { - font-size: 16px !important; + font-size: $font-size-5 !important; @include mq(sm) { - font-size: 18px !important; + font-size: $font-size-6 !important; } } @mixin fs-6 { - font-size: 18px !important; + font-size: $font-size-6 !important; @include mq(sm) { - font-size: 24px !important; + font-size: $font-size-7 !important; line-height: $body-heading-line-height; } } @mixin fs-7 { - font-size: 24px !important; + font-size: $font-size-7 !important; line-height: $body-heading-line-height; @include mq(sm) { - font-size: 32px !important; + font-size: $font-size-8 !important; } } @mixin fs-8 { - font-size: 32px !important; + font-size: $font-size-8 !important; line-height: $body-heading-line-height; @include mq(sm) { - font-size: 36px !important; + font-size: $font-size-9!important; } } @mixin fs-9 { - font-size: 36px !important; + font-size: $font-size-9 !important; line-height: $body-heading-line-height; @include mq(sm) { - font-size: 42px !important; + font-size: $font-size-10 !important; } } @mixin fs-10 { - font-size: 42px !important; + font-size: $font-size-10 !important; line-height: $body-heading-line-height; @include mq(sm) { - font-size: 48px !important; + font-size: $font-size-10-mq !important; } } From d3d17c0460a0d3db037f29c7e2d8bcaeca227398 Mon Sep 17 00:00:00 2001 From: marksie1988 Date: Sat, 27 Jun 2020 10:02:36 +0100 Subject: [PATCH 07/48] fix conflicts --- _includes/nav.html | 106 ++++++++++++++++++++++-------------------- lib/tasks/search.rake | 63 +++++++++++++++++++++---- 2 files changed, 109 insertions(+), 60 deletions(-) diff --git a/_includes/nav.html b/_includes/nav.html index e41f79e..8f0b089 100644 --- a/_includes/nav.html +++ b/_includes/nav.html @@ -1,51 +1,55 @@ - +
        + {%- assign ordered_pages_list = site.html_pages | where_exp:"item", "item.nav_order != nil" -%} + {%- assign unordered_pages_list = site.html_pages | where_exp:"item", "item.nav_order == nil" -%} + {%- if site.nav_sort == 'case_insensitive' -%} + {%- assign sorted_ordered_pages_list = ordered_pages_list | sort_natural:"nav_order" -%} + {%- assign sorted_unordered_pages_list = unordered_pages_list | sort_natural:"title" -%} + {%- else -%} + {%- assign sorted_ordered_pages_list = ordered_pages_list | sort:"nav_order" -%} + {%- assign sorted_unordered_pages_list = unordered_pages_list | sort:"title" -%} + {%- endif -%} + {%- assign pages_list = sorted_ordered_pages_list | concat: sorted_unordered_pages_list -%} + {%- for node in pages_list -%} + {%- unless node.nav_exclude -%} + {%- if node.parent == nil and node.title -%} +
      • + {%- if page.parent == node.title or page.grand_parent == node.title -%} + {%- assign first_level_url = node.url | relative_url -%} + {%- endif -%} + {%- if node.has_children -%} + + {%- endif -%} + {{ node.title }} + {%- if node.has_children -%} + {%- assign children_list = pages_list | where: "parent", node.title -%} +
          + {%- for child in children_list -%} + {%- unless child.nav_exclude -%} +
        • + {%- if page.url == child.url or page.parent == child.title -%} + {%- assign second_level_url = child.url | relative_url -%} + {%- endif -%} + {%- if child.has_children -%} + + {%- endif -%} + {{ child.title }} + {%- if child.has_children -%} + {%- assign grand_children_list = pages_list | where: "parent", child.title | where: "grand_parent", node.title -%} + + {%- endif -%} +
          • + {%- endunless -%} + {%- endfor -%} +
        + {%- endif -%} +
        • + {%- endif -%} + {%- endunless -%} + {%- endfor -%} +
      diff --git a/lib/tasks/search.rake b/lib/tasks/search.rake index 163fb03..6b0900e 100644 --- a/lib/tasks/search.rake +++ b/lib/tasks/search.rake @@ -3,23 +3,68 @@ namespace :search do task :init do puts 'Creating search data json file...' mkdir_p 'assets/js' - touch 'assets/js/search-data.json' - content = %Q[{{ page.content | markdownify | replace: '\' -%} + {%- assign title = titleAndContent[0] | replace_first: \'>\', \'

      \' | split: \'

      \' -%} + {%- assign title = title[1] | strip_html -%} + {%- assign content = titleAndContent[1] -%} + {%- assign url = page.url -%} + {%- if title == page.title and parts[0] == \'\' -%} + {%- assign title_found = true -%} + {%- else -%} + {%- assign id = titleAndContent[0] -%} + {%- assign id = id | split: \'id="\' -%} + {%- if id.size == 2 -%} + {%- assign id = id[1] -%} + {%- assign id = id | split: \'"\' -%} + {%- assign id = id[0] -%} + {%- capture url -%}{{ url | append: \'#\' | append: id }}{%- endcapture -%} + {%- endif -%} + {%- endif -%} + {%- unless i == 0 -%},{%- endunless -%} + "{{ i }}": { + "doc": {{ page.title | jsonify }}, + "title": {{ title | jsonify }}, + "content": {{ content | replace: \' Date: Sat, 27 Jun 2020 17:37:39 -0300 Subject: [PATCH 08/48] Updated native font stack, as suggested in https://github.com/pmarsceill/just-the-docs/issues/330#issuecomment-650415240 --- _sass/support/_variables.scss | 4 ++-- docs/ui-components/typography.md | 2 +- 2 files changed, 3 insertions(+), 3 deletions(-) diff --git a/_sass/support/_variables.scss b/_sass/support/_variables.scss index bca9a71..d169eba 100644 --- a/_sass/support/_variables.scss +++ b/_sass/support/_variables.scss @@ -2,8 +2,8 @@ // Typography // -$body-font-family: -apple-system, BlinkMacSystemFont, "helvetica neue", - "segoe ui", helvetica, roboto, noto, arial, sans-serif !default; +$body-font-family: system-ui, -apple-system, BlinkMacSystemFont, "Segoe UI", + Roboto, "Helvetica Neue", Arial, sans-serif !default; $mono-font-family: "SFMono-Regular", Menlo, Consolas, Monospace !default; $root-font-size: 16px !default; // Base font-size for rems $body-line-height: 1.4 !default; diff --git a/docs/ui-components/typography.md b/docs/ui-components/typography.md index 3db988c..b879c95 100644 --- a/docs/ui-components/typography.md +++ b/docs/ui-components/typography.md @@ -21,7 +21,7 @@ nav_order: 1 By default, Just the Docs uses a native system font stack for sans-serif fonts: ```scss --apple-system, BlinkMacSystemFont, "helvetica neue", "segoe ui", helvetica, roboto, noto, arial, sans-serif +system-ui, -apple-system, BlinkMacSystemFont, "Segoe UI", Roboto, "Helvetica Neue", Arial, sans-serif ``` ABCDEFGHIJKLMNOPQRSTUVWXYZ From d90482d7194119611163f98c90e6ea1f3a560ba9 Mon Sep 17 00:00:00 2001 From: Paul DeBruicker Date: Sun, 28 Jun 2020 14:52:15 -0700 Subject: [PATCH 09/48] put the font size variables in variables.scss and rename the ones misnamed -mq --- _sass/support/_variables.scss | 14 ++++++++++++++ _sass/support/mixins/_typography.scss | 18 ++---------------- 2 files changed, 16 insertions(+), 16 deletions(-) diff --git a/_sass/support/_variables.scss b/_sass/support/_variables.scss index 3665a36..f32c65b 100644 --- a/_sass/support/_variables.scss +++ b/_sass/support/_variables.scss @@ -10,6 +10,20 @@ $body-line-height: 1.4 !default; $content-line-height: 1.6 !default; $body-heading-line-height: 1.25 !default; +// Font size +$font-size-1: 9px; +$font-size-1-sm: 10px; +$font-size-2: 11px; //h4 - uppercased!, h6 not uppercased, text-small +$font-size-3: 12px; //h5 +$font-size-4: 15px; +$font-size-5: 16px; //h3 +$font-size-6: 18px; //h2 +$font-size-7: 24px; +$font-size-8: 32px;//h1 +$font-size-9: 36px; +$font-size-10: 42px; +$font-size-10-sm: 48px; + // // Colors // diff --git a/_sass/support/mixins/_typography.scss b/_sass/support/mixins/_typography.scss index 02e5b86..62b7812 100644 --- a/_sass/support/mixins/_typography.scss +++ b/_sass/support/mixins/_typography.scss @@ -1,22 +1,8 @@ -// Font size -$font-size-1: 9px; -$font-size-1-mq: 10px; -$font-size-2: 11px; //h4 - uppercased!, h6 not uppercased, text-small -$font-size-3: 12px; //h5 -$font-size-4: 15px; -$font-size-5: 16px; //h3 -$font-size-6: 18px; //h2 -$font-size-7: 24px; -$font-size-8: 32px;//h1 -$font-size-9: 36px; -$font-size-10: 42px; -$font-size-10-mq: 48px; - @mixin fs-1 { font-size: $font-size-1 !important; @include mq(sm) { - font-size: $font-size-1-mq !important; + font-size: $font-size-1-sm !important; } } @@ -93,6 +79,6 @@ $font-size-10-mq: 48px; line-height: $body-heading-line-height; @include mq(sm) { - font-size: $font-size-10-mq !important; + font-size: $font-size-10-sm !important; } } From e8d60818ed4c78250392af3104c36ef6741486a3 Mon Sep 17 00:00:00 2001 From: Patrick Marsceill Date: Tue, 30 Jun 2020 12:46:44 -0400 Subject: [PATCH 10/48] Update _variables.scss --- _sass/support/_variables.scss | 28 ++++++++++++++++------------ 1 file changed, 16 insertions(+), 12 deletions(-) diff --git a/_sass/support/_variables.scss b/_sass/support/_variables.scss index f32c65b..ff32267 100644 --- a/_sass/support/_variables.scss +++ b/_sass/support/_variables.scss @@ -10,19 +10,23 @@ $body-line-height: 1.4 !default; $content-line-height: 1.6 !default; $body-heading-line-height: 1.25 !default; +// // Font size -$font-size-1: 9px; -$font-size-1-sm: 10px; -$font-size-2: 11px; //h4 - uppercased!, h6 not uppercased, text-small -$font-size-3: 12px; //h5 -$font-size-4: 15px; -$font-size-5: 16px; //h3 -$font-size-6: 18px; //h2 -$font-size-7: 24px; -$font-size-8: 32px;//h1 -$font-size-9: 36px; -$font-size-10: 42px; -$font-size-10-sm: 48px; +// `-sm` suffix is the size at the small (and above) media query +// + +$font-size-1: 9px !default; +$font-size-1-sm: 10px !default; +$font-size-2: 11px !default; //h4 - uppercased!, h6 not uppercased, text-small +$font-size-3: 12px !default; //h5 +$font-size-4: 15px !default; +$font-size-5: 16px !default; //h3 +$font-size-6: 18px !default; //h2 +$font-size-7: 24px !default; +$font-size-8: 32px !default; //h1 +$font-size-9: 36px !default; +$font-size-10: 42px !default; +$font-size-10-sm: 48px !default; // // Colors From b41f28dadee8fe5e02b168341f4b5b46f97f0175 Mon Sep 17 00:00:00 2001 From: PLanCompS <18308236+pdmosses@users.noreply.github.com> Date: Sat, 4 Jul 2020 19:21:49 +0200 Subject: [PATCH 11/48] Support for the linenos option on highlighted code The added examples in `docs/index-test.md` extend the previous examplees of highlighting, documenting the required inout. --- _includes/fix_linenos.html | 33 +++++++++++++++++++ _sass/code.scss | 67 ++++++++++++++++++++++++++++++++++++++ docs/index-test.md | 34 ++++++++++++++++++- 3 files changed, 133 insertions(+), 1 deletion(-) create mode 100644 _includes/fix_linenos.html diff --git a/_includes/fix_linenos.html b/_includes/fix_linenos.html new file mode 100644 index 0000000..bf60027 --- /dev/null +++ b/_includes/fix_linenos.html @@ -0,0 +1,33 @@ +{% comment -%} +Fixes the HTML for highlighted code with linenos. + +Derived from the workaround provided by Dmitry Hrabrov (DeXP) at +https://github.com/penibelst/jekyll-compress-html/issues/71#issuecomment-188144901 + +Explanation: + +The HTML produced by Rouge with the linenos option matches CSS `code table`. +Jekyll (<= 4.1.1) always wraps the highlighted HTML with `pre`, which is +unnecessary and non-conforming, and leads to validation error reports. +The fix removes the `pre` tags around `_code` whenever it contains the pattern +``. This change avoids validation errors, and +allows the use of [Jekyll layout for compressing HTML](http://jch.penibelst.de), +which relies on `pre` tags not being nested. + +Usage: + +{% capture fix_linenos_code %}{% highlight AnyLanguage linenos %} +Some code +{% endhighlight %}{% endcapture %}{% include fix_linenos.html %}{{ fix_linenos_code }} + +Caveats: + +The above does not work when `Some code` happens to contain the matched string +`
      `. + +{%- endcomment %} + +{% if fix_linenos_code contains '
      ' %} + {% assign fix_linenos_code = fix_linenos_code | replace: "
      ", "" %} +{% endif %} diff --git a/_sass/code.scss b/_sass/code.scss index affc8aa..397f0f0 100644 --- a/_sass/code.scss +++ b/_sass/code.scss @@ -26,6 +26,73 @@ figure.highlight { } } +// Using Liquid tags for highlighting, optionally with linenos +// +// See docs/index-test.md for tests + +// Without linenos: figure.highlight > pre > code > div > span* + +figure.highlight { + padding: 0; + margin-top: 0; + margin-bottom: $sp-3; + background-color: $code-background-color; + border-radius: $border-radius; + -webkit-overflow-scrolling: touch; + + pre { + padding: $sp-3; + margin-top: 0; + margin-bottom: 0; + } +} + +// With linenos: + +figure.highlight > pre > code, figure.highlight > code +{ + +td, td > pre { + @include fs-2; + min-width: 0; + padding: 0; + background-color: $code-background-color; + border-bottom: none; + border-left: none; +} + +td.gutter { + padding-right: 1rem; +} + +pre { + line-height: 2; + margin-top: 0; +} + +tbody > tr > td { + border-bottom: none; + padding-bottom: 0; +} + +} + +// Jekyll 4.1.1: figure.highlight > pre > code > div > table > ... + +figure.highlight > pre > code .table-wrapper { + padding: 0; + margin-bottom: 0; + box-shadow: none; + border: none; +} + +// Using fix_linenos: figure.highlight > code > div > table > ... + +figure.highlight > code .table-wrapper { + padding: $sp-3; +} + + .highlighter-rouge { margin-bottom: $sp-3; } diff --git a/docs/index-test.md b/docs/index-test.md index 967ba6f..ec1239b 100644 --- a/docs/index-test.md +++ b/docs/index-test.md @@ -33,12 +33,44 @@ var fun = function lang(l) { ``` ```ruby -# Ruby code with syntax highlighting +# Ruby code with syntax highlighting in fences GitHubPages::Dependencies.gems.each do |gem, version| s.add_dependency(gem, "= #{version}") end ``` +{% highlight ruby %} +# Ruby code with syntax highlighting using Liquid +GitHubPages::Dependencies.gems.each do |gem, version| + s.add_dependency(gem, "= #{version}") +end +{% endhighlight %} + +{% capture fix_linenos_code %}{% highlight ruby linenos %} +# Ruby code with syntax highlighting and fixed line numbers using Liquid +GitHubPages::Dependencies.gems.each do |gem, version| + s.add_dependency(gem, "= #{version}") +end +{% endhighlight %}{% endcapture %}{% include fix_linenos.html %}{{ fix_linenos_code }} + +{% comment %} + +The code example below requires the following setting in `_config.yml`: +```yaml +compress_html: + ignore: + envs: all +``` + +{% highlight ruby linenos %} +# Ruby code with syntax highlighting and unfixed line numbers using Liquid +GitHubPages::Dependencies.gems.each do |gem, version| + s.add_dependency(gem, "= #{version}") +end +{% endhighlight %} + +{% endcomment %} + #### [](#header-4)Header 4 * This is an unordered list following a header. From 7df7572d913e44b0cbbe824ff6574c5059a44a9b Mon Sep 17 00:00:00 2001 From: PLanCompS <18308236+pdmosses@users.noreply.github.com> Date: Sat, 4 Jul 2020 21:12:00 +0200 Subject: [PATCH 12/48] Update code.scss Correected layout, order, values. --- _sass/code.scss | 50 ++++++++++++++++++++++++------------------------- 1 file changed, 25 insertions(+), 25 deletions(-) diff --git a/_sass/code.scss b/_sass/code.scss index 397f0f0..0d70d1a 100644 --- a/_sass/code.scss +++ b/_sass/code.scss @@ -43,37 +43,37 @@ figure.highlight { pre { padding: $sp-3; margin-top: 0; - margin-bottom: 0; + margin-bottom: 0; } } -// With linenos: +// With linenos: -figure.highlight > pre > code, figure.highlight > code -{ +figure.highlight > pre > code, figure.highlight > code { -td, td > pre { - @include fs-2; - min-width: 0; - padding: 0; - background-color: $code-background-color; - border-bottom: none; - border-left: none; -} + td, + td > pre { + @include fs-2; + min-width: 0; + padding: 0; + background-color: $code-background-color; + border-bottom: 0; + border-left: 0; + } -td.gutter { - padding-right: 1rem; -} - -pre { - line-height: 2; - margin-top: 0; -} + td.gutter { + padding-right: 1rem; + } + + pre { + margin-top: 0; + line-height: 2; + } -tbody > tr > td { - border-bottom: none; - padding-bottom: 0; -} + tbody > tr > td { + padding-bottom: 0; + border-bottom: 0; + } } @@ -82,8 +82,8 @@ tbody > tr > td { figure.highlight > pre > code .table-wrapper { padding: 0; margin-bottom: 0; + border: 0; box-shadow: none; - border: none; } // Using fix_linenos: figure.highlight > code > div > table > ... From 74845b4a0ee24907b624ae993d9a912eadd758c5 Mon Sep 17 00:00:00 2001 From: PLanCompS <18308236+pdmosses@users.noreply.github.com> Date: Sat, 4 Jul 2020 21:17:18 +0200 Subject: [PATCH 13/48] Update code.scss Fixed more layout details. Numbers of selectors still to be fixed. --- _sass/code.scss | 7 +++---- 1 file changed, 3 insertions(+), 4 deletions(-) diff --git a/_sass/code.scss b/_sass/code.scss index 0d70d1a..72fa336 100644 --- a/_sass/code.scss +++ b/_sass/code.scss @@ -49,7 +49,8 @@ figure.highlight { // With linenos: -figure.highlight > pre > code, figure.highlight > code { +figure.highlight > pre > code, +figure.highlight > code { td, td > pre { @@ -64,7 +65,7 @@ figure.highlight > pre > code, figure.highlight > code { td.gutter { padding-right: 1rem; } - + pre { margin-top: 0; line-height: 2; @@ -74,7 +75,6 @@ figure.highlight > pre > code, figure.highlight > code { padding-bottom: 0; border-bottom: 0; } - } // Jekyll 4.1.1: figure.highlight > pre > code > div > table > ... @@ -92,7 +92,6 @@ figure.highlight > code .table-wrapper { padding: $sp-3; } - .highlighter-rouge { margin-bottom: $sp-3; } From fdaf5a276bab46b0006b6787e2c1137a4ed4615c Mon Sep 17 00:00:00 2001 From: PLanCompS <18308236+pdmosses@users.noreply.github.com> Date: Mon, 6 Jul 2020 15:04:30 +0200 Subject: [PATCH 14/48] Moved tests from index-test.md to linenos-test.md This should revert the changes made to index-test.md --- docs/index-test.md | 34 +-------------------------- docs/linenos-test.md | 56 ++++++++++++++++++++++++++++++++++++++++++++ 2 files changed, 57 insertions(+), 33 deletions(-) create mode 100644 docs/linenos-test.md diff --git a/docs/index-test.md b/docs/index-test.md index ec1239b..967ba6f 100644 --- a/docs/index-test.md +++ b/docs/index-test.md @@ -33,44 +33,12 @@ var fun = function lang(l) { ``` ```ruby -# Ruby code with syntax highlighting in fences +# Ruby code with syntax highlighting GitHubPages::Dependencies.gems.each do |gem, version| s.add_dependency(gem, "= #{version}") end ``` -{% highlight ruby %} -# Ruby code with syntax highlighting using Liquid -GitHubPages::Dependencies.gems.each do |gem, version| - s.add_dependency(gem, "= #{version}") -end -{% endhighlight %} - -{% capture fix_linenos_code %}{% highlight ruby linenos %} -# Ruby code with syntax highlighting and fixed line numbers using Liquid -GitHubPages::Dependencies.gems.each do |gem, version| - s.add_dependency(gem, "= #{version}") -end -{% endhighlight %}{% endcapture %}{% include fix_linenos.html %}{{ fix_linenos_code }} - -{% comment %} - -The code example below requires the following setting in `_config.yml`: -```yaml -compress_html: - ignore: - envs: all -``` - -{% highlight ruby linenos %} -# Ruby code with syntax highlighting and unfixed line numbers using Liquid -GitHubPages::Dependencies.gems.each do |gem, version| - s.add_dependency(gem, "= #{version}") -end -{% endhighlight %} - -{% endcomment %} - #### [](#header-4)Header 4 * This is an unordered list following a header. diff --git a/docs/linenos-test.md b/docs/linenos-test.md new file mode 100644 index 0000000..48e9603 --- /dev/null +++ b/docs/linenos-test.md @@ -0,0 +1,56 @@ +--- +layout: default +title: Markdown line number test +nav_order: 999 +--- + +``` +Some unknown code in fences +``` + +Some of the code examples below require the following setting in `_config.yml`: +```yaml +compress_html: + ignore: + envs: all +``` + +```js +// Javascript code with syntax highlighting in fences +var fun = function lang(l) { + dateformat.i18n = require('./lang/' + l) + return true; +} +``` + +```ruby +# Ruby code with syntax highlighting in fences +GitHubPages::Dependencies.gems.each do |gem, version| + s.add_dependency(gem, "= #{version}") +end +``` + +{% highlight ruby %} +# Ruby code with syntax highlighting using Liquid +GitHubPages::Dependencies.gems.each do |gem, version| + s.add_dependency(gem, "= #{version}") +end +{% endhighlight %} + +{% capture code %} +{% highlight ruby linenos %} +# Ruby code with syntax highlighting and fixed line numbers using Liquid +GitHubPages::Dependencies.gems.each do |gem, version| + s.add_dependency(gem, "= #{version}") +end +{% endhighlight %} +{% endcapture %} +{% include fix_linenos.html code=code %} +{% assign code = nil %} + +{% highlight ruby linenos %} +# Ruby code with syntax highlighting and unfixed line numbers using Liquid +GitHubPages::Dependencies.gems.each do |gem, version| + s.add_dependency(gem, "= #{version}") +end +{% endhighlight %} From b73300595b679c4b6532107b955f30c3195c0ba3 Mon Sep 17 00:00:00 2001 From: PLanCompS <18308236+pdmosses@users.noreply.github.com> Date: Mon, 6 Jul 2020 15:07:53 +0200 Subject: [PATCH 15/48] Simplified the use of fix_linenos Now using an include parameter. Enhanced to support Markdown with code fences. --- _includes/fix_linenos.html | 68 ++++++++++++++++++++++++++++---------- 1 file changed, 50 insertions(+), 18 deletions(-) diff --git a/_includes/fix_linenos.html b/_includes/fix_linenos.html index bf60027..6243fb0 100644 --- a/_includes/fix_linenos.html +++ b/_includes/fix_linenos.html @@ -1,33 +1,65 @@ -{% comment -%} -Fixes the HTML for highlighted code with linenos. +{%- comment -%} +This file can be used to fix the HTML produced by Jekyll for highlighted +code with line numbers. -Derived from the workaround provided by Dmitry Hrabrov (DeXP) at +It works with `{% highlight some_language linenos %}...{% endhighlight %}` +and with the Kramdown option to add line numbers to fenced code. + +The implementation was derived from the workaround provided by +Dmitry Hrabrov (DeXP) at https://github.com/penibelst/jekyll-compress-html/issues/71#issuecomment-188144901 -Explanation: +EXPLANATION -The HTML produced by Rouge with the linenos option matches CSS `code table`. -Jekyll (<= 4.1.1) always wraps the highlighted HTML with `pre`, which is -unnecessary and non-conforming, and leads to validation error reports. -The fix removes the `pre` tags around `_code` whenever it contains the pattern -`
      `. This change avoids validation errors, and -allows the use of [Jekyll layout for compressing HTML](http://jch.penibelst.de), -which relies on `pre` tags not being nested. +The HTML produced by Rouge highlighting with lie numbers is of the form +`code table`. Jekyll (<= 4.1.1) always wraps the highlighted HTML +with `pre`. This wrapping is not only unnecessary, but also transforms +the conforming HTML produced by Rouge to non-conforming HTML, which +results in HTML validation error reports. -Usage: +The fix removes the outer `pre` tags whenever they contain the pattern +`
      `. + +Apart from avoiding HTML validation errors, the fix allows the use of +the [Jekyll layout for compressing HTML](http://jch.penibelst.de), +which relies on `pre` tags not being nested, according to +https://github.com/penibelst/jekyll-compress-html/issues/71#issuecomment-172069842 -{% capture fix_linenos_code %}{% highlight AnyLanguage linenos %} +USAGE + +(Any names can be used for `some_var` and `some_language`.) + +{% capture some_var %} +{% highlight some_language linenos %} Some code -{% endhighlight %}{% endcapture %}{% include fix_linenos.html %}{{ fix_linenos_code }} +{% endhighlight %} +{% endcapture %} +{% include fix_linenos.html code=some_var %} -Caveats: +For code fences: + +{% capture some_var %} +```some_language +Some code +``` +{% endcapture %} +{% assign some_var = some_var | markdownify %} +{% include fix_linenos.html code=some_var %} + +CAVEATS The above does not work when `Some code` happens to contain the matched string `
      `. -{%- endcomment %} +The use of this file overwrites the variable `fix_linenos_code` with `nil`. +{%- endcomment -%} + +{% assign fix_linenos_code = include.code %} {% if fix_linenos_code contains '
      ' %} - {% assign fix_linenos_code = fix_linenos_code | replace: "
      ", "" %} + {% assign fix_linenos_code = fix_linenos_code | replace: '
      ', '
      ' %}
+  {% assign fix_linenos_code = fix_linenos_code | replace: "
      ", "" %}
 {% endif %}
+{{ fix_linenos_code }}
+{% assign fix_linenos_code = nil %}

From b5cd532435c57f4b87734954fdd8c95dd196692f Mon Sep 17 00:00:00 2001
From: PLanCompS <18308236+pdmosses@users.noreply.github.com>
Date: Mon, 6 Jul 2020 15:10:35 +0200
Subject: [PATCH 16/48] Update code.scss

Produces sensible (but not perfect) results from different kinds of highlight markup.
The CSS code needs a major refactoring to eliminate duplication and superflous lines.
---
 _sass/code.scss | 56 +++++++++++++++++++++++++++++++++++++++----------
 1 file changed, 45 insertions(+), 11 deletions(-)

diff --git a/_sass/code.scss b/_sass/code.scss
index 72fa336..2423dfa 100644
--- a/_sass/code.scss
+++ b/_sass/code.scss
@@ -11,6 +11,34 @@ code {
   border-radius: $border-radius;
 }
 
+// Content structure for highlighted code blocks using fences or Liquid
+//
+// ```[LANG]...```, no kramdown line_numbers:
+//   div.[language-LANG.]highlighter-rouge > div.highlight > pre.highlight > code
+//
+// ```[LANG]...```, kramdown line_numbers = true:
+//   div.[language-LANG.]highlighter-rouge > div.highlight > pre.highlight > code
+//   > div.table-wrapper > table.rouge-table > tbody > tr 
+//   > td.rouge-gutter.gl > pre.lineno
+//   | td.rouge-code > pre
+//
+// {% highlight LANG %}...{% endhighlight %}:
+//   figure.highlight > pre > code.language-LANG
+//
+// {% highlight LANG linenos %}...{% endhighlight %}:
+//   figure.highlight > pre > code.language-LANG
+//   > div.table-wrapper > table.rouge-table > tbody > tr
+//   > td.gutter.gl > pre.lineno
+//   | td.code > pre
+//
+// fix_linenos removes the outermost pre when it encloses table.rouge-table
+//
+// See docs/index-test.md for some tests.
+// 
+// No kramdown line_numbers: fences and Liquid highlighting look the same.
+// Kramdown line_numbers = true: fences have a wider gutter than with Liquid?
+
+
 pre.highlight,
 figure.highlight {
   padding: $sp-3;
@@ -27,12 +55,11 @@ figure.highlight {
 }
 
 // Using Liquid tags for highlighting, optionally with linenos
-//
-// See docs/index-test.md for tests
 
 // Without linenos: figure.highlight > pre > code > div > span*
 
-figure.highlight {
+figure.highlight,
+div.highlight {
   padding: 0;
   margin-top: 0;
   margin-bottom: $sp-3;
@@ -47,11 +74,12 @@ figure.highlight {
   }
 }
 
-// With linenos:
-
-figure.highlight > pre > code,
-figure.highlight > code {
+// With linenos or kramdown line_numbers option:
 
+figure.highlight > pre > code, // {% highlight linenos %}
+figure.highlight > code,       // with fix_linenos
+div.highlight > pre > code,    // ```...```
+div.highlight > code {         // with fix_linenos
   td,
   td > pre {
     @include fs-2;
@@ -62,8 +90,8 @@ figure.highlight > code {
     border-left: 0;
   }
 
-  td.gutter {
-    padding-right: 1rem;
+  td.gl {
+    padding-right: $sp-3;
   }
 
   pre {
@@ -79,7 +107,9 @@ figure.highlight > code {
 
 // Jekyll 4.1.1: figure.highlight > pre > code > div > table > ...
 
-figure.highlight > pre > code .table-wrapper {
+figure.highlight > pre > code .table-wrapper,
+div.highlight > pre > code .table-wrapper,
+ {
   padding: 0;
   margin-bottom: 0;
   border: 0;
@@ -88,8 +118,12 @@ figure.highlight > pre > code .table-wrapper {
 
 // Using fix_linenos: figure.highlight > code > div > table > ...
 
-figure.highlight > code .table-wrapper {
+figure.highlight > code .table-wrapper,
+div.highlight > code .table-wrapper {
   padding: $sp-3;
+  margin-bottom: 0;
+  border: 0;
+  box-shadow: none;
 }
 
 .highlighter-rouge {

From 49ef043ebbe839858689de44428d2bf70bd02a53 Mon Sep 17 00:00:00 2001
From: PLanCompS <18308236+pdmosses@users.noreply.github.com>
Date: Mon, 6 Jul 2020 17:20:55 +0200
Subject: [PATCH 17/48] Update code.scss

Removed some comments and layout
---
 _sass/code.scss | 16 +++++++---------
 1 file changed, 7 insertions(+), 9 deletions(-)

diff --git a/_sass/code.scss b/_sass/code.scss
index 2423dfa..864c9b0 100644
--- a/_sass/code.scss
+++ b/_sass/code.scss
@@ -18,7 +18,7 @@ code {
 //
 // ```[LANG]...```, kramdown line_numbers = true:
 //   div.[language-LANG.]highlighter-rouge > div.highlight > pre.highlight > code
-//   > div.table-wrapper > table.rouge-table > tbody > tr 
+//   > div.table-wrapper > table.rouge-table > tbody > tr
 //   > td.rouge-gutter.gl > pre.lineno
 //   | td.rouge-code > pre
 //
@@ -34,11 +34,10 @@ code {
 // fix_linenos removes the outermost pre when it encloses table.rouge-table
 //
 // See docs/index-test.md for some tests.
-// 
+//
 // No kramdown line_numbers: fences and Liquid highlighting look the same.
 // Kramdown line_numbers = true: fences have a wider gutter than with Liquid?
 
-
 pre.highlight,
 figure.highlight {
   padding: $sp-3;
@@ -76,10 +75,10 @@ div.highlight {
 
 // With linenos or kramdown line_numbers option:
 
-figure.highlight > pre > code, // {% highlight linenos %}
-figure.highlight > code,       // with fix_linenos
-div.highlight > pre > code,    // ```...```
-div.highlight > code {         // with fix_linenos
+figure.highlight > pre > code,
+figure.highlight > code,
+div.highlight > pre > code,
+div.highlight > code {
   td,
   td > pre {
     @include fs-2;
@@ -108,8 +107,7 @@ div.highlight > code {         // with fix_linenos
 // Jekyll 4.1.1: figure.highlight > pre > code > div > table > ...
 
 figure.highlight > pre > code .table-wrapper,
-div.highlight > pre > code .table-wrapper,
- {
+div.highlight > pre > code .table-wrapper {
   padding: 0;
   margin-bottom: 0;
   border: 0;

From 61053f677b7e9808fb14ee851d28a89361980f55 Mon Sep 17 00:00:00 2001
From: PLanCompS <18308236+pdmosses@users.noreply.github.com>
Date: Tue, 7 Jul 2020 19:34:35 +0200
Subject: [PATCH 18/48] Major refactoring

The additions to `_config.yml` go together with the changes to `code.scss`,
to facilitate adjusttments by users. See `docs/linenos-test` for the details.
The CSS code has been significantly refactored and simplified,
and seems to produce sensible results (at least on Safari and Firefox).
---
 _config.yml          |   7 +++
 _sass/code.scss      | 100 ++++++++++++++++---------------------------
 docs/linenos-test.md |  75 ++++++++++++++++++++++++++++++--
 3 files changed, 115 insertions(+), 67 deletions(-)

diff --git a/_config.yml b/_config.yml
index 20bf8a1..aca049e 100644
--- a/_config.yml
+++ b/_config.yml
@@ -99,6 +99,11 @@ ga_tracking_anonymize_ip: true # Use GDPR compliant Google Analytics settings (t
 plugins:
   - jekyll-seo-tag
 
+kramdown:
+  syntax_highlighter_opts:
+    block:
+      line_numbers: false
+
 compress_html:
   clippings: all
   comments: all
@@ -106,3 +111,5 @@ compress_html:
   startings: []
   blanklines: false
   profile: false
+  # ignore:
+  #   envs: all
diff --git a/_sass/code.scss b/_sass/code.scss
index 864c9b0..4836a1e 100644
--- a/_sass/code.scss
+++ b/_sass/code.scss
@@ -38,55 +38,58 @@ code {
 // No kramdown line_numbers: fences and Liquid highlighting look the same.
 // Kramdown line_numbers = true: fences have a wider gutter than with Liquid?
 
-pre.highlight,
-figure.highlight {
+// ```[LANG]...```
+div.highlighter-rouge {
   padding: $sp-3;
   margin-top: 0;
-  margin-bottom: 0;
-  background-color: $code-background-color;
-  border-radius: $border-radius;
-  -webkit-overflow-scrolling: touch;
-
-  code {
-    padding: 0;
-    border: 0;
-  }
-}
-
-// Using Liquid tags for highlighting, optionally with linenos
-
-// Without linenos: figure.highlight > pre > code > div > span*
-
-figure.highlight,
-div.highlight {
-  padding: 0;
-  margin-top: 0;
   margin-bottom: $sp-3;
   background-color: $code-background-color;
   border-radius: $border-radius;
+  box-shadow: none;
   -webkit-overflow-scrolling: touch;
 
-  pre {
-    padding: $sp-3;
-    margin-top: 0;
-    margin-bottom: 0;
+  div.highlight,
+  pre.highlight,
+  code {
+    padding: 0;
+    margin: 0;
+    border: 0;
   }
 }
 
-// With linenos or kramdown line_numbers option:
+// {% highlight LANG [linenos] %}...{% endhighlight %}:
+figure.highlight {
+  padding: $sp-3;
+  margin-top: 0;
+  margin-bottom: $sp-3;
+  background-color: $code-background-color;
+  border-radius: $border-radius;
+  box-shadow: none;
+  -webkit-overflow-scrolling: touch;
 
-figure.highlight > pre > code,
-figure.highlight > code,
-div.highlight > pre > code,
-div.highlight > code {
-  td,
+  pre,
+  code {
+    padding: 0;
+    margin: 0;
+    border: 0;
+  }
+}
+
+// ```[LANG]...```, kramdown line_numbers = true,
+// {% highlight LANG linenos %}...{% endhighlight %}:
+.highlight .table-wrapper {
+  padding: 0;
+  margin: 0;
+  border: 0;
+  box-shadow: none;
+
+  tr > td,
   td > pre {
     @include fs-2;
     min-width: 0;
     padding: 0;
+    border: 0;
     background-color: $code-background-color;
-    border-bottom: 0;
-    border-left: 0;
   }
 
   td.gl {
@@ -94,38 +97,9 @@ div.highlight > code {
   }
 
   pre {
-    margin-top: 0;
+    margin: 0;
     line-height: 2;
   }
-
-  tbody > tr > td {
-    padding-bottom: 0;
-    border-bottom: 0;
-  }
-}
-
-// Jekyll 4.1.1: figure.highlight > pre > code > div > table > ...
-
-figure.highlight > pre > code .table-wrapper,
-div.highlight > pre > code .table-wrapper {
-  padding: 0;
-  margin-bottom: 0;
-  border: 0;
-  box-shadow: none;
-}
-
-// Using fix_linenos: figure.highlight > code > div > table > ...
-
-figure.highlight > code .table-wrapper,
-div.highlight > code .table-wrapper {
-  padding: $sp-3;
-  margin-bottom: 0;
-  border: 0;
-  box-shadow: none;
-}
-
-.highlighter-rouge {
-  margin-bottom: $sp-3;
 }
 
 .highlight .c {
diff --git a/docs/linenos-test.md b/docs/linenos-test.md
index 48e9603..8d6962e 100644
--- a/docs/linenos-test.md
+++ b/docs/linenos-test.md
@@ -4,17 +4,80 @@ title: Markdown line number test
 nav_order: 999
 ---
 
-```
-Some unknown code in fences
-```
+# Configuration options
+
+The default settings for HTML compression are incompatible with the HTML
+produced by Jekyll (4.1.1 or earlier) for line numbers from highlighted code
+-- both when using Kramdown code fences and when using Liquid highlight tags.
+
+To avoid non-conforming HTML and unsatisfactory layout, HTML compression
+can be turned off by using the following configuration option:
 
-Some of the code examples below require the following setting in `_config.yml`:
 ```yaml
 compress_html:
   ignore:
     envs: all
 ```
 
+When using Kramdown code fences, line numbers are turned on globally by the
+following configuration option:
+
+```yaml
+kramdown:
+  syntax_highlighter_opts:
+    block:
+      line_numbers: false
+```
+
+Line numbers can then be suppressed locally using Liquid tags (_without_ the
+`linenos` option) instead of fences:
+
+```
+{% raw %}{% highlight some_language %}
+Some code
+{% endhighlight %}{% endraw %}
+```
+
+# Workarounds
+
+To use HTML compression together with line numbers, all highlighted code
+needs to be wrapped using one of the following workarounds.
+(The variable name `some_var` can be changed to avoid clashes; it can also
+be replaced by `code` -- but note that `code=code` cannot be removed).
+
+## Code fences
+
+````
+{% raw %}{% capture some_var %}
+```some_language
+Some code
+```
+{% endcapture %}
+{% assign some_var = some_var | markdownify %}
+{% include fix_linenos.html code=some_var %}{% endraw %}
+````
+
+## Liquid highlighting
+
+```
+{% raw %}{% capture some_var %}
+{% highlight some_language linenos %}
+Some code
+{% endhighlight %}
+{% endcapture %}
+{% include fix_linenos.html code=some_var %}{% endraw %}
+```
+
+_Credit:_ The original version of the above workaround was suggested by
+Dmitry Hrabrov at
+.
+
+# Examples
+
+```
+Some unknown code in fences
+```
+
 ```js
 // Javascript code with syntax highlighting in fences
 var fun = function lang(l) {
@@ -48,6 +111,10 @@ end
 {% include fix_linenos.html code=code %}
 {% assign code = nil %}
 
+With the default configuration options, the following example illustrates
+the incorrect formatting arising from the incompatibility of HTML compression
+and the non-conforming HTML produced by Jekyll for line numbers:
+
 {% highlight ruby linenos %}
 # Ruby code with syntax highlighting and unfixed line numbers using Liquid
 GitHubPages::Dependencies.gems.each do |gem, version|

From 029ba12559d8f55ca4a4beca44cd68120299ae4b Mon Sep 17 00:00:00 2001
From: PLanCompS <18308236+pdmosses@users.noreply.github.com>
Date: Tue, 7 Jul 2020 19:38:46 +0200
Subject: [PATCH 19/48] Update code.scss

---
 _sass/code.scss | 2 +-
 1 file changed, 1 insertion(+), 1 deletion(-)

diff --git a/_sass/code.scss b/_sass/code.scss
index 4836a1e..a28addd 100644
--- a/_sass/code.scss
+++ b/_sass/code.scss
@@ -88,8 +88,8 @@ figure.highlight {
     @include fs-2;
     min-width: 0;
     padding: 0;
-    border: 0;
     background-color: $code-background-color;
+    border: 0;
   }
 
   td.gl {

From 8a9a8a345d03883ed978eacedd5bdd651e1505b9 Mon Sep 17 00:00:00 2001
From: PLanCompS <18308236+pdmosses@users.noreply.github.com>
Date: Tue, 7 Jul 2020 19:54:31 +0200
Subject: [PATCH 20/48] Optimisations

Optimised CSS selectors.
Changed markup in `linenos-test` to inhibit line numbers appearing in YAML examples when testing code fences.
---
 _sass/code.scss      |  4 ++--
 docs/linenos-test.md | 20 ++++++++++----------
 2 files changed, 12 insertions(+), 12 deletions(-)

diff --git a/_sass/code.scss b/_sass/code.scss
index a28addd..5fd7df9 100644
--- a/_sass/code.scss
+++ b/_sass/code.scss
@@ -83,8 +83,8 @@ figure.highlight {
   border: 0;
   box-shadow: none;
 
-  tr > td,
-  td > pre {
+  td,
+  pre {
     @include fs-2;
     min-width: 0;
     padding: 0;
diff --git a/docs/linenos-test.md b/docs/linenos-test.md
index 8d6962e..cdb19a9 100644
--- a/docs/linenos-test.md
+++ b/docs/linenos-test.md
@@ -13,30 +13,30 @@ produced by Jekyll (4.1.1 or earlier) for line numbers from highlighted code
 To avoid non-conforming HTML and unsatisfactory layout, HTML compression
 can be turned off by using the following configuration option:
 
-```yaml
+{% highlight yaml %}
 compress_html:
   ignore:
     envs: all
-```
+{% endhighlight %}
 
 When using Kramdown code fences, line numbers are turned on globally by the
 following configuration option:
 
-```yaml
+{% highlight yaml %}
 kramdown:
   syntax_highlighter_opts:
     block:
       line_numbers: false
-```
+{% endhighlight %}
 
 Line numbers can then be suppressed locally using Liquid tags (_without_ the
 `linenos` option) instead of fences:
 
-```
+{% highlight yaml %}
 {% raw %}{% highlight some_language %}
 Some code
 {% endhighlight %}{% endraw %}
-```
+{% endhighlight %}
 
 # Workarounds
 
@@ -47,7 +47,7 @@ be replaced by `code` -- but note that `code=code` cannot be removed).
 
 ## Code fences
 
-````
+{% highlight default %}
 {% raw %}{% capture some_var %}
 ```some_language
 Some code
@@ -55,18 +55,18 @@ Some code
 {% endcapture %}
 {% assign some_var = some_var | markdownify %}
 {% include fix_linenos.html code=some_var %}{% endraw %}
-````
+{% endhighlight %}
 
 ## Liquid highlighting
 
-```
+{% highlight default %}
 {% raw %}{% capture some_var %}
 {% highlight some_language linenos %}
 Some code
 {% endhighlight %}
 {% endcapture %}
 {% include fix_linenos.html code=some_var %}{% endraw %}
-```
+{% endhighlight %}
 
 _Credit:_ The original version of the above workaround was suggested by
 Dmitry Hrabrov at

From a855af3db3aa828817b69615e92c598825eb51d8 Mon Sep 17 00:00:00 2001
From: PLanCompS <18308236+pdmosses@users.noreply.github.com>
Date: Tue, 7 Jul 2020 19:59:13 +0200
Subject: [PATCH 21/48] Update code.scss

---
 _sass/code.scss | 3 ++-
 1 file changed, 2 insertions(+), 1 deletion(-)

diff --git a/_sass/code.scss b/_sass/code.scss
index 5fd7df9..ead2c5f 100644
--- a/_sass/code.scss
+++ b/_sass/code.scss
@@ -57,7 +57,8 @@ div.highlighter-rouge {
   }
 }
 
-// {% highlight LANG [linenos] %}...{% endhighlight %}:
+// {% highlight LANG %}...{% endhighlight %},
+// {% highlight LANG linenos %}...{% endhighlight %}:
 figure.highlight {
   padding: $sp-3;
   margin-top: 0;

From 93f93f48a712aeee2ef6d869613efe66ba0e2dfc Mon Sep 17 00:00:00 2001
From: Silvio Giebl 
Date: Thu, 9 Jul 2020 21:07:24 +0200
Subject: [PATCH 22/48] Added doc collections and categories

---
 _includes/nav.html              |  4 ++--
 _layouts/default.html           | 14 +++++++++++++-
 _sass/navigation.scss           | 23 +++++++++++++++++++++++
 assets/js/zzzz-search-data.json | 18 ++++++++++++++----
 4 files changed, 52 insertions(+), 7 deletions(-)

diff --git a/_includes/nav.html b/_includes/nav.html
index f2ec7e5..930945c 100644
--- a/_includes/nav.html
+++ b/_includes/nav.html
@@ -1,6 +1,6 @@
 
        
-  {%- assign ordered_pages_list = site.html_pages | where_exp:"item", "item.nav_order != nil" -%}
-  {%- assign unordered_pages_list = site.html_pages | where_exp:"item", "item.nav_order == nil" -%}
+  {%- assign ordered_pages_list = include.pages | where_exp:"item", "item.nav_order != nil" -%}
+  {%- assign unordered_pages_list = include.pages | where_exp:"item", "item.nav_order == nil" -%}
   {%- if site.nav_sort == 'case_insensitive' -%}
     {%- assign sorted_ordered_pages_list = ordered_pages_list | sort_natural:"nav_order" -%}
     {%- assign sorted_unordered_pages_list = unordered_pages_list | sort_natural:"title" -%}
diff --git a/_layouts/default.html b/_layouts/default.html
index 1d41a71..3510c25 100644
--- a/_layouts/default.html
+++ b/_layouts/default.html
@@ -48,7 +48,19 @@ layout: table_wrappers
       
     
     
     
        
       This site uses Just the Docs, a documentation theme for Jekyll.
diff --git a/_sass/navigation.scss b/_sass/navigation.scss
index 0417b4c..521c15f 100644
--- a/_sass/navigation.scss
+++ b/_sass/navigation.scss
@@ -131,6 +131,29 @@
   }
 }
 
+.nav-category {
+  padding-top: $sp-2;
+  padding-right: $gutter-spacing-sm;
+  padding-bottom: $sp-2;
+  padding-left: $gutter-spacing-sm;
+  font-weight: 600;
+  text-align: end;
+  text-transform: uppercase;
+  border-bottom: $border $border-color;
+  @include fs-2;
+
+  @include mq(md) {
+    padding-right: $gutter-spacing;
+    padding-left: $gutter-spacing;
+    margin-top: $gutter-spacing-sm;
+    text-align: start;
+
+    &:first-child {
+      margin-top: 0;
+    }
+  }
+}
+
 // Aux nav
 
 .aux-nav {
diff --git a/assets/js/zzzz-search-data.json b/assets/js/zzzz-search-data.json
index 0a6c3e5..6bc36e8 100644
--- a/assets/js/zzzz-search-data.json
+++ b/assets/js/zzzz-search-data.json
@@ -2,8 +2,17 @@
 permalink: /assets/js/search-data.json
 ---
 {
-  {%- assign i = 0 -%}
-  {% for page in site.html_pages %}
+{% assign i = 0 -%}
+{%- assign pages_array = '' | split: '' -%}
+{%- assign pages_array = pages_array | push: site.html_pages -%}
+{%- if site.doc_collections -%}
+  {%- for doc_collection in site.doc_collections -%}
+    {%- assign collection = site[doc_collection.collection] -%}
+    {%- assign pages_array = pages_array | push: collection -%}
+  {%- endfor -%}
+{%- endif -%}
+{%- for pages in pages_array -%}
+  {%- for page in pages -%}
     {%- if page.title and page.search_exclude != true -%}
       {%- assign page_content = page.content -%}
       {%- assign heading_level = site.search.heading_level | default: 2 -%}
@@ -14,7 +23,7 @@ permalink: /assets/js/search-data.json
       {%- endfor -%}
       {%- assign parts = page_content | split: '' -%}
         {%- assign title = titleAndContent[0] | replace_first: '>', '
        ' | split: '
        ' -%}
         {%- assign title = title[1] | strip_html -%}
@@ -54,5 +63,6 @@ permalink: /assets/js/search-data.json
         {%- assign i = i | plus: 1 -%}
       {%- endunless -%}
     {%- endif -%}
-  {% endfor %}
+  {%- endfor -%}
+{%- endfor %}
 }

From d476ce5748608235f4a6f8f74169129c9a384cff Mon Sep 17 00:00:00 2001
From: Silvio Giebl 
Date: Thu, 9 Jul 2020 22:14:57 +0200
Subject: [PATCH 23/48] Updated search.rake

---
 lib/tasks/search.rake | 18 ++++++++++++++----
 1 file changed, 14 insertions(+), 4 deletions(-)

diff --git a/lib/tasks/search.rake b/lib/tasks/search.rake
index 8e6305a..73c0d5b 100644
--- a/lib/tasks/search.rake
+++ b/lib/tasks/search.rake
@@ -12,8 +12,17 @@ namespace :search do
 permalink: /assets/js/search-data.json
 ---
 {
-  {%- assign i = 0 -%}
-  {% for page in site.html_pages %}
+{% assign i = 0 -%}
+{%- assign pages_array = \'\' | split: \'\' -%}
+{%- assign pages_array = pages_array | push: site.html_pages -%}
+{%- if site.doc_collections -%}
+  {%- for doc_collection in site.doc_collections -%}
+    {%- assign collection = site[doc_collection.collection] -%}
+    {%- assign pages_array = pages_array | push: collection -%}
+  {%- endfor -%}
+{%- endif -%}
+{%- for pages in pages_array -%}
+  {%- for page in pages -%}
     {%- if page.title and page.search_exclude != true -%}
       {%- assign page_content = page.content -%}
       {%- assign heading_level = site.search.heading_level | default: 2 -%}
@@ -24,7 +33,7 @@ permalink: /assets/js/search-data.json
       {%- endfor -%}
       {%- assign parts = page_content | split: \'\' -%}
         {%- assign title = titleAndContent[0] | replace_first: \'>\', \'
        \' | split: \'
        \' -%}
         {%- assign title = title[1] | strip_html -%}
@@ -64,7 +73,8 @@ permalink: /assets/js/search-data.json
         {%- assign i = i | plus: 1 -%}
       {%- endunless -%}
     {%- endif -%}
-  {% endfor %}
+  {%- endfor -%}
+{%- endfor %}
 }'
     end
     puts 'Done.'

From d1c3e0833722c8a432e1d697cb5ca529c64246fd Mon Sep 17 00:00:00 2001
From: Silvio Giebl 
Date: Thu, 9 Jul 2020 23:33:52 +0200
Subject: [PATCH 24/48] Updated doc_collections format

---
 _layouts/default.html           | 8 ++++++--
 assets/js/zzzz-search-data.json | 3 ++-
 lib/tasks/search.rake           | 3 ++-
 3 files changed, 10 insertions(+), 4 deletions(-)

diff --git a/_layouts/default.html b/_layouts/default.html
index 3510c25..9a04ac6 100644
--- a/_layouts/default.html
+++ b/_layouts/default.html
@@ -51,8 +51,9 @@ layout: table_wrappers
       {% if site.doc_collections %}
         {% assign doc_collections_size = site.doc_collections | size %}
         {% for doc_collection in site.doc_collections %}
-          {% assign name = doc_collection.name %}
-          {% assign collection = site[doc_collection.collection] %}
+          {% assign collection_name = doc_collection[0] %}
+          {% assign collection = site[collection_name] %}
+          {% assign name = doc_collection[1].name %}
           {% if doc_collections_size > 1 %}
             
        {{ name }}
        
           {% endif %}
@@ -155,6 +156,9 @@ layout: table_wrappers
                   site.gh_edit_branch and
                   site.gh_edit_view_mode
                 %}
+                {{ site.github.repository_url }}
+                {{ site.github.source.branch }}
+                {{ site.github.source.path }}
                   
        
                     {{ site.gh_edit_link_text }}
                   
        
diff --git a/assets/js/zzzz-search-data.json b/assets/js/zzzz-search-data.json
index 6bc36e8..05b393d 100644
--- a/assets/js/zzzz-search-data.json
+++ b/assets/js/zzzz-search-data.json
@@ -7,7 +7,8 @@ permalink: /assets/js/search-data.json
 {%- assign pages_array = pages_array | push: site.html_pages -%}
 {%- if site.doc_collections -%}
   {%- for doc_collection in site.doc_collections -%}
-    {%- assign collection = site[doc_collection.collection] -%}
+    {% assign collection_name = doc_collection[0] %}
+    {% assign collection = site[collection_name] %}
     {%- assign pages_array = pages_array | push: collection -%}
   {%- endfor -%}
 {%- endif -%}
diff --git a/lib/tasks/search.rake b/lib/tasks/search.rake
index 73c0d5b..5b65682 100644
--- a/lib/tasks/search.rake
+++ b/lib/tasks/search.rake
@@ -17,7 +17,8 @@ permalink: /assets/js/search-data.json
 {%- assign pages_array = pages_array | push: site.html_pages -%}
 {%- if site.doc_collections -%}
   {%- for doc_collection in site.doc_collections -%}
-    {%- assign collection = site[doc_collection.collection] -%}
+    {% assign collection_name = doc_collection[0] %}
+    {% assign collection = site[collection_name] %}
     {%- assign pages_array = pages_array | push: collection -%}
   {%- endfor -%}
 {%- endif -%}

From b4b74f7e1dd52e043500ad7dbd40bef68f6676b2 Mon Sep 17 00:00:00 2001
From: Silvio Giebl 
Date: Thu, 9 Jul 2020 23:43:33 +0200
Subject: [PATCH 25/48] Added documentation for doc_collections

---
 docs/configuration.md | 41 +++++++++++++++++++++++++++++++++++++++++
 1 file changed, 41 insertions(+)

diff --git a/docs/configuration.md b/docs/configuration.md
index 65471d2..3e7a1f8 100644
--- a/docs/configuration.md
+++ b/docs/configuration.md
@@ -22,6 +22,47 @@ Just the Docs has some specific configuration parameters that can be defined in
 
 View this site's [_config.yml](https://github.com/pmarsceill/just-the-docs/tree/master/_config.yml) file as an example.
 
+## Document collections
+
+By default, the navigation display normal [pages](https://jekyllrb.com/docs/pages/).
+Instead, you can also use [Jekyll collections](https://jekyllrb.com/docs/collections/).
+Collections group documents that semantically belong together.
+
+For example, to group all documentation, put all your files in the `_docs` folder and create the `docs` collection:
+```yaml
+# Define Jekyll collections
+collections:
+  # Define a collection named "docs", its documents reside in the "_docs" directory
+  docs:
+    permalink: "/:collection/:path/"
+    output: true
+
+# Define which collections are used in just-the-docs
+doc_collections:
+  # Reference the "docs" collection
+  docs:
+    # Give the collection a name
+    name: Documentation
+```
+
+You can reference multiple collections.
+This creates categories in the navigation with the configured names.
+```yaml
+collections:
+  docs:
+    permalink: "/:collection/:path/"
+    output: true
+  tutorials:
+    permalink: "/:collection/:path/"
+    output: true
+
+doc_collections:
+  docs:
+    name: Documentation
+  tutorials:
+    name: Tutorials
+```
+
 ## Site logo
 
 ```yaml

From 7dec48433be15614b5e062d5a467537060113d13 Mon Sep 17 00:00:00 2001
From: Silvio Giebl 
Date: Thu, 9 Jul 2020 23:51:31 +0200
Subject: [PATCH 26/48] Improved documentation for doc_collections

---
 docs/configuration.md | 4 ++--
 1 file changed, 2 insertions(+), 2 deletions(-)

diff --git a/docs/configuration.md b/docs/configuration.md
index 3e7a1f8..ee87752 100644
--- a/docs/configuration.md
+++ b/docs/configuration.md
@@ -24,11 +24,11 @@ View this site's [_config.yml](https://github.com/pmarsceill/just-the-docs/tree/
 
 ## Document collections
 
-By default, the navigation display normal [pages](https://jekyllrb.com/docs/pages/).
+By default, the navigation and search include normal [pages](https://jekyllrb.com/docs/pages/).
 Instead, you can also use [Jekyll collections](https://jekyllrb.com/docs/collections/).
 Collections group documents that semantically belong together.
 
-For example, to group all documentation, put all your files in the `_docs` folder and create the `docs` collection:
+For example, to group all documentation put all your files in the `_docs` folder and create the `docs` collection:
 ```yaml
 # Define Jekyll collections
 collections:

From 9faba6cd9160ac4b783b105d6bec1125a8d72336 Mon Sep 17 00:00:00 2001
From: Silvio Giebl 
Date: Fri, 10 Jul 2020 17:26:23 +0200
Subject: [PATCH 27/48] Removed temporary changes

---
 _layouts/default.html | 3 ---
 1 file changed, 3 deletions(-)

diff --git a/_layouts/default.html b/_layouts/default.html
index 9a04ac6..5f6e664 100644
--- a/_layouts/default.html
+++ b/_layouts/default.html
@@ -156,9 +156,6 @@ layout: table_wrappers
                   site.gh_edit_branch and
                   site.gh_edit_view_mode
                 %}
-                {{ site.github.repository_url }}
-                {{ site.github.source.branch }}
-                {{ site.github.source.path }}
                   
        
                     {{ site.gh_edit_link_text }}
                   
        

From 6b27beaf583053e348c771ac383a4dc82c9663db Mon Sep 17 00:00:00 2001
From: Silvio Giebl 
Date: Fri, 10 Jul 2020 19:07:01 +0200
Subject: [PATCH 28/48] Added just-the-docs.collections nav_exclude and
 search_exclude Renamed doc_collections to just-the-docs.collections

---
 _layouts/default.html           | 20 +++++++++++---------
 assets/js/zzzz-search-data.json | 15 +++++++++------
 lib/tasks/search.rake           | 17 ++++++++++-------
 3 files changed, 30 insertions(+), 22 deletions(-)

diff --git a/_layouts/default.html b/_layouts/default.html
index 5f6e664..8641d98 100644
--- a/_layouts/default.html
+++ b/_layouts/default.html
@@ -48,16 +48,18 @@ layout: table_wrappers