From 94c1dc37365b59122f178e58d03880c0819206ea Mon Sep 17 00:00:00 2001 From: Peter Mosses Date: Sat, 16 Nov 2019 11:44:46 +0100 Subject: [PATCH 01/83] Hides dispay of grandchildren Display of grandchildren links in the navigation is now delayed until their parent is selected. To test, select the `Grandchildren test` node. Only the direct children should appear. Selecting one of them then shows its children. --- _includes/nav.html | 6 +++++- docs/grandchildren-test/buttons.md | 11 +++++++++++ docs/grandchildren-test/buttons/grandchild.md | 9 +++++++++ docs/grandchildren-test/index.md | 12 ++++++++++++ docs/grandchildren-test/labels.md | 11 +++++++++++ docs/grandchildren-test/labels/label-grandchild.md | 9 +++++++++ 6 files changed, 57 insertions(+), 1 deletion(-) create mode 100644 docs/grandchildren-test/buttons.md create mode 100644 docs/grandchildren-test/buttons/grandchild.md create mode 100644 docs/grandchildren-test/index.md create mode 100644 docs/grandchildren-test/labels.md create mode 100644 docs/grandchildren-test/labels/label-grandchild.md diff --git a/_includes/nav.html b/_includes/nav.html index d561a42..eb96e28 100644 --- a/_includes/nav.html +++ b/_includes/nav.html @@ -10,6 +10,7 @@ {%- endif -%} {{ node.title }} {%- if node.has_children -%} + {%- if page.url == node.url or page.parent == node.title or page.grand_parent == node.title -%} {%- assign children_list = site.html_pages | where: "parent", node.title | sort:"nav_order" -%} + {%- endif -%} {%- endif -%} {%- endfor -%} {%- endif -%} + {%- endif -%} {%- endif -%} {%- endunless -%} diff --git a/docs/grandchildren-test/buttons.md b/docs/grandchildren-test/buttons.md new file mode 100644 index 0000000..96fc21e --- /dev/null +++ b/docs/grandchildren-test/buttons.md @@ -0,0 +1,11 @@ +--- +layout: default +title: Buttons +parent: Grandchildren test +has_children: true +--- + +Buttons +---- + +Child of [Grandchildren test](..) diff --git a/docs/grandchildren-test/buttons/grandchild.md b/docs/grandchildren-test/buttons/grandchild.md new file mode 100644 index 0000000..093d200 --- /dev/null +++ b/docs/grandchildren-test/buttons/grandchild.md @@ -0,0 +1,9 @@ +--- +layout: default +title: Buttons Child Page +parent: Buttons +grand_parent: Grandchildren test +--- + +Buttons Child Page +---- diff --git a/docs/grandchildren-test/index.md b/docs/grandchildren-test/index.md new file mode 100644 index 0000000..dd03d58 --- /dev/null +++ b/docs/grandchildren-test/index.md @@ -0,0 +1,12 @@ +--- +layout: default +title: Grandchildren test +has_children: true +nav_order: 8 +--- + +Grandchildren test +================== + +Has a child [Buttons](buttons) +and a grandchild [Child of Buttons](buttons/grandchild) diff --git a/docs/grandchildren-test/labels.md b/docs/grandchildren-test/labels.md new file mode 100644 index 0000000..f4b9ea8 --- /dev/null +++ b/docs/grandchildren-test/labels.md @@ -0,0 +1,11 @@ +--- +layout: default +title: Labels +parent: Grandchildren test +has_children: true +--- + +Labels +---- + +Child of Grandchildren test diff --git a/docs/grandchildren-test/labels/label-grandchild.md b/docs/grandchildren-test/labels/label-grandchild.md new file mode 100644 index 0000000..f6c9550 --- /dev/null +++ b/docs/grandchildren-test/labels/label-grandchild.md @@ -0,0 +1,9 @@ +--- +layout: default +title: Labels Child Page +parent: Labels +grand_parent: Grandchildren test +--- + +Labels Child Page +---- From 367db86fff5e37e1f5c55de7a291cf34ea4bcb89 Mon Sep 17 00:00:00 2001 From: Peter Mosses Date: Sat, 16 Nov 2019 15:14:54 +0100 Subject: [PATCH 02/83] Update just-the-docs.gemspec Trying to get the navigation to remain in the forked site --- just-the-docs.gemspec | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/just-the-docs.gemspec b/just-the-docs.gemspec index 4be9738..0e38b4d 100644 --- a/just-the-docs.gemspec +++ b/just-the-docs.gemspec @@ -7,7 +7,7 @@ Gem::Specification.new do |spec| spec.email = ["patrick.marsceill@gmail.com"] spec.summary = %q{A modern, highly customizable, and responsive Jekyll theme for documention with built-in search.} - spec.homepage = "https://github.com/pmarsceill/just-the-docs" + # spec.homepage = "https://github.com/pmarsceill/just-the-docs" spec.license = "MIT" spec.files = `git ls-files -z`.split("\x0").select { |f| f.match(%r{^(assets|bin|_layouts|_includes|lib|Rakefile|_sass|LICENSE|README)}i) } From f978770956cfc2792eba21f77efc138690047da3 Mon Sep 17 00:00:00 2001 From: Peter Mosses Date: Sat, 16 Nov 2019 15:18:42 +0100 Subject: [PATCH 03/83] Update just-the-docs.gemspec Trying to get the navigation to remain in the forked site --- just-the-docs.gemspec | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/just-the-docs.gemspec b/just-the-docs.gemspec index 0e38b4d..67c5f01 100644 --- a/just-the-docs.gemspec +++ b/just-the-docs.gemspec @@ -7,7 +7,7 @@ Gem::Specification.new do |spec| spec.email = ["patrick.marsceill@gmail.com"] spec.summary = %q{A modern, highly customizable, and responsive Jekyll theme for documention with built-in search.} - # spec.homepage = "https://github.com/pmarsceill/just-the-docs" + spec.homepage = "https://pdmosses.github.io/just-the-docs" spec.license = "MIT" spec.files = `git ls-files -z`.split("\x0").select { |f| f.match(%r{^(assets|bin|_layouts|_includes|lib|Rakefile|_sass|LICENSE|README)}i) } From 5f50531cce0646f31b9ee363e72934c085e9da82 Mon Sep 17 00:00:00 2001 From: Peter Mosses Date: Sat, 16 Nov 2019 15:20:43 +0100 Subject: [PATCH 04/83] Update just-the-docs.gemspec Trying to get the navigation to remain in the forked site --- just-the-docs.gemspec | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/just-the-docs.gemspec b/just-the-docs.gemspec index 67c5f01..2381106 100644 --- a/just-the-docs.gemspec +++ b/just-the-docs.gemspec @@ -7,7 +7,7 @@ Gem::Specification.new do |spec| spec.email = ["patrick.marsceill@gmail.com"] spec.summary = %q{A modern, highly customizable, and responsive Jekyll theme for documention with built-in search.} - spec.homepage = "https://pdmosses.github.io/just-the-docs" + spec.homepage = "https://github.com/pdmosses/just-the-docs" spec.license = "MIT" spec.files = `git ls-files -z`.split("\x0").select { |f| f.match(%r{^(assets|bin|_layouts|_includes|lib|Rakefile|_sass|LICENSE|README)}i) } From 33d1e0f8d7b0805ff668759379b1f513deeed44d Mon Sep 17 00:00:00 2001 From: Peter Mosses Date: Sat, 16 Nov 2019 15:23:29 +0100 Subject: [PATCH 05/83] Update _config.yml Trying to get the navigation to remain in the forked site --- _config.yml | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/_config.yml b/_config.yml index a090670..7e71f3e 100644 --- a/_config.yml +++ b/_config.yml @@ -16,7 +16,7 @@ title: Just the Docs description: A Jekyll theme for documentation baseurl: "/just-the-docs" # the subpath of your site, e.g. /blog -url: "https://pmarsceill.github.io" # the base hostname & protocol for your site, e.g. http://example.com +url: "https://pdmosses.github.io" # the base hostname & protocol for your site, e.g. http://example.com permalink: pretty exclude: ["node_modules/", "*.gemspec", "*.gem", "Gemfile", "Gemfile.lock", "package.json", "package-lock.json", "script/", "LICENSE.txt", "lib/", "bin/", "README.md", "Rakefile"] From d00aadeee73bc2b35b17bf7c0bba3f6f4465c824 Mon Sep 17 00:00:00 2001 From: PLanCompS <18308236+pdmosses@users.noreply.github.com> Date: Mon, 27 Apr 2020 16:28:30 +0200 Subject: [PATCH 06/83] Update .gitignore Added `.jekyll-cache` --- .gitignore | 1 + 1 file changed, 1 insertion(+) diff --git a/.gitignore b/.gitignore index b447a12..a802a86 100644 --- a/.gitignore +++ b/.gitignore @@ -1,5 +1,6 @@ *.gem .bundle +.jekyll-cache .sass-cache _site Gemfile.lock From 7cfc63e1384d91548fc25810a544b07daacca9d0 Mon Sep 17 00:00:00 2001 From: Henrique Vianna Date: Mon, 1 Jun 2020 14:35:15 -0300 Subject: [PATCH 07/83] 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 08/83] :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 09/83] :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 10/83] 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 11/83] 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 12/83] 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 13/83] 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 14/83] 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 15/83] 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 16/83] 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 17/83] 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 18/83] 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 19/83] 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 20/83] 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 21/83] 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 22/83] 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 23/83] 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 24/83] 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 25/83] 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 26/83] 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 27/83] 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 28/83] 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 29/83] 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 30/83] 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 31/83] 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 32/83] 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 33/83] 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 34/83] 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
       
     
     
      
diff --git a/docs/untitled-test.md b/docs/untitled-test.md
new file mode 100644
index 0000000..84f66d8
--- /dev/null
+++ b/docs/untitled-test.md
@@ -0,0 +1,6 @@
+---
+layout: default
+---
+# Untitled test page
+
+This page should not appear in the navigation.

From 74da664c0a6eb84bccaa43eecda7f486c596cea3 Mon Sep 17 00:00:00 2001
From: PLanCompS <18308236+pdmosses@users.noreply.github.com>
Date: Mon, 10 Aug 2020 16:53:48 +0200
Subject: [PATCH 52/83] Linenos test moved to UI Components as a child of Code

---
 docs/ui-components/code.md                         | 1 +
 docs/{linenos-test.md => ui-components/linenos.md} | 5 +++--
 2 files changed, 4 insertions(+), 2 deletions(-)
 rename docs/{linenos-test.md => ui-components/linenos.md} (97%)

diff --git a/docs/ui-components/code.md b/docs/ui-components/code.md
index e53a90d..b8136a3 100644
--- a/docs/ui-components/code.md
+++ b/docs/ui-components/code.md
@@ -2,6 +2,7 @@
 layout: default
 title: Code
 parent: UI Components
+has_children: true
 nav_order: 6
 ---
 
diff --git a/docs/linenos-test.md b/docs/ui-components/linenos.md
similarity index 97%
rename from docs/linenos-test.md
rename to docs/ui-components/linenos.md
index cdb19a9..b13e6c9 100644
--- a/docs/linenos-test.md
+++ b/docs/ui-components/linenos.md
@@ -1,7 +1,8 @@
 ---
 layout: default
-title: Markdown line number test
-nav_order: 999
+title: Code with line numbers
+parent: Code
+grand_parent: UI Components
 ---
 
 # Configuration options

From 4fc59a578fc987ea2dc67455c22bc5c356a0218b Mon Sep 17 00:00:00 2001
From: PLanCompS <18308236+pdmosses@users.noreply.github.com>
Date: Tue, 11 Aug 2020 18:25:58 +0200
Subject: [PATCH 53/83] Separate sorting of numbers and strings for navigation
 order

The values of `title` and `nav_order` can be numbers or strings.
Jekyll gives build failures when sorting on mixtures of different types,
so numbers and strings need to be sorted separately.

Here, numbers are sorted by their values, and come before all strings.
An omitted `nav_order` value is equivalent to the page's `title` value
(except that a numerical `title` value is treated as a string).

The case-sensitivity of string sorting is determined by `site.nav_sort`.
---
 _config.yml                       |  2 +-
 _includes/nav.html                | 59 ++++++++++++++++++++++++++-----
 docs/tests/42.md                  | 11 ++++++
 docs/{ => tests}/untitled-test.md |  0
 4 files changed, 63 insertions(+), 9 deletions(-)
 create mode 100644 docs/tests/42.md
 rename docs/{ => tests}/untitled-test.md (100%)

diff --git a/_config.yml b/_config.yml
index fd71b51..32309d8 100644
--- a/_config.yml
+++ b/_config.yml
@@ -19,7 +19,7 @@ baseurl: "/just-the-docs" # the subpath of your site, e.g. /blog
 url: "https://pmarsceill.github.io" # the base hostname & protocol for your site, e.g. http://example.com
 
 permalink: pretty
-exclude: ["node_modules/", "*.gemspec", "*.gem", "Gemfile", "Gemfile.lock", "package.json", "package-lock.json",  "script/", "LICENSE.txt", "lib/", "bin/", "README.md", "Rakefile"]
+exclude: ["node_modules/", "*.gemspec", "*.gem", "Gemfile", "Gemfile.lock", "package.json", "package-lock.json",  "script/", "LICENSE.txt", "lib/", "bin/", "README.md", "Rakefile", "docs/tests/"]
 
 # Set a path/url to a logo that will be displayed instead of the title
 #logo: "/assets/images/just-the-docs.png"
diff --git a/_includes/nav.html b/_includes/nav.html
index d74c17c..748b6ce 100644
--- a/_includes/nav.html
+++ b/_includes/nav.html
@@ -1,15 +1,58 @@
 
        
-  {%- assign included_pages_list = site.html_pages | where_exp:"item", "item.nav_exclude != true" | where_exp:"item", "item.title != nil" -%}
-  {%- assign ordered_pages_list = included_pages_list | where_exp:"item", "item.nav_order != nil"  -%}
-  {%- assign unordered_pages_list = included_pages_list | where_exp:"item", "item.nav_order == nil" -%}
+  {%- assign included_pages = site.html_pages
+        | where_exp:"item", "item.nav_exclude != true"
+        | where_exp:"item", "item.title != nil" -%}
+
+  {%- comment -%}
+    A nav_order value can be a number or a string.
+    Numbers are sorted by their values, before strings.
+    An omitted nav_order value is equivalent to the title value,
+    except that a numerical title value is treated as a string.
+    The case-sensitivity of string sorting is determined by site.nav_sort.
+  {%- endcomment -%}
+  
+  {%- assign string_ordered_pages = included_pages
+        | where_exp:"item", "item.nav_order == nil" -%}
+  {%- assign nav_ordered_pages = included_pages
+        | where_exp:"item", "item.nav_order != nil"  -%}
+
+  {%- comment -%}
+    The nav_ordered_pages have to be added to number_ordered_pages and
+    string_ordered_pages, depending on the nav_order value.
+    The first character of jsonify is `"` only for strings.
+  {%- endcomment -%}
+  {%- assign nav_ordered_groups = nav_ordered_pages
+        | group_by_exp:"item", "item.nav_order | jsonify | slice: 0" -%}
+  {%- assign number_ordered_pages = "" | split:"X" -%}
+  {%- for group in nav_ordered_groups -%}
+    {%- if group.name == '"' -%}
+      {%- assign string_ordered_pages = string_ordered_pages | concat: group.items -%}
+    {%- else -%}
+      {%- assign number_ordered_pages = number_ordered_pages | concat: group.items -%}
+    {%- endif -%}
+  {%- endfor -%}
+  
+  {%- assign sorted_number_ordered_pages = number_ordered_pages | sort:"nav_order" -%}
+  
+  {%- comment -%}
+    The string_ordered_pages have to be sorted by nav_order, and otherwise title.
+    After grouping them by those values, the groups are sorted, then the items
+    of each group are concatenated.
+  {%- endcomment -%}
+  {%- assign string_ordered_groups = string_ordered_pages
+        | group_by_exp:"item", "item.nav_order | default: item.title | string" -%}
   {%- 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" -%}
+    {%- assign sorted_string_ordered_groups = string_ordered_groups | sort_natural:"name" -%}
   {%- else -%}
-    {%- assign sorted_ordered_pages_list = ordered_pages_list | sort:"nav_order" -%}
-    {%- assign sorted_unordered_pages_list = unordered_pages_list | sort:"title" -%}
+    {%- assign sorted_string_ordered_groups = string_ordered_groups | sort:"name" -%}
   {%- endif -%}
-  {%- assign pages_list = sorted_ordered_pages_list | concat: sorted_unordered_pages_list -%}
+  {%- assign sorted_string_ordered_pages = "" | split:"X" -%}
+  {%- for group in sorted_string_ordered_groups -%}
+    {%- assign sorted_string_ordered_pages = sorted_string_ordered_pages | concat: group.items -%}
+  {%- endfor -%}
+
+  {%- assign pages_list = sorted_number_ordered_pages | concat: sorted_string_ordered_pages -%}
+  
   {%- for node in pages_list -%}
       {%- if node.parent == nil -%}
         
      • 
diff --git a/docs/tests/42.md b/docs/tests/42.md
new file mode 100644
index 0000000..fba0590
--- /dev/null
+++ b/docs/tests/42.md
@@ -0,0 +1,11 @@
+---
+layout: default
+title: 42
+search_exclude: true
+---
+
+# The answer is 42
+
+A link to this page should appear in the navigation after all pages where
+the `nav_order` value is a number, because titles are treated as strings
+when used as default `nav_order`s.
diff --git a/docs/untitled-test.md b/docs/tests/untitled-test.md
similarity index 100%
rename from docs/untitled-test.md
rename to docs/tests/untitled-test.md

From a7be52df3be906cf0b2e0a4b8194b94a63d5295f Mon Sep 17 00:00:00 2001
From: PLanCompS <18308236+pdmosses@users.noreply.github.com>
Date: Tue, 11 Aug 2020 18:26:34 +0200
Subject: [PATCH 54/83] Update nav.html

---
 _includes/nav.html | 14 +++++++++-----
 1 file changed, 9 insertions(+), 5 deletions(-)

diff --git a/_includes/nav.html b/_includes/nav.html
index 748b6ce..c9bcbda 100644
--- a/_includes/nav.html
+++ b/_includes/nav.html
@@ -4,11 +4,15 @@
         | where_exp:"item", "item.title != nil" -%}
 
   {%- comment -%}
-    A nav_order value can be a number or a string.
-    Numbers are sorted by their values, before strings.
-    An omitted nav_order value is equivalent to the title value,
-    except that a numerical title value is treated as a string.
-    The case-sensitivity of string sorting is determined by site.nav_sort.
+    The values of `title` and `nav_order` can be numbers or strings.
+    Jekyll gives build failures when sorting on mixtures of different types,
+    so numbers and strings need to be sorted separately.
+
+    Here, numbers are sorted by their values, and come before all strings.
+    An omitted `nav_order` value is equivalent to the page's `title` value
+    (except that a numerical `title` value is treated as a string).
+
+    The case-sensitivity of string sorting is determined by `site.nav_sort`.
   {%- endcomment -%}
   
   {%- assign string_ordered_pages = included_pages

From e4759daecfeb52ceda9aeb3f567096bf5fb29293 Mon Sep 17 00:00:00 2001
From: PLanCompS <18308236+pdmosses@users.noreply.github.com>
Date: Tue, 11 Aug 2020 18:31:54 +0200
Subject: [PATCH 55/83] Update nav.html

Indentation adjusted
---
 _includes/nav.html | 74 +++++++++++++++++++++++-----------------------
 1 file changed, 37 insertions(+), 37 deletions(-)

diff --git a/_includes/nav.html b/_includes/nav.html
index c9bcbda..a6fd87e 100644
--- a/_includes/nav.html
+++ b/_includes/nav.html
@@ -58,42 +58,42 @@
   {%- assign pages_list = sorted_number_ordered_pages | concat: sorted_string_ordered_pages -%}
   
   {%- for node in pages_list -%}
-      {%- if node.parent == nil -%}
-        
      • 
-          {%- if page.parent == node.title or page.grand_parent == node.title -%}
-            {%- assign first_level_url = node.url | absolute_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 -%}
-                
        • 
-                  {%- if page.url == child.url or page.parent == child.title -%}
-                    {%- assign second_level_url = child.url | absolute_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 -%}
-                
          • 
-            {%- endfor -%}
-            
        
-          {%- endif -%}
-        
        • 
-      {%- endif -%}
+    {%- if node.parent == nil -%}
+      
      • 
+        {%- if page.parent == node.title or page.grand_parent == node.title -%}
+          {%- assign first_level_url = node.url | absolute_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 -%}
+            
        • 
+              {%- if page.url == child.url or page.parent == child.title -%}
+                {%- assign second_level_url = child.url | absolute_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 -%}
+            
          • 
+          {%- endfor -%}
+          
        
+        {%- endif -%}
+      
        • 
+    {%- endif -%}
   {%- endfor -%}
 
      

From cff0254d93ec5c748bd06649f19bfc6cf97a8c28 Mon Sep 17 00:00:00 2001
From: PLanCompS <18308236+pdmosses@users.noreply.github.com>
Date: Tue, 11 Aug 2020 20:47:22 +0200
Subject: [PATCH 56/83] Update navigation-structure.md

Adjusted the documentation to explain how mixtures of numbers and strings are treated by `nav_order`.
---
 docs/navigation-structure.md | 17 ++++++++++-------
 1 file changed, 10 insertions(+), 7 deletions(-)

diff --git a/docs/navigation-structure.md b/docs/navigation-structure.md
index d5a7504..34e1005 100644
--- a/docs/navigation-structure.md
+++ b/docs/navigation-structure.md
@@ -25,7 +25,7 @@ By default, all pages will appear as top level pages in the main nav unless a pa
 
 ## Ordering pages
 
-To specify a page order, use the `nav_order` parameter in your pages' YAML front matter.
+To specify a page order, you can use the `nav_order` parameter in your pages' YAML front matter.
 
 #### Example
 {: .no_toc }
@@ -38,12 +38,13 @@ nav_order: 4
 ---
 ```
 
-The specified `nav_order` parameters on a site should be all integers or all strings.
-Pages without a `nav_order` parameter are ordered alphabetically by their `title`,
-and appear after the explicitly-ordered pages at each level.
-By default, all Capital letters are sorted before all lowercase letters;
-adding `nav_sort: case_insensitive` in the configuration file ignores case
-when sorting strings (but also sorts numbers lexicographically: `10` comes before `1`).
+The parameter values determine the order of the top-level pages, and of child pages with the same parent. You can reuse the same parameter values (e.g., integers starting from 1) for the child pages of different parents.
+
+The parameter values can be numbers (integers, floats) and/or strings. When you omit `nav_order` parameters, they default to the titles of the pages, which are ordered alphabetically. Pages with numerical `nav_order` parameters always come before those with strings or default `nav_order` parameters. If you want to make the page order independent of the page titles, you can set explicit `nav_order` parameters on all pages.
+
+By default, all Capital letters come before all lowercase letters; you can add `nav_sort: case_insensitive` in the configuration file to ignore the case). Enclosing strings in quotation marks is optional.
+
+> *Note for users of previous versions:* `nav_sort: case_insensitive` previously affected the ordering of numerical `nav_order` parameters: e.g., `10` came before `2`. Also, all pages with explicit `nav_order` parameters previously came before all pages with default parameters.
 
 ---
 
@@ -62,6 +63,8 @@ nav_exclude: true
 ---
 ```
 
+Pages with no `title` are automatically excluded from the navigation.
+
 ---
 
 ## Pages with children

From cfbdee11682be1cf1b6358605cbbc2abb4c607e8 Mon Sep 17 00:00:00 2001
From: PLanCompS <18308236+pdmosses@users.noreply.github.com>
Date: Thu, 13 Aug 2020 16:47:58 +0200
Subject: [PATCH 57/83] Update nav.html

Fixed conversion of numeric titles to strings.
---
 _includes/nav.html | 7 ++++---
 1 file changed, 4 insertions(+), 3 deletions(-)

diff --git a/_includes/nav.html b/_includes/nav.html
index a6fd87e..a70e2b0 100644
--- a/_includes/nav.html
+++ b/_includes/nav.html
@@ -23,7 +23,7 @@
   {%- comment -%}
     The nav_ordered_pages have to be added to number_ordered_pages and
     string_ordered_pages, depending on the nav_order value.
-    The first character of jsonify is `"` only for strings.
+    The first character of the jsonify result is `"` only for strings.
   {%- endcomment -%}
   {%- assign nav_ordered_groups = nav_ordered_pages
         | group_by_exp:"item", "item.nav_order | jsonify | slice: 0" -%}
@@ -39,12 +39,13 @@
   {%- assign sorted_number_ordered_pages = number_ordered_pages | sort:"nav_order" -%}
   
   {%- comment -%}
-    The string_ordered_pages have to be sorted by nav_order, and otherwise title.
+    The string_ordered_pages have to be sorted by nav_order, and otherwise title
+    (where appending the empty string to a numeric title converts it to a string).
     After grouping them by those values, the groups are sorted, then the items
     of each group are concatenated.
   {%- endcomment -%}
   {%- assign string_ordered_groups = string_ordered_pages
-        | group_by_exp:"item", "item.nav_order | default: item.title | string" -%}
+        | group_by_exp:"item", "item.nav_order | default: item.title | append:''" -%}
   {%- if site.nav_sort == 'case_insensitive' -%}
     {%- assign sorted_string_ordered_groups = string_ordered_groups | sort_natural:"name" -%}
   {%- else -%}

From 591a3c2351a8d8f8f6757a496853bc13b9a3119b Mon Sep 17 00:00:00 2001
From: PLanCompS <18308236+pdmosses@users.noreply.github.com>
Date: Thu, 13 Aug 2020 16:48:45 +0200
Subject: [PATCH 58/83] Update navigation-structure.md

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

diff --git a/docs/navigation-structure.md b/docs/navigation-structure.md
index 34e1005..c23906b 100644
--- a/docs/navigation-structure.md
+++ b/docs/navigation-structure.md
@@ -42,9 +42,9 @@ The parameter values determine the order of the top-level pages, and of child pa
 
 The parameter values can be numbers (integers, floats) and/or strings. When you omit `nav_order` parameters, they default to the titles of the pages, which are ordered alphabetically. Pages with numerical `nav_order` parameters always come before those with strings or default `nav_order` parameters. If you want to make the page order independent of the page titles, you can set explicit `nav_order` parameters on all pages.
 
-By default, all Capital letters come before all lowercase letters; you can add `nav_sort: case_insensitive` in the configuration file to ignore the case). Enclosing strings in quotation marks is optional.
+By default, all Capital letters come before all lowercase letters; you can add `nav_sort: case_insensitive` in the configuration file to ignore the case. Enclosing strings in quotation marks is optional.
 
-> *Note for users of previous versions:* `nav_sort: case_insensitive` previously affected the ordering of numerical `nav_order` parameters: e.g., `10` came before `2`. Also, all pages with explicit `nav_order` parameters previously came before all pages with default parameters.
+> *Note for users of previous versions:* `nav_sort: case_insensitive` previously affected the ordering of numerical `nav_order` parameters: e.g., `10` came before `2`. Also, all pages with explicit `nav_order` parameters previously came before all pages with default parameters. Both were potentially confusing, and they have now been eliminated. 
 
 ---
 

From ca367e09d5bb9d603794ab7fafdd23d1cc839289 Mon Sep 17 00:00:00 2001
From: PLanCompS <18308236+pdmosses@users.noreply.github.com>
Date: Thu, 13 Aug 2020 16:52:30 +0200
Subject: [PATCH 59/83] Added regression tests for navigation

See the change to `_config.yml` for how to activate the tests.
---
 _config.yml                                   | 10 ++++++-
 docs/tests/42.md                              | 11 --------
 docs/tests/index.md                           | 16 +++++++++++
 .../navigation/exclude/excluded-child.md      | 15 ++++++++++
 .../navigation/exclude/excluded-grandchild.md | 17 +++++++++++
 docs/tests/navigation/exclude/excluded.md     | 15 ++++++++++
 .../exclude/non-excluded-child-of-excluded.md | 15 ++++++++++
 .../navigation/exclude/non-excluded-child.md  | 16 +++++++++++
 .../non-excluded-grandchild-of-excluded.md    | 17 +++++++++++
 .../exclude/non-excluded-grandchild.md        | 17 +++++++++++
 docs/tests/navigation/exclude/non-excluded.md | 14 ++++++++++
 docs/tests/navigation/exclude/untitled.md     |  6 ++++
 docs/tests/navigation/grandparent/a.md        | 14 ++++++++++
 docs/tests/navigation/grandparent/b.md        | 14 ++++++++++
 docs/tests/navigation/grandparent/ca.md       | 16 +++++++++++
 docs/tests/navigation/grandparent/cb.md       | 16 +++++++++++
 docs/tests/navigation/grandparent/dca.md      | 16 +++++++++++
 docs/tests/navigation/grandparent/dcb.md      | 16 +++++++++++
 docs/tests/navigation/index.md                | 28 +++++++++++++++++++
 docs/tests/navigation/order/default/10.md     | 14 ++++++++++
 docs/tests/navigation/order/default/2.md      | 14 ++++++++++
 docs/tests/navigation/order/default/a.md      | 14 ++++++++++
 .../navigation/order/default/aa-lower.md      | 14 ++++++++++
 docs/tests/navigation/order/default/aa.md     | 14 ++++++++++
 docs/tests/navigation/order/default/index.md  | 15 ++++++++++
 docs/tests/navigation/order/floats/-1.1.md    | 16 +++++++++++
 docs/tests/navigation/order/floats/0.0.md     | 16 +++++++++++
 docs/tests/navigation/order/floats/10.0.md    | 16 +++++++++++
 docs/tests/navigation/order/floats/2.2222.md  | 16 +++++++++++
 docs/tests/navigation/order/floats/index.md   | 13 +++++++++
 docs/tests/navigation/order/index.md          |  8 ++++++
 docs/tests/navigation/order/integers/-1.md    | 16 +++++++++++
 docs/tests/navigation/order/integers/0.md     | 16 +++++++++++
 docs/tests/navigation/order/integers/10.md    | 16 +++++++++++
 docs/tests/navigation/order/integers/2.md     | 16 +++++++++++
 docs/tests/navigation/order/integers/index.md | 13 +++++++++
 docs/tests/navigation/order/mixture/-1.1.md   | 16 +++++++++++
 docs/tests/navigation/order/mixture/-1.md     | 16 +++++++++++
 docs/tests/navigation/order/mixture/0.0.md    | 16 +++++++++++
 docs/tests/navigation/order/mixture/0.md      | 16 +++++++++++
 docs/tests/navigation/order/mixture/10.0.md   | 16 +++++++++++
 docs/tests/navigation/order/mixture/10.md     | 14 ++++++++++
 docs/tests/navigation/order/mixture/2.2222.md | 16 +++++++++++
 docs/tests/navigation/order/mixture/2.md      | 14 ++++++++++
 docs/tests/navigation/order/mixture/a.md      | 14 ++++++++++
 .../navigation/order/mixture/aa-lower.md      | 16 +++++++++++
 docs/tests/navigation/order/mixture/aa.md     | 16 +++++++++++
 docs/tests/navigation/order/mixture/index.md  | 11 ++++++++
 docs/tests/navigation/order/strings/10.md     | 16 +++++++++++
 docs/tests/navigation/order/strings/2.md      | 16 +++++++++++
 docs/tests/navigation/order/strings/a.md      | 16 +++++++++++
 .../navigation/order/strings/aa-lower.md      | 16 +++++++++++
 docs/tests/navigation/order/strings/aa.md     | 16 +++++++++++
 docs/tests/navigation/order/strings/index.md  | 13 +++++++++
 docs/tests/untitled-test.md                   |  6 ----
 55 files changed, 798 insertions(+), 18 deletions(-)
 delete mode 100644 docs/tests/42.md
 create mode 100644 docs/tests/index.md
 create mode 100644 docs/tests/navigation/exclude/excluded-child.md
 create mode 100644 docs/tests/navigation/exclude/excluded-grandchild.md
 create mode 100644 docs/tests/navigation/exclude/excluded.md
 create mode 100644 docs/tests/navigation/exclude/non-excluded-child-of-excluded.md
 create mode 100644 docs/tests/navigation/exclude/non-excluded-child.md
 create mode 100644 docs/tests/navigation/exclude/non-excluded-grandchild-of-excluded.md
 create mode 100644 docs/tests/navigation/exclude/non-excluded-grandchild.md
 create mode 100644 docs/tests/navigation/exclude/non-excluded.md
 create mode 100644 docs/tests/navigation/exclude/untitled.md
 create mode 100644 docs/tests/navigation/grandparent/a.md
 create mode 100644 docs/tests/navigation/grandparent/b.md
 create mode 100644 docs/tests/navigation/grandparent/ca.md
 create mode 100644 docs/tests/navigation/grandparent/cb.md
 create mode 100644 docs/tests/navigation/grandparent/dca.md
 create mode 100644 docs/tests/navigation/grandparent/dcb.md
 create mode 100644 docs/tests/navigation/index.md
 create mode 100644 docs/tests/navigation/order/default/10.md
 create mode 100644 docs/tests/navigation/order/default/2.md
 create mode 100644 docs/tests/navigation/order/default/a.md
 create mode 100644 docs/tests/navigation/order/default/aa-lower.md
 create mode 100644 docs/tests/navigation/order/default/aa.md
 create mode 100644 docs/tests/navigation/order/default/index.md
 create mode 100644 docs/tests/navigation/order/floats/-1.1.md
 create mode 100644 docs/tests/navigation/order/floats/0.0.md
 create mode 100644 docs/tests/navigation/order/floats/10.0.md
 create mode 100644 docs/tests/navigation/order/floats/2.2222.md
 create mode 100644 docs/tests/navigation/order/floats/index.md
 create mode 100644 docs/tests/navigation/order/index.md
 create mode 100644 docs/tests/navigation/order/integers/-1.md
 create mode 100644 docs/tests/navigation/order/integers/0.md
 create mode 100644 docs/tests/navigation/order/integers/10.md
 create mode 100644 docs/tests/navigation/order/integers/2.md
 create mode 100644 docs/tests/navigation/order/integers/index.md
 create mode 100644 docs/tests/navigation/order/mixture/-1.1.md
 create mode 100644 docs/tests/navigation/order/mixture/-1.md
 create mode 100644 docs/tests/navigation/order/mixture/0.0.md
 create mode 100644 docs/tests/navigation/order/mixture/0.md
 create mode 100644 docs/tests/navigation/order/mixture/10.0.md
 create mode 100644 docs/tests/navigation/order/mixture/10.md
 create mode 100644 docs/tests/navigation/order/mixture/2.2222.md
 create mode 100644 docs/tests/navigation/order/mixture/2.md
 create mode 100644 docs/tests/navigation/order/mixture/a.md
 create mode 100644 docs/tests/navigation/order/mixture/aa-lower.md
 create mode 100644 docs/tests/navigation/order/mixture/aa.md
 create mode 100644 docs/tests/navigation/order/mixture/index.md
 create mode 100644 docs/tests/navigation/order/strings/10.md
 create mode 100644 docs/tests/navigation/order/strings/2.md
 create mode 100644 docs/tests/navigation/order/strings/a.md
 create mode 100644 docs/tests/navigation/order/strings/aa-lower.md
 create mode 100644 docs/tests/navigation/order/strings/aa.md
 create mode 100644 docs/tests/navigation/order/strings/index.md
 delete mode 100644 docs/tests/untitled-test.md

diff --git a/_config.yml b/_config.yml
index 32309d8..51161b0 100644
--- a/_config.yml
+++ b/_config.yml
@@ -19,7 +19,15 @@ baseurl: "/just-the-docs" # the subpath of your site, e.g. /blog
 url: "https://pmarsceill.github.io" # the base hostname & protocol for your site, e.g. http://example.com
 
 permalink: pretty
-exclude: ["node_modules/", "*.gemspec", "*.gem", "Gemfile", "Gemfile.lock", "package.json", "package-lock.json",  "script/", "LICENSE.txt", "lib/", "bin/", "README.md", "Rakefile", "docs/tests/"]
+exclude: ["node_modules/", "*.gemspec", "*.gem", "Gemfile", "Gemfile.lock", "package.json", "package-lock.json",  "script/", "LICENSE.txt", "lib/", "bin/", "README.md", "Rakefile"
+, "docs/tests/"
+]
+
+# Regression tests
+# By default, the pages in /docs/tests are excluded when the ste is built.
+# To include them, comment-out the relevant line above.
+# Uncommenting the following line doesn't work - see https://github.com/jekyll/jekyll/issues/4791
+# include: ["docs/tests/"]
 
 # Set a path/url to a logo that will be displayed instead of the title
 #logo: "/assets/images/just-the-docs.png"
diff --git a/docs/tests/42.md b/docs/tests/42.md
deleted file mode 100644
index fba0590..0000000
--- a/docs/tests/42.md
+++ /dev/null
@@ -1,11 +0,0 @@
----
-layout: default
-title: 42
-search_exclude: true
----
-
-# The answer is 42
-
-A link to this page should appear in the navigation after all pages where
-the `nav_order` value is a number, because titles are treated as strings
-when used as default `nav_order`s.
diff --git a/docs/tests/index.md b/docs/tests/index.md
new file mode 100644
index 0000000..7c03c7b
--- /dev/null
+++ b/docs/tests/index.md
@@ -0,0 +1,16 @@
+---
+layout: default
+title: Tests
+has_children: true
+nav_order: 100
+---
+
+# Tests
+
+ The main documentation pages of this theme illustrate the use of many of its features, which to some extent tests their implementation. The pages linked below provide further test cases for particular features, and may be useful for regression testing when developing new features.
+ 
+The default configuration does not include the test pages. To include them, add the following option to `_config.yml':
+
+```yaml
+include: ["docs/tests/"]
+```
diff --git a/docs/tests/navigation/exclude/excluded-child.md b/docs/tests/navigation/exclude/excluded-child.md
new file mode 100644
index 0000000..b7b4f9a
--- /dev/null
+++ b/docs/tests/navigation/exclude/excluded-child.md
@@ -0,0 +1,15 @@
+---
+layout: default
+title: Excluded Child
+parent: Not Excluded
+nav_exclude: true
+---
+# Excluded Child
+
+This child page is explicitly excluded, and should not appear in the navigation.
+
+```yaml
+title: Excluded Child
+parent: Not Excluded
+nav_exclude: true
+```
diff --git a/docs/tests/navigation/exclude/excluded-grandchild.md b/docs/tests/navigation/exclude/excluded-grandchild.md
new file mode 100644
index 0000000..2e3eadf
--- /dev/null
+++ b/docs/tests/navigation/exclude/excluded-grandchild.md
@@ -0,0 +1,17 @@
+---
+layout: default
+title: Excluded Grandchild
+parent: Non-excluded Child
+grand_parent: Non-excluded
+nav_exclude: true
+---
+# Excluded Grandchild
+
+This grandchild page is explicitly excluded, and should not appear in the navigation.
+
+```yaml
+title: Excluded Grandchild
+parent: Non-excluded Child
+grand_parent: Non-excluded
+nav_exclude: true
+```
diff --git a/docs/tests/navigation/exclude/excluded.md b/docs/tests/navigation/exclude/excluded.md
new file mode 100644
index 0000000..50cebd3
--- /dev/null
+++ b/docs/tests/navigation/exclude/excluded.md
@@ -0,0 +1,15 @@
+---
+layout: default
+title: Excluded
+has_children: true
+nav_exclude: true
+---
+# Excluded
+
+This top-level page is explicitly excluded, and should not appear in the navigation. Any child pages are implicitly excluded.
+
+```yaml
+title: Excluded
+has_children: true
+nav_exclude: true
+```
diff --git a/docs/tests/navigation/exclude/non-excluded-child-of-excluded.md b/docs/tests/navigation/exclude/non-excluded-child-of-excluded.md
new file mode 100644
index 0000000..efe478c
--- /dev/null
+++ b/docs/tests/navigation/exclude/non-excluded-child-of-excluded.md
@@ -0,0 +1,15 @@
+---
+layout: default
+title: Non-excluded Child of Excluded
+parent: Excluded
+nav_exclude: false
+---
+# Non-excluded Child of Excluded
+
+This child page is explicitly not excluded, but its parent page is excluded, so it should not appear in the navigation.
+
+```yaml
+title: Non-excluded Child of Excluded
+parent: Excluded
+nav_exclude: false
+```
diff --git a/docs/tests/navigation/exclude/non-excluded-child.md b/docs/tests/navigation/exclude/non-excluded-child.md
new file mode 100644
index 0000000..b7ec02d
--- /dev/null
+++ b/docs/tests/navigation/exclude/non-excluded-child.md
@@ -0,0 +1,16 @@
+---
+layout: default
+title: Non-excluded Child
+parent: Non-excluded
+has_children: true
+nav_exclude: false
+---
+# Non-excluded Child
+
+This child page is explicitly not excluded, and should appear in the navigation.
+
+```yaml
+title: Non-excluded Child
+parent: Non-excluded
+nav_exclude: false
+```
diff --git a/docs/tests/navigation/exclude/non-excluded-grandchild-of-excluded.md b/docs/tests/navigation/exclude/non-excluded-grandchild-of-excluded.md
new file mode 100644
index 0000000..8dc7720
--- /dev/null
+++ b/docs/tests/navigation/exclude/non-excluded-grandchild-of-excluded.md
@@ -0,0 +1,17 @@
+---
+layout: default
+title: Non-excluded Grandchild of Excluded
+parent: Non-excluded Child
+grand_parent: Excluded
+nav_exclude: false
+---
+# Non-excluded Grandchild of Excluded
+
+This grandchild page is explicitly not excluded, and neither is its parent page; but its grandparent page is excluded, so it should not appear in the navigation.
+
+```yaml
+title: Non-excluded Grandchild of Excluded
+parent: Non-excluded Child
+grand_parent: Excluded
+nav_exclude: false
+```
diff --git a/docs/tests/navigation/exclude/non-excluded-grandchild.md b/docs/tests/navigation/exclude/non-excluded-grandchild.md
new file mode 100644
index 0000000..6fc2dd1
--- /dev/null
+++ b/docs/tests/navigation/exclude/non-excluded-grandchild.md
@@ -0,0 +1,17 @@
+---
+layout: default
+title: Non-excluded Grandchild
+parent: Non-excluded Child
+grand_parent: Non-excluded
+nav_exclude: false
+---
+# Non-excluded Grandchild
+
+This grandchild page is explicitly not excluded, and neither is its parent page nor its grandparent page, so it should appear in the navigation.
+
+```yaml
+title: Non-excluded Grandchild of Excluded
+parent: Non-excluded Child
+grand_parent: Excluded
+nav_exclude: false
+```
diff --git a/docs/tests/navigation/exclude/non-excluded.md b/docs/tests/navigation/exclude/non-excluded.md
new file mode 100644
index 0000000..849c4f2
--- /dev/null
+++ b/docs/tests/navigation/exclude/non-excluded.md
@@ -0,0 +1,14 @@
+---
+layout: default
+title: Non-excluded
+has_children: true
+nav_exclude: false
+---
+# Non-excluded
+
+This top-level page is explicitly not excluded, and should appear in the navigation.
+
+```yaml
+title: Non-excluded
+nav_exclude: false
+```
diff --git a/docs/tests/navigation/exclude/untitled.md b/docs/tests/navigation/exclude/untitled.md
new file mode 100644
index 0000000..ff61925
--- /dev/null
+++ b/docs/tests/navigation/exclude/untitled.md
@@ -0,0 +1,6 @@
+---
+layout: default
+---
+# Untitled
+
+This page has no `title`, and should not appear in the navigation.
diff --git a/docs/tests/navigation/grandparent/a.md b/docs/tests/navigation/grandparent/a.md
new file mode 100644
index 0000000..23bed50
--- /dev/null
+++ b/docs/tests/navigation/grandparent/a.md
@@ -0,0 +1,14 @@
+---
+layout: default
+title: A
+has_children: true
+---
+
+# A
+
+A top-level page
+
+```yaml
+title: A
+has_children: true
+```
diff --git a/docs/tests/navigation/grandparent/b.md b/docs/tests/navigation/grandparent/b.md
new file mode 100644
index 0000000..7973bf0
--- /dev/null
+++ b/docs/tests/navigation/grandparent/b.md
@@ -0,0 +1,14 @@
+---
+layout: default
+title: B
+has_children: true
+---
+
+# B
+
+A top-level page
+
+```yaml
+title: B
+has_children: true
+```
diff --git a/docs/tests/navigation/grandparent/ca.md b/docs/tests/navigation/grandparent/ca.md
new file mode 100644
index 0000000..525428e
--- /dev/null
+++ b/docs/tests/navigation/grandparent/ca.md
@@ -0,0 +1,16 @@
+---
+layout: default
+title: C
+parent: A
+has_children: true
+---
+
+# C
+
+A child of page A, and parent of page D
+
+```yaml
+title: C
+parent: A
+has_children: true
+```
diff --git a/docs/tests/navigation/grandparent/cb.md b/docs/tests/navigation/grandparent/cb.md
new file mode 100644
index 0000000..1baa41b
--- /dev/null
+++ b/docs/tests/navigation/grandparent/cb.md
@@ -0,0 +1,16 @@
+---
+layout: default
+title: C
+parent: B
+has_children: true
+---
+
+# C
+
+A child of page B, and parent of page D
+
+```yaml
+title: C
+parent: B
+has_children: true
+```
diff --git a/docs/tests/navigation/grandparent/dca.md b/docs/tests/navigation/grandparent/dca.md
new file mode 100644
index 0000000..5ff7584
--- /dev/null
+++ b/docs/tests/navigation/grandparent/dca.md
@@ -0,0 +1,16 @@
+---
+layout: default
+title: D
+parent: C
+grand_parent: A
+---
+
+# D
+
+A grandchild of page A
+
+```yaml
+title: D
+parent: C
+grand_parent: A
+```
diff --git a/docs/tests/navigation/grandparent/dcb.md b/docs/tests/navigation/grandparent/dcb.md
new file mode 100644
index 0000000..567025d
--- /dev/null
+++ b/docs/tests/navigation/grandparent/dcb.md
@@ -0,0 +1,16 @@
+---
+layout: default
+title: D
+parent: C
+grand_parent: B
+---
+
+# D
+
+A grandchild of page B
+
+```yaml
+title: D
+parent: C
+grand_parent: B
+```
diff --git a/docs/tests/navigation/index.md b/docs/tests/navigation/index.md
new file mode 100644
index 0000000..50587d8
--- /dev/null
+++ b/docs/tests/navigation/index.md
@@ -0,0 +1,28 @@
+---
+layout: default
+title: Navigation
+parent: Tests
+---
+
+# Navigation
+
+## Parent page disambiguation
+
+- [Page A](grandparent/a/) has a child [page with title C](grandparent/ca/), and a grandchild [page with title D](grandparent/dca/).
+- [Page B](grandparent/b/) has a child [page with title C](grandparent/cb/), and a grandchild [page with title D](grandparent/dcb/).
+- The grandchild pages specify their parent and grandparent pages, so there is no ambiguity.
+
+## Page exclusion
+
+- An [untitled page](exclude/untitled/) is excluded from the navigation.
+- An excluded [top level page](exclude/excluded/), [child page](exclude/excluded-child/), or [grandchild page](exclude/excluded-grandchild/) does not appear.
+- A non-excluded [top level page](exclude/non-excluded/) appears; and a non-excluded [child page](exclude/non-excluded-child/) or [grandchild page](exclude/non-excluded-grandchild/) appears if its parent appears.
+- A non-excluded child page or grandchild page does not appear if its parent is excluded.
+
+## Page order
+
+- [Default](order/default/), using `title` instead of `nav_order` fields.
+- [Strings](order/strings/), lexicographically ordered, possibly case-insensitively.
+- [Integers](order/integers/), numerically ordered.
+- [Floats](order/floats/), numerically ordered.
+- [Mixture](order/mixture/), with numbers before strings.
diff --git a/docs/tests/navigation/order/default/10.md b/docs/tests/navigation/order/default/10.md
new file mode 100644
index 0000000..bd6fbb8
--- /dev/null
+++ b/docs/tests/navigation/order/default/10.md
@@ -0,0 +1,14 @@
+---
+layout: default
+title: "10"
+parent: Default
+grand_parent: Order
+---
+
+# 10
+
+```yaml
+title: "10"
+parent: Default
+grand_parent: Order
+```
diff --git a/docs/tests/navigation/order/default/2.md b/docs/tests/navigation/order/default/2.md
new file mode 100644
index 0000000..5e2792b
--- /dev/null
+++ b/docs/tests/navigation/order/default/2.md
@@ -0,0 +1,14 @@
+---
+layout: default
+title: "2"
+parent: Default
+grand_parent: Order
+---
+
+# 2
+
+```yaml
+title: "2"
+parent: Default
+grand_parent: Order
+```
diff --git a/docs/tests/navigation/order/default/a.md b/docs/tests/navigation/order/default/a.md
new file mode 100644
index 0000000..a122e97
--- /dev/null
+++ b/docs/tests/navigation/order/default/a.md
@@ -0,0 +1,14 @@
+---
+layout: default
+title: A
+parent: Default
+grand_parent: Order
+---
+
+# A
+
+```yaml
+title: A
+parent: Default
+grand_parent: Order
+```
diff --git a/docs/tests/navigation/order/default/aa-lower.md b/docs/tests/navigation/order/default/aa-lower.md
new file mode 100644
index 0000000..43957d6
--- /dev/null
+++ b/docs/tests/navigation/order/default/aa-lower.md
@@ -0,0 +1,14 @@
+---
+layout: default
+title: aa
+parent: Default
+grand_parent: Order
+---
+
+# aa
+
+```yaml
+title: aa
+parent: Default
+grand_parent: Order
+```
diff --git a/docs/tests/navigation/order/default/aa.md b/docs/tests/navigation/order/default/aa.md
new file mode 100644
index 0000000..081bcfc
--- /dev/null
+++ b/docs/tests/navigation/order/default/aa.md
@@ -0,0 +1,14 @@
+---
+layout: default
+title: Aa
+parent: Default
+grand_parent: Order
+---
+
+# Aa
+
+```yaml
+title: Aa
+parent: Default
+grand_parent: Order
+```
diff --git a/docs/tests/navigation/order/default/index.md b/docs/tests/navigation/order/default/index.md
new file mode 100644
index 0000000..d672d77
--- /dev/null
+++ b/docs/tests/navigation/order/default/index.md
@@ -0,0 +1,15 @@
+---
+layout: default
+title: Default
+parent: Order
+nav_order: 1
+has_children: true
+---
+
+# Default Order
+
+When `nav_order` fields are omitted, the pages are ordered alphabetically by their titles.
+
+By default, all Capital letters come before all lowercase letters; you can add `nav_sort: case_insensitive` in the configuration file to ignore the case).
+
+Digits precede letters, and numeric titles are ordered lexicographically: `10` precedes `2` (in contrast to explicit numeric `nav_order` values).
diff --git a/docs/tests/navigation/order/floats/-1.1.md b/docs/tests/navigation/order/floats/-1.1.md
new file mode 100644
index 0000000..3466e76
--- /dev/null
+++ b/docs/tests/navigation/order/floats/-1.1.md
@@ -0,0 +1,16 @@
+---
+layout: default
+title: "-1.1"
+nav_order: -1.1
+parent: Floats
+grand_parent: Order
+---
+
+# -1.1
+
+```yaml
+title: "-1.1"
+nav_order: -1.1
+parent: Floats
+grand_parent: Order
+```
diff --git a/docs/tests/navigation/order/floats/0.0.md b/docs/tests/navigation/order/floats/0.0.md
new file mode 100644
index 0000000..6c545ba
--- /dev/null
+++ b/docs/tests/navigation/order/floats/0.0.md
@@ -0,0 +1,16 @@
+---
+layout: default
+title: "0.0"
+nav_order: 0.0
+parent: Floats
+grand_parent: Order
+---
+
+# 0.0
+
+```yaml
+title: "0.0"
+nav_order: 0.0
+parent: Floats
+grand_parent: Order
+```
diff --git a/docs/tests/navigation/order/floats/10.0.md b/docs/tests/navigation/order/floats/10.0.md
new file mode 100644
index 0000000..fc648c4
--- /dev/null
+++ b/docs/tests/navigation/order/floats/10.0.md
@@ -0,0 +1,16 @@
+---
+layout: default
+title: "10.0"
+nav_order: 10.0
+parent: Floats
+grand_parent: Order
+---
+
+# 10.0
+
+```yaml
+title: "10.0"
+nav_order: 10.0
+parent: Floats
+grand_parent: Order
+```
diff --git a/docs/tests/navigation/order/floats/2.2222.md b/docs/tests/navigation/order/floats/2.2222.md
new file mode 100644
index 0000000..8050d7b
--- /dev/null
+++ b/docs/tests/navigation/order/floats/2.2222.md
@@ -0,0 +1,16 @@
+---
+layout: default
+title: "2.2222"
+nav_order: 2.2222
+parent: Floats
+grand_parent: Order
+---
+
+# 2.2222
+
+```yaml
+title: "2.2222"
+nav_order: 2.2222
+parent: Floats
+grand_parent: Order
+```
diff --git a/docs/tests/navigation/order/floats/index.md b/docs/tests/navigation/order/floats/index.md
new file mode 100644
index 0000000..2a3db37
--- /dev/null
+++ b/docs/tests/navigation/order/floats/index.md
@@ -0,0 +1,13 @@
+---
+layout: default
+title: Floats
+parent: Order
+nav_order: 4
+has_children: true
+---
+
+# Floating-Point Order
+
+When `nav_order` fields are floating-point numbers, the pages are ordered in increasing order of the numerical values.
+
+Floats include `0.0` and negative values. 
diff --git a/docs/tests/navigation/order/index.md b/docs/tests/navigation/order/index.md
new file mode 100644
index 0000000..c1b488a
--- /dev/null
+++ b/docs/tests/navigation/order/index.md
@@ -0,0 +1,8 @@
+---
+layout: default
+title: Order
+has_children: true
+nav_order: 110
+---
+
+# Order
diff --git a/docs/tests/navigation/order/integers/-1.md b/docs/tests/navigation/order/integers/-1.md
new file mode 100644
index 0000000..5b6e229
--- /dev/null
+++ b/docs/tests/navigation/order/integers/-1.md
@@ -0,0 +1,16 @@
+---
+layout: default
+title: "-1"
+nav_order: -1
+parent: Integers
+grand_parent: Order
+---
+
+# -1
+
+```yaml
+title: "-1"
+nav_order: -1
+parent: Integers
+grand_parent: Order
+```
diff --git a/docs/tests/navigation/order/integers/0.md b/docs/tests/navigation/order/integers/0.md
new file mode 100644
index 0000000..f97f599
--- /dev/null
+++ b/docs/tests/navigation/order/integers/0.md
@@ -0,0 +1,16 @@
+---
+layout: default
+title: "0"
+nav_order: 0
+parent: Integers
+grand_parent: Order
+---
+
+# 0
+
+```yaml
+title: "0"
+nav_order: 0
+parent: Integers
+grand_parent: Order
+```
diff --git a/docs/tests/navigation/order/integers/10.md b/docs/tests/navigation/order/integers/10.md
new file mode 100644
index 0000000..181bffb
--- /dev/null
+++ b/docs/tests/navigation/order/integers/10.md
@@ -0,0 +1,16 @@
+---
+layout: default
+title: "10"
+nav_order: 10
+parent: Integers
+grand_parent: Order
+---
+
+# 10
+
+```yaml
+title: "10"
+nav_order: 10
+parent: Integers
+grand_parent: Order
+```
diff --git a/docs/tests/navigation/order/integers/2.md b/docs/tests/navigation/order/integers/2.md
new file mode 100644
index 0000000..51c76c7
--- /dev/null
+++ b/docs/tests/navigation/order/integers/2.md
@@ -0,0 +1,16 @@
+---
+layout: default
+title: "2"
+nav_order: 2
+parent: Integers
+grand_parent: Order
+---
+
+# 2
+
+```yaml
+title: "2"
+nav_order: 2
+parent: Integers
+grand_parent: Order
+```
diff --git a/docs/tests/navigation/order/integers/index.md b/docs/tests/navigation/order/integers/index.md
new file mode 100644
index 0000000..674c841
--- /dev/null
+++ b/docs/tests/navigation/order/integers/index.md
@@ -0,0 +1,13 @@
+---
+layout: default
+title: Integers
+parent: Order
+nav_order: 3
+has_children: true
+---
+
+# Integer Order
+
+When `nav_order` fields are integers, the pages are ordered in increasing order of the numerical values.
+
+Integers include `0` and negative values. Integers can be reused for top-level pages and for different sets of child pages. 
diff --git a/docs/tests/navigation/order/mixture/-1.1.md b/docs/tests/navigation/order/mixture/-1.1.md
new file mode 100644
index 0000000..60b8a60
--- /dev/null
+++ b/docs/tests/navigation/order/mixture/-1.1.md
@@ -0,0 +1,16 @@
+---
+layout: default
+title: "-1.1"
+nav_order: -1.1
+parent: Mixture
+grand_parent: Order
+---
+
+# -1.1
+
+```yaml
+title: "-1.1"
+nav_order: -1.1
+parent: Mixture
+grand_parent: Order
+```
diff --git a/docs/tests/navigation/order/mixture/-1.md b/docs/tests/navigation/order/mixture/-1.md
new file mode 100644
index 0000000..81c247f
--- /dev/null
+++ b/docs/tests/navigation/order/mixture/-1.md
@@ -0,0 +1,16 @@
+---
+layout: default
+title: "-1"
+nav_order: -1
+parent: Mixture
+grand_parent: Order
+---
+
+# -1
+
+```yaml
+title: "-1"
+nav_order: -1
+parent: Mixture
+grand_parent: Order
+```
diff --git a/docs/tests/navigation/order/mixture/0.0.md b/docs/tests/navigation/order/mixture/0.0.md
new file mode 100644
index 0000000..46ea906
--- /dev/null
+++ b/docs/tests/navigation/order/mixture/0.0.md
@@ -0,0 +1,16 @@
+---
+layout: default
+title: "0.0"
+nav_order: 0.0
+parent: Mixture
+grand_parent: Order
+---
+
+# 0.0
+
+```yaml
+title: "0.0"
+nav_order: 0.0
+parent: Mixture
+grand_parent: Order
+```
diff --git a/docs/tests/navigation/order/mixture/0.md b/docs/tests/navigation/order/mixture/0.md
new file mode 100644
index 0000000..5fb96d8
--- /dev/null
+++ b/docs/tests/navigation/order/mixture/0.md
@@ -0,0 +1,16 @@
+---
+layout: default
+title: "0"
+nav_order: 0
+parent: Mixture
+grand_parent: Order
+---
+
+# 0
+
+```yaml
+title: "0"
+nav_order: 0
+parent: Mixture
+grand_parent: Order
+```
diff --git a/docs/tests/navigation/order/mixture/10.0.md b/docs/tests/navigation/order/mixture/10.0.md
new file mode 100644
index 0000000..4f137a8
--- /dev/null
+++ b/docs/tests/navigation/order/mixture/10.0.md
@@ -0,0 +1,16 @@
+---
+layout: default
+title: "10.0"
+nav_order: 10.0
+parent: Mixture
+grand_parent: Order
+---
+
+# 10.0
+
+```yaml
+title: "10.0"
+nav_order: 10.0
+parent: Mixture
+grand_parent: Order
+```
diff --git a/docs/tests/navigation/order/mixture/10.md b/docs/tests/navigation/order/mixture/10.md
new file mode 100644
index 0000000..03c7c88
--- /dev/null
+++ b/docs/tests/navigation/order/mixture/10.md
@@ -0,0 +1,14 @@
+---
+layout: default
+title: "10"
+parent: Mixture
+grand_parent: Order
+---
+
+# 10
+
+```yaml
+title: "10"
+parent: Mixture
+grand_parent: Order
+```
diff --git a/docs/tests/navigation/order/mixture/2.2222.md b/docs/tests/navigation/order/mixture/2.2222.md
new file mode 100644
index 0000000..b8d74fb
--- /dev/null
+++ b/docs/tests/navigation/order/mixture/2.2222.md
@@ -0,0 +1,16 @@
+---
+layout: default
+title: "2.2222"
+nav_order: 2.2222
+parent: Mixture
+grand_parent: Order
+---
+
+# 2.2222
+
+```yaml
+title: "2.2222"
+nav_order: 2.2222
+parent: Mixture
+grand_parent: Order
+```
diff --git a/docs/tests/navigation/order/mixture/2.md b/docs/tests/navigation/order/mixture/2.md
new file mode 100644
index 0000000..22e118b
--- /dev/null
+++ b/docs/tests/navigation/order/mixture/2.md
@@ -0,0 +1,14 @@
+---
+layout: default
+title: "2"
+parent: Mixture
+grand_parent: Order
+---
+
+# 2
+
+```yaml
+title: "2"
+parent: Mixture
+grand_parent: Order
+```
diff --git a/docs/tests/navigation/order/mixture/a.md b/docs/tests/navigation/order/mixture/a.md
new file mode 100644
index 0000000..8d36765
--- /dev/null
+++ b/docs/tests/navigation/order/mixture/a.md
@@ -0,0 +1,14 @@
+---
+layout: default
+title: A
+parent: Mixture
+grand_parent: Order
+---
+
+# A
+
+```yaml
+title: A
+parent: Mixture
+grand_parent: Order
+```
diff --git a/docs/tests/navigation/order/mixture/aa-lower.md b/docs/tests/navigation/order/mixture/aa-lower.md
new file mode 100644
index 0000000..12a8631
--- /dev/null
+++ b/docs/tests/navigation/order/mixture/aa-lower.md
@@ -0,0 +1,16 @@
+---
+layout: default
+title: aa
+nav_order: "aa"
+parent: Mixture
+grand_parent: Order
+---
+
+# aa
+
+```yaml
+title: aa
+nav_order: "aa"
+parent: Mixture
+grand_parent: Order
+```
diff --git a/docs/tests/navigation/order/mixture/aa.md b/docs/tests/navigation/order/mixture/aa.md
new file mode 100644
index 0000000..d826339
--- /dev/null
+++ b/docs/tests/navigation/order/mixture/aa.md
@@ -0,0 +1,16 @@
+---
+layout: default
+title: Aa
+nav_order: "Aa"
+parent: Mixture
+grand_parent: Order
+---
+
+# Aa
+
+```yaml
+title: Aa
+nav_order: "Aa"
+parent: Mixture
+grand_parent: Order
+```
diff --git a/docs/tests/navigation/order/mixture/index.md b/docs/tests/navigation/order/mixture/index.md
new file mode 100644
index 0000000..1d45bc7
--- /dev/null
+++ b/docs/tests/navigation/order/mixture/index.md
@@ -0,0 +1,11 @@
+---
+layout: default
+title: Mixture
+parent: Order
+nav_order: 5
+has_children: true
+---
+
+# Mixed Order
+
+It seems unlikely that different types of `nav_order` values are needed for the children of the same parent.
diff --git a/docs/tests/navigation/order/strings/10.md b/docs/tests/navigation/order/strings/10.md
new file mode 100644
index 0000000..4bc8b59
--- /dev/null
+++ b/docs/tests/navigation/order/strings/10.md
@@ -0,0 +1,16 @@
+---
+layout: default
+title: "10"
+nav_order: "10"
+parent: Strings
+grand_parent: Order
+---
+
+# 10
+
+```yaml
+title: "10"
+nav_order: "10"
+parent: Strings
+grand_parent: Order
+```
diff --git a/docs/tests/navigation/order/strings/2.md b/docs/tests/navigation/order/strings/2.md
new file mode 100644
index 0000000..be13a98
--- /dev/null
+++ b/docs/tests/navigation/order/strings/2.md
@@ -0,0 +1,16 @@
+---
+layout: default
+title: "2"
+nav_order: "2"
+parent: Strings
+grand_parent: Order
+---
+
+# 2
+
+```yaml
+title: "2"
+nav_order: "2"
+parent: Strings
+grand_parent: Order
+```
diff --git a/docs/tests/navigation/order/strings/a.md b/docs/tests/navigation/order/strings/a.md
new file mode 100644
index 0000000..71dd447
--- /dev/null
+++ b/docs/tests/navigation/order/strings/a.md
@@ -0,0 +1,16 @@
+---
+layout: default
+title: A
+nav_order: A
+parent: Strings
+grand_parent: Order
+---
+
+# A
+
+```yaml
+title: A
+nav_order: A
+parent: Strings
+grand_parent: Order
+```
diff --git a/docs/tests/navigation/order/strings/aa-lower.md b/docs/tests/navigation/order/strings/aa-lower.md
new file mode 100644
index 0000000..ea9c10b
--- /dev/null
+++ b/docs/tests/navigation/order/strings/aa-lower.md
@@ -0,0 +1,16 @@
+---
+layout: default
+title: aa
+nav_order: "aa"
+parent: Strings
+grand_parent: Order
+---
+
+# aa
+
+```yaml
+title: aa
+nav_order: "aa"
+parent: Strings
+grand_parent: Order
+```
diff --git a/docs/tests/navigation/order/strings/aa.md b/docs/tests/navigation/order/strings/aa.md
new file mode 100644
index 0000000..1daeb04
--- /dev/null
+++ b/docs/tests/navigation/order/strings/aa.md
@@ -0,0 +1,16 @@
+---
+layout: default
+title: Aa
+nav_order: "Aa"
+parent: Strings
+grand_parent: Order
+---
+
+# Aa
+
+```yaml
+title: Aa
+nav_order: "Aa"
+parent: Strings
+grand_parent: Order
+```
diff --git a/docs/tests/navigation/order/strings/index.md b/docs/tests/navigation/order/strings/index.md
new file mode 100644
index 0000000..3eb5bc5
--- /dev/null
+++ b/docs/tests/navigation/order/strings/index.md
@@ -0,0 +1,13 @@
+---
+layout: default
+title: Strings
+parent: Order
+nav_order: 2
+has_children: true
+---
+
+# String Order
+
+By default, all Capital letters come before all lowercase letters; you can add `nav_sort: case_insensitive` in the configuration file to ignore the case).
+
+Digits precede letters, and numeric titles are ordered lexicographically: `"10"` precedes `"2"` (in contrast to explicit numeric `nav_order` values).
diff --git a/docs/tests/untitled-test.md b/docs/tests/untitled-test.md
deleted file mode 100644
index 84f66d8..0000000
--- a/docs/tests/untitled-test.md
+++ /dev/null
@@ -1,6 +0,0 @@
----
-layout: default
----
-# Untitled test page
-
-This page should not appear in the navigation.

From 55f80acb4f7927a4b955d97c1884ca337654b65e Mon Sep 17 00:00:00 2001
From: Phillip Cutter 
Date: Tue, 25 Aug 2020 17:53:54 -0700
Subject: [PATCH 60/83] Added site.source to GitHub edit link

---
 _layouts/default.html | 2 +-
 1 file changed, 1 insertion(+), 1 deletion(-)

diff --git a/_layouts/default.html b/_layouts/default.html
index 4c48ae7..92ffbea 100644
--- a/_layouts/default.html
+++ b/_layouts/default.html
@@ -159,7 +159,7 @@ layout: table_wrappers
                   site.gh_edit_view_mode
                 %}
                   
      
-                    {{ site.gh_edit_link_text }}
+                    {{ site.gh_edit_link_text }}
                   
      
                 {% endif %}
               

From cdfad69c5b0ae25bc3c18de5392c9beba339a342 Mon Sep 17 00:00:00 2001
From: Phillip Cutter 
Date: Tue, 25 Aug 2020 18:08:31 -0700
Subject: [PATCH 61/83] Migrated from site.source to site.gh_edit_source

---
 _config.yml           | 1 +
 _layouts/default.html | 2 +-
 docs/configuration.md | 2 ++
 3 files changed, 4 insertions(+), 1 deletion(-)

diff --git a/_config.yml b/_config.yml
index 20bf8a1..a13f1c5 100644
--- a/_config.yml
+++ b/_config.yml
@@ -86,6 +86,7 @@ gh_edit_link: true # show or hide edit this page link
 gh_edit_link_text: "Edit this page on GitHub"
 gh_edit_repository: "https://github.com/pmarsceill/just-the-docs" # the github URL for your repo
 gh_edit_branch: "master" # the branch that your docs is served from
+# gh_edit_source: docs # the source that your files originate from
 gh_edit_view_mode: "tree" # "tree" or "edit" if you want the user to jump into the editor immediately
 
 # Color scheme currently only supports "dark", "light"/nil (default), or a custom scheme that you define
diff --git a/_layouts/default.html b/_layouts/default.html
index 92ffbea..442d44d 100644
--- a/_layouts/default.html
+++ b/_layouts/default.html
@@ -159,7 +159,7 @@ layout: table_wrappers
                   site.gh_edit_view_mode
                 %}
                   
      
-                    {{ site.gh_edit_link_text }}
+                    {{ site.gh_edit_link_text }}
                   
      
                 {% endif %}
               
diff --git a/docs/configuration.md b/docs/configuration.md
index 8b5cb97..ff4b490 100644
--- a/docs/configuration.md
+++ b/docs/configuration.md
@@ -147,6 +147,7 @@ gh_edit_link: true # show or hide edit this page link
 gh_edit_link_text: "Edit this page on GitHub."
 gh_edit_repository: "https://github.com/pmarsceill/just-the-docs" # the github URL for your repo
 gh_edit_branch: "master" # the branch that your docs is served from
+# gh_edit_source: docs # the source that your files originate from
 gh_edit_view_mode: "tree" # "tree" or "edit" if you want the user to jump into the editor immediately
 ```
 
@@ -154,6 +155,7 @@ gh_edit_view_mode: "tree" # "tree" or "edit" if you want the user to jump into t
 - `last_edit_time_format` uses Ruby's DateTime formatter; see examples and more information [at this link.](https://apidock.com/ruby/DateTime/strftime)
 - `gh_edit_repository` is the URL of the project's GitHub repository
 - `gh_edit_branch` is the branch that the docs site is served from; defaults to `master`
+- `gh_edit_source` is the source directory that your project files are stored in (should be the same as [site.source](https://jekyllrb.com/docs/configuration/options/))
 - `gh_edit_view_mode` is `"tree"` by default, which brings the user to the github page; switch to `"edit"` to bring the user directly into editing mode
 
 ## Color scheme

From 793a7247db9e15a16198466d0db79807e2f4a216 Mon Sep 17 00:00:00 2001
From: "dependabot-preview[bot]"
 <27856297+dependabot-preview[bot]@users.noreply.github.com>
Date: Wed, 26 Aug 2020 08:53:22 +0000
Subject: [PATCH 62/83] Bump prettier from 2.0.5 to 2.1.1

Bumps [prettier](https://github.com/prettier/prettier) from 2.0.5 to 2.1.1.
- [Release notes](https://github.com/prettier/prettier/releases)
- [Changelog](https://github.com/prettier/prettier/blob/master/CHANGELOG.md)
- [Commits](https://github.com/prettier/prettier/compare/2.0.5...2.1.1)

Signed-off-by: dependabot-preview[bot] 
---
 package-lock.json | 6 +++---
 package.json      | 2 +-
 2 files changed, 4 insertions(+), 4 deletions(-)

diff --git a/package-lock.json b/package-lock.json
index c28c70e..1c7aeaf 100644
--- a/package-lock.json
+++ b/package-lock.json
@@ -3753,9 +3753,9 @@
       "dev": true
     },
     "prettier": {
-      "version": "2.0.5",
-      "resolved": "https://registry.npmjs.org/prettier/-/prettier-2.0.5.tgz",
-      "integrity": "sha512-7PtVymN48hGcO4fGjybyBSIWDsLU4H4XlvOHfq91pz9kkGlonzwTfYkaIEwiRg/dAJF9YlbsduBAgtYLi+8cFg==",
+      "version": "2.1.1",
+      "resolved": "https://registry.npmjs.org/prettier/-/prettier-2.1.1.tgz",
+      "integrity": "sha512-9bY+5ZWCfqj3ghYBLxApy2zf6m+NJo5GzmLTpr9FsApsfjriNnS2dahWReHMi7qNPhhHl9SYHJs2cHZLgexNIw==",
       "dev": true
     },
     "prettier-linter-helpers": {
diff --git a/package.json b/package.json
index 0dbeaf2..8bb1d11 100644
--- a/package.json
+++ b/package.json
@@ -7,7 +7,7 @@
   "bugs": "https://github.com/pmarsceill/just-the-docs/issues",
   "devDependencies": {
     "@primer/css": "^15.1.0",
-    "prettier": "^2.0.5",
+    "prettier": "^2.1.1",
     "stylelint": "^13.6.1",
     "stylelint-config-prettier": "^8.0.2",
     "stylelint-config-primer": "^9.0.0",

From cd8d1739354b6c527fbeb9e609c9b5d9e10c9547 Mon Sep 17 00:00:00 2001
From: PLanCompS <18308236+pdmosses@users.noreply.github.com>
Date: Fri, 11 Sep 2020 18:54:32 +0200
Subject: [PATCH 63/83] Updated tests activation documenation

Apparetnly Jekyll's `include` config option cannot be used to override an `exclude`, so activating `docs/tests/` requires commenting-out that line in the `exclude` list.
---
 docs/tests/index.md | 10 ++++++++--
 1 file changed, 8 insertions(+), 2 deletions(-)

diff --git a/docs/tests/index.md b/docs/tests/index.md
index 7c03c7b..27fc4d7 100644
--- a/docs/tests/index.md
+++ b/docs/tests/index.md
@@ -9,8 +9,14 @@ nav_order: 100
 
  The main documentation pages of this theme illustrate the use of many of its features, which to some extent tests their implementation. The pages linked below provide further test cases for particular features, and may be useful for regression testing when developing new features.
  
-The default configuration does not include the test pages. To include them, add the following option to `_config.yml':
+The default configuration does not include the test pages. To include them, *commment-out* the following line in `_config.yml`:
 
 ```yaml
-include: ["docs/tests/"]
+, "docs/tests/"
 ```
+so that it is:
+```yaml
+# , "docs/tests/"
+```
+
+(Apparently Jekyll's `include` does *not* override `exclude`  for the same folder...)

From ddccec7bb76d40af39b30b30b72c63c4848cc631 Mon Sep 17 00:00:00 2001
From: PLanCompS <18308236+pdmosses@users.noreply.github.com>
Date: Fri, 11 Sep 2020 18:57:57 +0200
Subject: [PATCH 64/83] Update navigation-structure.md

Reinstated the collapsible TOC at the top, to support the reference to it right at the end of the file. (The `TOC` feature can only be used once per page, so this is the only way of illustrating the rendering of the collapsible TOC in the docs.)
---
 docs/navigation-structure.md | 9 ++++++---
 1 file changed, 6 insertions(+), 3 deletions(-)

diff --git a/docs/navigation-structure.md b/docs/navigation-structure.md
index c23906b..bb601d4 100644
--- a/docs/navigation-structure.md
+++ b/docs/navigation-structure.md
@@ -7,11 +7,14 @@ nav_order: 5
 # Navigation Structure
 {: .no_toc }
 
-## Table of contents
-{: .no_toc .text-delta }
-
+
      
+  
+    Table of contents
+  
+  {: .text-delta }
 1. TOC
 {:toc}
+
      
 
 ---
 

From fea9ae2b07df8ab62fc6d6a0814930bbc2df9a0e Mon Sep 17 00:00:00 2001
From: PLanCompS <18308236+pdmosses@users.noreply.github.com>
Date: Fri, 11 Sep 2020 19:41:55 +0200
Subject: [PATCH 65/83] Update _config.yml

url corrected
---
 _config.yml | 2 +-
 1 file changed, 1 insertion(+), 1 deletion(-)

diff --git a/_config.yml b/_config.yml
index a6f02ed..d2119ef 100644
--- a/_config.yml
+++ b/_config.yml
@@ -16,7 +16,7 @@
 title: Just the Docs
 description: A Jekyll theme for documentation
 baseurl: "/just-the-docs" # the subpath of your site, e.g. /blog
-url: "https://pdmosses.github.io" # the base hostname & protocol for your site, e.g. http://example.com
+url: "https://pmarsceill.github.io" # the base hostname & protocol for your site, e.g. http://example.com
 
 permalink: pretty
 exclude: ["node_modules/", "*.gemspec", "*.gem", "Gemfile", "Gemfile.lock", "package.json", "package-lock.json",  "script/", "LICENSE.txt", "lib/", "bin/", "README.md", "Rakefile"

From d59887cc2b99224ea08b2944b2a6c812c167a469 Mon Sep 17 00:00:00 2001
From: PLanCompS <18308236+pdmosses@users.noreply.github.com>
Date: Fri, 11 Sep 2020 19:42:44 +0200
Subject: [PATCH 66/83] Update linenos.md

doc for turning on kramdown linenos globally corrected/
---
 docs/ui-components/linenos.md | 2 +-
 1 file changed, 1 insertion(+), 1 deletion(-)

diff --git a/docs/ui-components/linenos.md b/docs/ui-components/linenos.md
index b13e6c9..a81d511 100644
--- a/docs/ui-components/linenos.md
+++ b/docs/ui-components/linenos.md
@@ -27,7 +27,7 @@ following configuration option:
 kramdown:
   syntax_highlighter_opts:
     block:
-      line_numbers: false
+      line_numbers: true
 {% endhighlight %}
 
 Line numbers can then be suppressed locally using Liquid tags (_without_ the

From f774596f5e2d77d05a665eb899b36a285838ff8a Mon Sep 17 00:00:00 2001
From: Patrick Marsceill 
Date: Fri, 11 Sep 2020 17:18:44 -0400
Subject: [PATCH 67/83] Use magic numbers for better alignment

---
 _sass/search.scss | 4 ++--
 1 file changed, 2 insertions(+), 2 deletions(-)

diff --git a/_sass/search.scss b/_sass/search.scss
index eb94cb7..4290210 100644
--- a/_sass/search.scss
+++ b/_sass/search.scss
@@ -284,13 +284,13 @@
     background-color: $search-background-color;
 
     @include mq(md) {
-      padding-left: #{$sp-4 * 1.25 + $sp-5};
+      padding-left: 2.3rem;
     }
   }
 
   .search-label {
     @include mq(md) {
-      padding-left: #{$sp-4 * 1.25};
+      padding-left: 0.6rem;
     }
   }
 

From 000da77ba2c6c7c8bb4bf5fa34456984f01bd6bc Mon Sep 17 00:00:00 2001
From: Peter Mosses <18308236+pdmosses@users.noreply.github.com>
Date: Sat, 12 Sep 2020 08:55:53 +0200
Subject: [PATCH 68/83] Update _includes/nav.html

Correction needed for use of collections.

Co-authored-by: Kevin Lin 
---
 _includes/nav.html | 2 +-
 1 file changed, 1 insertion(+), 1 deletion(-)

diff --git a/_includes/nav.html b/_includes/nav.html
index a70e2b0..976dbbd 100644
--- a/_includes/nav.html
+++ b/_includes/nav.html
@@ -1,5 +1,5 @@
 
        
-  {%- assign included_pages = site.html_pages
+  {%- assign included_pages = include.pages
         | where_exp:"item", "item.nav_exclude != true"
         | where_exp:"item", "item.title != nil" -%}
 

From 985bdc02ca0a5439ef06015f3905752dd3c98843 Mon Sep 17 00:00:00 2001
From: "dependabot-preview[bot]"
 <27856297+dependabot-preview[bot]@users.noreply.github.com>
Date: Sat, 12 Sep 2020 08:26:47 +0000
Subject: [PATCH 69/83] Bump prettier from 2.0.5 to 2.1.1

Bumps [prettier](https://github.com/prettier/prettier) from 2.0.5 to 2.1.1.
- [Release notes](https://github.com/prettier/prettier/releases)
- [Changelog](https://github.com/prettier/prettier/blob/master/CHANGELOG.md)
- [Commits](https://github.com/prettier/prettier/compare/2.0.5...2.1.1)

Signed-off-by: dependabot-preview[bot] 
---
 package-lock.json | 6 +++---
 package.json      | 2 +-
 2 files changed, 4 insertions(+), 4 deletions(-)

diff --git a/package-lock.json b/package-lock.json
index c28c70e..1c7aeaf 100644
--- a/package-lock.json
+++ b/package-lock.json
@@ -3753,9 +3753,9 @@
       "dev": true
     },
     "prettier": {
-      "version": "2.0.5",
-      "resolved": "https://registry.npmjs.org/prettier/-/prettier-2.0.5.tgz",
-      "integrity": "sha512-7PtVymN48hGcO4fGjybyBSIWDsLU4H4XlvOHfq91pz9kkGlonzwTfYkaIEwiRg/dAJF9YlbsduBAgtYLi+8cFg==",
+      "version": "2.1.1",
+      "resolved": "https://registry.npmjs.org/prettier/-/prettier-2.1.1.tgz",
+      "integrity": "sha512-9bY+5ZWCfqj3ghYBLxApy2zf6m+NJo5GzmLTpr9FsApsfjriNnS2dahWReHMi7qNPhhHl9SYHJs2cHZLgexNIw==",
       "dev": true
     },
     "prettier-linter-helpers": {
diff --git a/package.json b/package.json
index 0dbeaf2..8bb1d11 100644
--- a/package.json
+++ b/package.json
@@ -7,7 +7,7 @@
   "bugs": "https://github.com/pmarsceill/just-the-docs/issues",
   "devDependencies": {
     "@primer/css": "^15.1.0",
-    "prettier": "^2.0.5",
+    "prettier": "^2.1.1",
     "stylelint": "^13.6.1",
     "stylelint-config-prettier": "^8.0.2",
     "stylelint-config-primer": "^9.0.0",

From 020a50acff180ecdd759c31d4d52f375e606b37b Mon Sep 17 00:00:00 2001
From: Patrick Marsceill 
Date: Mon, 14 Sep 2020 10:57:42 -0400
Subject: [PATCH 70/83] Update docs/tests/navigation/exclude/untitled.md

Co-authored-by: Peter Mosses <18308236+pdmosses@users.noreply.github.com>
---
 docs/tests/navigation/exclude/untitled.md | 2 +-
 1 file changed, 1 insertion(+), 1 deletion(-)

diff --git a/docs/tests/navigation/exclude/untitled.md b/docs/tests/navigation/exclude/untitled.md
index ff61925..8fcd544 100644
--- a/docs/tests/navigation/exclude/untitled.md
+++ b/docs/tests/navigation/exclude/untitled.md
@@ -3,4 +3,4 @@ layout: default
 ---
 # Untitled
 
-This page has no `title`, and should not appear in the navigation.
+This page does not have a `title`, and it is excluded from the navigation -- unless it is located in a Jekyll collection (which provides default titles). To exclude a title-less page from the navigation, regardless of whether it is located in a collection, set `nav_exclude: true`.

From f518ff3caa64df4ed0376776e42b446bf6b20132 Mon Sep 17 00:00:00 2001
From: Patrick Marsceill 
Date: Mon, 14 Sep 2020 11:19:56 -0400
Subject: [PATCH 71/83] Update _sass/support/_variables.scss

Co-authored-by: Kevin Lin 
---
 _sass/support/_variables.scss | 2 +-
 1 file changed, 1 insertion(+), 1 deletion(-)

diff --git a/_sass/support/_variables.scss b/_sass/support/_variables.scss
index a185e5e..3ab3f05 100644
--- a/_sass/support/_variables.scss
+++ b/_sass/support/_variables.scss
@@ -19,7 +19,7 @@ $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-4: 14px !default;
 $font-size-5: 16px !default; //h3
 $font-size-6: 18px !default; //h2
 $font-size-7: 24px !default;

From ada962d917717c5d949b5d002f09a1a4cf129b1d Mon Sep 17 00:00:00 2001
From: Patrick Marsceill 
Date: Mon, 14 Sep 2020 12:07:59 -0400
Subject: [PATCH 72/83] Add current version number as a test.

---
 index.md | 3 ++-
 1 file changed, 2 insertions(+), 1 deletion(-)

diff --git a/index.md b/index.md
index 7bf9947..d64392e 100644
--- a/index.md
+++ b/index.md
@@ -4,7 +4,6 @@ title: Home
 nav_order: 1
 description: "Just the Docs is a responsive Jekyll theme with built-in search that is easily customizable and hosted on GitHub Pages."
 permalink: /
-last_modified_date: 2020-04-27T17:54:08+0000
 ---
 
 # Focus on writing good documentation
@@ -15,6 +14,8 @@ Just the Docs gives your documentation a jumpstart with a responsive Jekyll them
 
 [Get started now](#getting-started){: .btn .btn-primary .fs-5 .mb-4 .mb-md-0 .mr-2 } [View it on GitHub](https://github.com/pmarsceill/just-the-docs){: .btn .fs-5 .mb-4 .mb-md-0 }
 
+v{{ site.github.versions.just-the-docs }}
+
 ---
 
 ## Getting started

From d4da8e7e46c447dcdbc9d4682d0909080f50100e Mon Sep 17 00:00:00 2001
From: Patrick Marsceill 
Date: Mon, 14 Sep 2020 12:15:15 -0400
Subject: [PATCH 73/83] Update index.md

---
 index.md | 5 +++--
 1 file changed, 3 insertions(+), 2 deletions(-)

diff --git a/index.md b/index.md
index d64392e..c566e43 100644
--- a/index.md
+++ b/index.md
@@ -14,8 +14,9 @@ Just the Docs gives your documentation a jumpstart with a responsive Jekyll them
 
 [Get started now](#getting-started){: .btn .btn-primary .fs-5 .mb-4 .mb-md-0 .mr-2 } [View it on GitHub](https://github.com/pmarsceill/just-the-docs){: .btn .fs-5 .mb-4 .mb-md-0 }
 
-v{{ site.github.versions.just-the-docs }}
-
+{% for dep in site.github.versions %}
+  {{ dep }}: {{ dep.version }}
+{% endfor %}
 ---
 
 ## Getting started

From 575b9237f9bf3cfd8ecc11844bd331fc74620d9b Mon Sep 17 00:00:00 2001
From: Patrick Marsceill 
Date: Mon, 14 Sep 2020 12:28:14 -0400
Subject: [PATCH 74/83] Revert this

---
 index.md | 3 ---
 1 file changed, 3 deletions(-)

diff --git a/index.md b/index.md
index c566e43..fc2b709 100644
--- a/index.md
+++ b/index.md
@@ -14,9 +14,6 @@ Just the Docs gives your documentation a jumpstart with a responsive Jekyll them
 
 [Get started now](#getting-started){: .btn .btn-primary .fs-5 .mb-4 .mb-md-0 .mr-2 } [View it on GitHub](https://github.com/pmarsceill/just-the-docs){: .btn .fs-5 .mb-4 .mb-md-0 }
 
-{% for dep in site.github.versions %}
-  {{ dep }}: {{ dep.version }}
-{% endfor %}
 ---
 
 ## Getting started

From e0f7dea67f04ba7362c529a7e4a58f2493d8dca9 Mon Sep 17 00:00:00 2001
From: Patrick Marsceill 
Date: Mon, 14 Sep 2020 12:28:55 -0400
Subject: [PATCH 75/83] Update just-the-docs.gemspec

---
 just-the-docs.gemspec | 2 +-
 1 file changed, 1 insertion(+), 1 deletion(-)

diff --git a/just-the-docs.gemspec b/just-the-docs.gemspec
index 6d6d47e..0c4d3a3 100644
--- a/just-the-docs.gemspec
+++ b/just-the-docs.gemspec
@@ -7,7 +7,7 @@ Gem::Specification.new do |spec|
   spec.email         = ["patrick.marsceill@gmail.com"]
 
   spec.summary       = %q{A modern, highly customizable, and responsive Jekyll theme for documention with built-in search.}
-  spec.homepage      = "https://github.com/pdmosses/just-the-docs"
+  spec.homepage      = "https://github.com/pmarsceill/just-the-docs"
   spec.license       = "MIT"
 
   spec.files         = `git ls-files -z`.split("\x0").select { |f| f.match(%r{^(assets|bin|_layouts|_includes|lib|Rakefile|_sass|LICENSE|README)}i) }

From 68d5c56cf32ed8d0232119a548dfc5cdeacbcc61 Mon Sep 17 00:00:00 2001
From: Patrick Marsceill 
Date: Mon, 14 Sep 2020 12:40:17 -0400
Subject: [PATCH 76/83] Move this down

---
 docs/configuration.md | 96 ++++++++++++++++++++++---------------------
 1 file changed, 49 insertions(+), 47 deletions(-)

diff --git a/docs/configuration.md b/docs/configuration.md
index ff4b490..1c6a19d 100644
--- a/docs/configuration.md
+++ b/docs/configuration.md
@@ -22,53 +22,6 @@ 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 and search include normal [pages](https://jekyllrb.com/docs/pages/).
-Instead, you can also use [Jekyll collections](https://jekyllrb.com/docs/collections/) which group documents semantically together.
-
-For example, put all your documentation 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
-
-just_the_docs:
-  # Define which collections are used in just-the-docs
-  collections:
-    # Reference the "docs" collection
-    docs:
-      # Give the collection a name
-      name: Documentation
-      # Exclude the collection from the navigation
-      # Supports true or false (default)
-      nav_exclude: false
-      # Exclude the collection from the search
-      # Supports true or false (default)
-      search_exclude: false
-```
-
-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
-
-just_the_docs:
-  collections:
-    docs:
-      name: Documentation
-    tutorials:
-      name: Tutorials
-```
 
 ## Site logo
 
@@ -190,3 +143,52 @@ See [Customization]({{ site.baseurl }}{% link docs/customization.md %}) for more
 ga_tracking: UA-5555555-55
 ga_tracking_anonymize_ip: true # Use GDPR compliant Google Analytics settings (true by default)
 ```
+
+## Document collections
+
+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/) which group documents semantically together.
+
+For example, put all your documentation 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
+
+just_the_docs:
+  # Define which collections are used in just-the-docs
+  collections:
+    # Reference the "docs" collection
+    docs:
+      # Give the collection a name
+      name: Documentation
+      # Exclude the collection from the navigation
+      # Supports true or false (default)
+      nav_exclude: false
+      # Exclude the collection from the search
+      # Supports true or false (default)
+      search_exclude: false
+```
+
+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
+
+just_the_docs:
+  collections:
+    docs:
+      name: Documentation
+    tutorials:
+      name: Tutorials
+```
+

From e4246b35b04dffd53fffd82bdf051f124333f14d Mon Sep 17 00:00:00 2001
From: Patrick Marsceill 
Date: Mon, 14 Sep 2020 12:43:59 -0400
Subject: [PATCH 77/83] Update permalink

---
 docs/ui-components/{linenos.md => line-nos.md} | 1 +
 1 file changed, 1 insertion(+)
 rename docs/ui-components/{linenos.md => line-nos.md} (98%)

diff --git a/docs/ui-components/linenos.md b/docs/ui-components/line-nos.md
similarity index 98%
rename from docs/ui-components/linenos.md
rename to docs/ui-components/line-nos.md
index a81d511..3398480 100644
--- a/docs/ui-components/linenos.md
+++ b/docs/ui-components/line-nos.md
@@ -3,6 +3,7 @@ layout: default
 title: Code with line numbers
 parent: Code
 grand_parent: UI Components
+permalink: /docs/ui-components/code/line-numbers/
 ---
 
 # Configuration options

From c587c0b2171f659a3ce058c36fd29a37445a94a2 Mon Sep 17 00:00:00 2001
From: Patrick Marsceill 
Date: Mon, 14 Sep 2020 12:46:26 -0400
Subject: [PATCH 78/83] Fix heading hierarchy

---
 docs/ui-components/line-nos.md | 10 +++++-----
 1 file changed, 5 insertions(+), 5 deletions(-)

diff --git a/docs/ui-components/line-nos.md b/docs/ui-components/line-nos.md
index 3398480..5c3f1a4 100644
--- a/docs/ui-components/line-nos.md
+++ b/docs/ui-components/line-nos.md
@@ -6,7 +6,7 @@ grand_parent: UI Components
 permalink: /docs/ui-components/code/line-numbers/
 ---
 
-# Configuration options
+# Code snippets with line numbers
 
 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
@@ -40,14 +40,14 @@ Some code
 {% endhighlight %}{% endraw %}
 {% endhighlight %}
 
-# Workarounds
+## 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
+### Code fences
 
 {% highlight default %}
 {% raw %}{% capture some_var %}
@@ -59,7 +59,7 @@ Some code
 {% include fix_linenos.html code=some_var %}{% endraw %}
 {% endhighlight %}
 
-## Liquid highlighting
+### Liquid highlighting
 
 {% highlight default %}
 {% raw %}{% capture some_var %}
@@ -74,7 +74,7 @@ _Credit:_ The original version of the above workaround was suggested by
 Dmitry Hrabrov at
 .
 
-# Examples
+## Examples
 
 ```
 Some unknown code in fences

From 1b0a313c1690f497fc98a2987ebb0f064eff3ab1 Mon Sep 17 00:00:00 2001
From: Patrick Marsceill 
Date: Mon, 14 Sep 2020 12:54:55 -0400
Subject: [PATCH 79/83] Make examples more clear

---
 docs/ui-components/line-nos.md | 28 ++++++++++------------------
 1 file changed, 10 insertions(+), 18 deletions(-)

diff --git a/docs/ui-components/line-nos.md b/docs/ui-components/line-nos.md
index 5c3f1a4..6b66859 100644
--- a/docs/ui-components/line-nos.md
+++ b/docs/ui-components/line-nos.md
@@ -76,10 +76,10 @@ Dmitry Hrabrov at
 
 ## Examples
 
-```
-Some unknown code in fences
-```
+✅ Using code fences + workaround:
 
+{% highlight default %}
+{% raw %}{% capture code_fence %}
 ```js
 // Javascript code with syntax highlighting in fences
 var fun = function lang(l) {
@@ -87,21 +87,13 @@ var fun = function 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
+{% endcapture %}
+{% assign code_fence = code_fence | markdownify %}
+{% include fix_linenos.html code=code_fence %}{% endraw %}
 {% endhighlight %}
 
+✅ Using liquid highlighting + workaround:
+
 {% capture code %}
 {% highlight ruby linenos %}
 # Ruby code with syntax highlighting and fixed line numbers using Liquid
@@ -113,8 +105,8 @@ 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
+❌ 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 %}

From 84e67c34b771375702679c0973133dacb583b7cd Mon Sep 17 00:00:00 2001
From: Patrick Marsceill 
Date: Mon, 14 Sep 2020 13:19:33 -0400
Subject: [PATCH 80/83] Forgot to remove this

---
 docs/ui-components/line-nos.md | 2 --
 1 file changed, 2 deletions(-)

diff --git a/docs/ui-components/line-nos.md b/docs/ui-components/line-nos.md
index 6b66859..35f8ba9 100644
--- a/docs/ui-components/line-nos.md
+++ b/docs/ui-components/line-nos.md
@@ -78,7 +78,6 @@ Dmitry Hrabrov at
 
 ✅ Using code fences + workaround:
 
-{% highlight default %}
 {% raw %}{% capture code_fence %}
 ```js
 // Javascript code with syntax highlighting in fences
@@ -90,7 +89,6 @@ var fun = function lang(l) {
 {% endcapture %}
 {% assign code_fence = code_fence | markdownify %}
 {% include fix_linenos.html code=code_fence %}{% endraw %}
-{% endhighlight %}
 
 ✅ Using liquid highlighting + workaround:
 

From 916a9256b18093d6de13431669296be8dfbe7ac7 Mon Sep 17 00:00:00 2001
From: Patrick Marsceill 
Date: Mon, 14 Sep 2020 13:24:10 -0400
Subject: [PATCH 81/83] Forgot this too

---
 docs/ui-components/line-nos.md | 4 ++--
 1 file changed, 2 insertions(+), 2 deletions(-)

diff --git a/docs/ui-components/line-nos.md b/docs/ui-components/line-nos.md
index 35f8ba9..f9aca66 100644
--- a/docs/ui-components/line-nos.md
+++ b/docs/ui-components/line-nos.md
@@ -78,7 +78,7 @@ Dmitry Hrabrov at
 
 ✅ Using code fences + workaround:
 
-{% raw %}{% capture code_fence %}
+{% capture code_fence %}
 ```js
 // Javascript code with syntax highlighting in fences
 var fun = function lang(l) {
@@ -88,7 +88,7 @@ var fun = function lang(l) {
 ```
 {% endcapture %}
 {% assign code_fence = code_fence | markdownify %}
-{% include fix_linenos.html code=code_fence %}{% endraw %}
+{% include fix_linenos.html code=code_fence %}
 
 ✅ Using liquid highlighting + workaround:
 

From 1f30d6bf78e0daf56c2779f3cafc6b8b90155d44 Mon Sep 17 00:00:00 2001
From: Patrick Marsceill 
Date: Mon, 14 Sep 2020 13:29:09 -0400
Subject: [PATCH 82/83] Update line-nos.md

---
 docs/ui-components/line-nos.md | 4 ++--
 1 file changed, 2 insertions(+), 2 deletions(-)

diff --git a/docs/ui-components/line-nos.md b/docs/ui-components/line-nos.md
index f9aca66..1baa3da 100644
--- a/docs/ui-components/line-nos.md
+++ b/docs/ui-components/line-nos.md
@@ -47,7 +47,7 @@ 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
+### Code fences (three backticks)
 
 {% highlight default %}
 {% raw %}{% capture some_var %}
@@ -76,7 +76,7 @@ Dmitry Hrabrov at
 
 ## Examples
 
-✅ Using code fences + workaround:
+✅ Using code fences + workaround (will only show line numbers if enabled globally in `_config.yml`):
 
 {% capture code_fence %}
 ```js

From 0513c1930adc6ce4bda7c2363b3c17d273f17978 Mon Sep 17 00:00:00 2001
From: Patrick Marsceill 
Date: Mon, 14 Sep 2020 13:33:29 -0400
Subject: [PATCH 83/83] Tweak search to make it less bulky

---
 _config.yml | 6 +++---
 1 file changed, 3 insertions(+), 3 deletions(-)

diff --git a/_config.yml b/_config.yml
index 92b911b..ad42809 100644
--- a/_config.yml
+++ b/_config.yml
@@ -41,13 +41,13 @@ search:
   heading_level: 2
   # Maximum amount of previews per search result
   # Default: 3
-  previews: 3
+  previews: 2
   # Maximum amount of words to display before a matched word in the preview
   # Default: 5
-  preview_words_before: 5
+  preview_words_before: 3
   # Maximum amount of words to display after a matched word in the preview
   # Default: 10
-  preview_words_after: 10
+  preview_words_after: 3
   # Set the search token separator
   # Default: /[\s\-/]+/
   # Example: enable support for hyphenated search words