Docs: Allow unlimited multi-level navigation #1440
Open
Conversation
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
This PR is intended to supersede just-the-docs#462. The only user-level difference from just-the-docs#462 is that disambiguation of parent pages has to use either `grand_parent` or `ancestor` titles: the somewhat unnatural `section_id` and `in_section` fields are not supported. The implementation has been significantly simplified by the changes introduced in v0.7.0 of the theme. This initial draft has not yet been rigorously tested nor profiled.
Unclear to me why adding this gem causes CI failures.
A page should not have a parent or ancestor with the same title. If it does, the location of the repeated link is marked by ∞, to facilitate debugging the navigation (and an unbounded loop leading to a build exception is avoided). It might be preferable to emit a warning in the Jekyll build log, but that doesn't appear to be supported by Liquid/Jekyll tags.
Reuses `nav_breadcrumbs`.
In Jekyll 3, Liquid’s binary `and` and `or` operations cannot be used in the `where_exp` filter...
Avoid diffs from sites built with v0.8.0
For backward compatibility with 3-level sites
For backward compatibility with 3-level sites
This is for backwards compatibility with sites that use `has_children: false` to suppress navigation links to child pages.
Takes account of ancestors. To test, add to 404.html front matter: ```yaml parent: T grand_parent: S ancestor: Y ``` Then check that 404.html has the correct breadcrumbs.
When activated by `nav_error_report: true` in `_config.yml`, displays warnings about pages with the same title as their parent page or an ancestral page.
The breadcrumbs for excluded pages were incorrect in previous commits, due to interference between assignments in recursive inclusions of ancestry.html.
It appears that: - `nav_levels[1] == nil` holds only when not `site_nav contains nav_list_link`; - `nav_levels[2] == nil and nav_levels[3]` never holds.
* Generate rules for any number of levels * Improve layout of generated rules * Improve layout of Liquid tags
Revert to the original code for nav/ancestry. The previous draft increased the build time 5x with Jekyll 3 for a site with about 550 pages, of which 150 are excluded from the main navigation.
The extra cached site-nav is used for determining breadcrumbs and children navigation, which may involve pages that are excluded from the main navigation. The inefficient code previously used for excluded pages is now redundant, and to be removed in a subsequent commit.
Replace code for determining children by inclusion of components/nav/children.html Profiling locally, this doesn't appear to lose efficiency.
Use a front matter default instead of depending on an extra plugin. `jekyll-default-layout` is useful on simple sites, doesn't generalise to collections.
5 tasks
Revert to v0.8.1
Improve structure and content of navigation docs pages
|
@mattxwang The failure log states: What might have caused that? The PR doesn't change |
Obsolete
After locally doing: ```sh bundle install Fetching gem metadata from https://rubygems.org/.......... Resolving dependencies... Fetching rouge 4.2.1 Fetching console 1.23.6 Installing console 1.23.6 Installing rouge 4.2.1 Bundle complete! 5 Gemfile dependencies, 63 gems now installed. Use `bundle info [gemname]` to see where a bundled gem is installed. 1 installed gem you directly depend on is looking for funding. Run `bundle fund` for details 9:15 just-the-docs: bundle lock --add-platform x86_64-linux Fetching gem metadata from https://rubygems.org/......... Resolving dependencies... Writing lockfile to /Users/pdm/Projects/GitHub/just-the-docs/Gemfile.lock ```
The deploy issue disappeared after: rm Gemfile.lock
bundle install
bundle lock --add-platform x86_64-linux |
|
I don't understand why the link in the deploy preview navigation to The latter link is not in the main navigation, so the JS code for activating and scrolling the navigation doesn't find it. Locally, the navigation works correctly. Could the issue with the deploy preview somehow be caused by case folding on macOS? GitHub shows the file with the same path as locally: Hmm: https://stackoverflow.com/questions/66297382/github-changing-the-folders-case seems to confirm that. 🙄 |
The filenames are also changed locally to lowercase, but GH Desktop doesn't notice that.
|
Forced Git to update using the simplest solution found on StackOverflow: cd .../just-the-docs
git rm -r --cached docs/navigation/main
git add --all docs/navigation/main
git status
git commit -a -m "Fixing file name casing"
git pushLogjust-the-docs: ls docs/navigation/main/
ancestry.md exclude.md index.md order.md xs.md xu.md ys.md yu.md
collections.md external.md levels.md x.md xt.md y.md yt.md
just-the-docs: git rm -r --cached docs/navigation/main
rm 'docs/navigation/main/X.md'
rm 'docs/navigation/main/XS.md'
rm 'docs/navigation/main/XT.md'
rm 'docs/navigation/main/XU.md'
rm 'docs/navigation/main/Y.md'
rm 'docs/navigation/main/YS.md'
rm 'docs/navigation/main/YT.md'
rm 'docs/navigation/main/YU.md'
rm 'docs/navigation/main/ancestry.md'
rm 'docs/navigation/main/collections.md'
rm 'docs/navigation/main/exclude.md'
rm 'docs/navigation/main/external.md'
rm 'docs/navigation/main/index.md'
rm 'docs/navigation/main/levels.md'
rm 'docs/navigation/main/order.md'
just-the-docs: git add --all docs/navigation/main
just-the-docs: git status
On branch multi-level-docs
Your branch is up to date with 'origin/multi-level-docs'.
Changes to be committed:
(use "git reset HEAD <file>..." to unstage)
renamed: docs/navigation/main/X.md -> docs/navigation/main/x.md
renamed: docs/navigation/main/XS.md -> docs/navigation/main/xs.md
renamed: docs/navigation/main/XT.md -> docs/navigation/main/xt.md
renamed: docs/navigation/main/XU.md -> docs/navigation/main/xu.md
renamed: docs/navigation/main/Y.md -> docs/navigation/main/y.md
renamed: docs/navigation/main/YS.md -> docs/navigation/main/ys.md
renamed: docs/navigation/main/YT.md -> docs/navigation/main/yt.md
renamed: docs/navigation/main/YU.md -> docs/navigation/main/yu.md
just-the-docs: git commit -a -m "Fixing file name casing"
[multi-level-docs ca94d72] Fixing file name casing
8 files changed, 0 insertions(+), 0 deletions(-)
rename docs/navigation/main/{X.md => x.md} (100%)
rename docs/navigation/main/{XS.md => xs.md} (100%)
rename docs/navigation/main/{XT.md => xt.md} (100%)
rename docs/navigation/main/{XU.md => xu.md} (100%)
rename docs/navigation/main/{Y.md => y.md} (100%)
rename docs/navigation/main/{YS.md => ys.md} (100%)
rename docs/navigation/main/{YT.md => yt.md} (100%)
rename docs/navigation/main/{YU.md => yu.md} (100%)
just-the-docs: git push
Enumerating objects: 9, done.
Counting objects: 100% (9/9), done.
Delta compression using up to 8 threads
Compressing objects: 100% (5/5), done.
Writing objects: 100% (5/5), 491 bytes | 491.00 KiB/s, done.
Total 5 (delta 4), reused 0 (delta 0)
remote: Resolving deltas: 100% (4/4), completed with 4 local objects.
To https://github.com/pdmosses/just-the-docs.git
2b4bdc3..ca94d72 multi-level-docs -> multi-level-docsThe navigation now works correctly in the deploy preview. 🎉 |
|
The current validation failure is: This is is caused by the following section heading in the source file: ## Back to TopAlthough it's possible to adjust the ID generated by Kramdown from the heading, it might be better to prefix all IDs generated by the theme with |
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
Add this suggestion to a batch that can be applied as a single commit.
This suggestion is invalid because no changes were made to the code.
Suggestions cannot be applied while the pull request is closed.
Suggestions cannot be applied while viewing a subset of changes.
Only one suggestion per line can be applied in a batch.
Add this suggestion to a batch that can be applied as a single commit.
Applying suggestions on deleted lines is not supported.
You must change the existing code in this line in order to create a valid suggestion.
Outdated suggestions cannot be applied.
This suggestion has been applied or marked resolved.
Suggestions cannot be applied from pending reviews.
Suggestions cannot be applied on multi-line comments.
Suggestions cannot be applied while the pull request is queued to merge.
Suggestion cannot be applied right now. Please check back later.
Update the theme docs for the multi-level navigation feature of #1431.
Overview of changes and additions
If #1431 is merged, the only changes and additions made by this PR will be as follows.
_config.yml:layout: defaultnav_error_report.docs/*.md:layout: defaultfrom front matterpermalinkfields by renaming files (and adjusting their paths inlinktags in other files)docs/layout/layout.md:layout: defaultdocs/navigation/*:docs.navigation-structureby some smaller pages with revised content