From 94c1dc37365b59122f178e58d03880c0819206ea Mon Sep 17 00:00:00 2001 From: Peter Mosses Date: Sat, 16 Nov 2019 11:44:46 +0100 Subject: [PATCH 01/19] 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/19] 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/19] 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/19] 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/19] 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/19] 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 86061c80a476718eff414b621a608bd0f2baf6bd Mon Sep 17 00:00:00 2001 From: PLanCompS <18308236+pdmosses@users.noreply.github.com> Date: Mon, 27 Jul 2020 14:19:06 +0200 Subject: [PATCH 07/19] grandchildren-test removed --- 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 --------- 5 files changed, 52 deletions(-) delete mode 100644 docs/grandchildren-test/buttons.md delete mode 100644 docs/grandchildren-test/buttons/grandchild.md delete mode 100644 docs/grandchildren-test/index.md delete mode 100644 docs/grandchildren-test/labels.md delete mode 100644 docs/grandchildren-test/labels/label-grandchild.md diff --git a/docs/grandchildren-test/buttons.md b/docs/grandchildren-test/buttons.md deleted file mode 100644 index 96fc21e..0000000 --- a/docs/grandchildren-test/buttons.md +++ /dev/null @@ -1,11 +0,0 @@ ---- -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 deleted file mode 100644 index 093d200..0000000 --- a/docs/grandchildren-test/buttons/grandchild.md +++ /dev/null @@ -1,9 +0,0 @@ ---- -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 deleted file mode 100644 index dd03d58..0000000 --- a/docs/grandchildren-test/index.md +++ /dev/null @@ -1,12 +0,0 @@ ---- -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 deleted file mode 100644 index f4b9ea8..0000000 --- a/docs/grandchildren-test/labels.md +++ /dev/null @@ -1,11 +0,0 @@ ---- -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 deleted file mode 100644 index f6c9550..0000000 --- a/docs/grandchildren-test/labels/label-grandchild.md +++ /dev/null @@ -1,9 +0,0 @@ ---- -layout: default -title: Labels Child Page -parent: Labels -grand_parent: Grandchildren test ---- - -Labels Child Page ----- From 83ec5533489f344bd237c381e6decbecefa850f2 Mon Sep 17 00:00:00 2001 From: PLanCompS <18308236+pdmosses@users.noreply.github.com> Date: Mon, 10 Aug 2020 15:58:42 +0200 Subject: [PATCH 08/19] Ensure pages with nav_exclude are ignored by navigation Pages with `nav_exclude: true` were included when sorting on `title` or `nav_order`. That could cause build failures when the type of value of the field differs from that on other pages, as reported in https://github.com/pmarsceill/just-the-docs/issues/406. Pages with `nav_exclude: true` or no `title` are never displayed in the navigation, so removing them from `pages_list` cannot break existing sites. This change also allows the removal of some tests in the code. (The indentation of the code should now be adjusted, but that has been deferred, to restrict the size of the diff for review.) For testing, the title of `404.html` has been changed to the number `404`, the page `docs/untitled-test.md` has been added, and `nav_sort_order` has been set to `case_sensitive`. Those updates give build failures with the current version of `_includes/nav.html`, but not after the suggested changes. It will still be possible for build failures to occur due to sorting fields of *non-excluded* pages with differing types of values (e.g., `nav_order`a mixture of numbers and strings). To make the code completely safe will require relatively complicated changes,. --- 404.html | 2 +- _config.yml | 4 ++-- _includes/nav.html | 11 ++++------- docs/untitled-test.md | 6 ++++++ 4 files changed, 13 insertions(+), 10 deletions(-) create mode 100644 docs/untitled-test.md diff --git a/404.html b/404.html index 1e7a37e..5fde966 100644 --- a/404.html +++ b/404.html @@ -1,6 +1,6 @@ --- layout: default -title: Page not found +title: 404 permalink: /404 nav_exclude: true search_exclude: true diff --git a/_config.yml b/_config.yml index 20bf8a1..fd71b51 100644 --- a/_config.yml +++ b/_config.yml @@ -63,8 +63,8 @@ aux_links: aux_links_new_tab: false # Sort order for navigation links -nav_sort: case_insensitive # default, equivalent to nil -# nav_sort: case_sensitive # Capital letters sorted before lowercase +# nav_sort: case_insensitive # default, equivalent to nil +nav_sort: case_sensitive # Capital letters sorted before lowercase # Footer content # appears at the bottom of every page's main content diff --git a/_includes/nav.html b/_includes/nav.html index f2ec7e5..d74c17c 100644 --- a/_includes/nav.html +++ b/_includes/nav.html @@ -1,6 +1,7 @@
    - {%- 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 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" -%} {%- 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" -%} @@ -10,8 +11,7 @@ {%- 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 node.parent == nil -%}
  • {%- if page.parent == node.title or page.grand_parent == node.title -%} {%- assign first_level_url = node.url | absolute_url -%} @@ -24,7 +24,6 @@ {%- 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 | absolute_url -%} @@ -44,12 +43,10 @@
    {%- endif -%}
    • - {%- endunless -%} {%- endfor -%}
{%- endif -%} {%- endif -%} - {%- endunless -%} {%- endfor -%} 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 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 09/19] 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 10/19] 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 11/19] 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 12/19] 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 13/19] 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 14/19] 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 15/19] 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 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 16/19] 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 17/19] 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 18/19] 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 19/19] 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