Fix liquid variable leakage in navigation components

[pdmosses]

Fix #1118

Improve the modularity of building the nav-panel, breadcrumbs, and children-nav by making them independent. This also significantly simplifies the Liquid code.

This is purely a refactoring, and shouldn't affect the generated site (modulo layout).

[pdmosses]

Building the just-the-docs-tests repo with this PR branch gives the same site as when using [email protected] (modulo white space):

just-the-docs-tests: diff -rBwtb -x "*.js*" -x "*.map" -I "published_time|dateModified" _site-0.5.1 _site-fix-leakage       
diff -rBwtb -x *.js* -x *.map -I published_time|dateModified _site-0.5.1/customization/nav-footer/index.html _site-fix-leakage/customization/nav-footer/index.html
369c369
< just-the-docs/just-the-docs @v0.5.1</p>
---
> pdmosses/just-the-docs @fix-leakage</p>
diff -rBwtb -x *.js* -x *.map -I published_time|dateModified _site-0.5.1/index.html _site-fix-leakage/index.html
339c339
<   <dd>just-the-docs/just-the-docs @v0.5.1</dd>
---
>   <dd>pdmosses/just-the-docs @fix-leakage</dd>
just-the-docs-tests: 

Ironically, diff may itself differ, depending on the platform. The version used above is from macOS 13.3. diff --version reports only Apple diff (based on FreeBSD diff). The man pages include:

The diff utility is compliant with the IEEE Std 1003.1-2008 (“POSIX.1”) specification.

The flags [-AaDdIiLlNnPpqSsTtwXxy] are extensions to that specification.

We need to avoid diff ignoring significant differences that might affect the appearance or navigation of our websites. The following simplified set of options gives the same result as shown above:

just-the-docs-tests: diff -rw -x "*.js*" -x "*.map" -I "published_time" -I "dateModified" _site-0.5.1 _site-fix-leakage | more

Regarding the options used:

• -r: Causes application of diff recursively to common subdirectories encountered.
• -w: […] causes whitespace (blanks and tabs) to be totally ignored.
• -x "*.js*" -x "*.map": Exclude JavaScript and CSS map files and subdirectories
• -I "published_time" -I "dateModified": Ignores changes of build-dependent metadata.

In practice, changes in the Liquid code used to build HTML can easily affect where lines are broken, causing diff to report irrelevant differences on all pages. Some of the commits in this PR were merely to ensure the line breaks are the same.

[pdmosses]

@mattxwang This PR is partly preparation for updating #462 to 0.5.

[mattxwang]

Super impressive work!

Based on the previous modularization-PR, am I correct that this also means we can remove the special code in _layouts/minimal.html? If so, it'd be nice to bundle that change into this PR as well.

[pdmosses]

Based on the previous modularization-PR, am I correct that this also means we can remove the special code in _layouts/minimal.html?

Yes

If so, it'd be nice to bundle that change into this PR as well.

That was easy enough…

In a separate commit, I've also added some basic docs pages about layout. You're welcome to review those for accuracy, but let's defer discussion of improvements to them (as that can be done independently of releases).

[mattxwang]

GitHub's provided diff is a bit tricky to grok, but looking through the change I think I'm confident in these changes; paired with your diff-based test, I think this is good to merge.

Re: documentation, I appreciate the initiative on writing this up! Don't have any criticism with this; in fact, it may also help users who are struggling to get layout: default to work (there have been a few issues I've triaged with that as the problem).

Whenver you feel ready, feel free to squash-merge + add the changelog entry!

[pdmosses]

Whenver you feel ready, feel free to squash-merge + add the changelog entry!

It's a very long time since I last tried merging anything into main…

1. Do I need to merge main into the PR branch before the squash-merge?
2. And to add the changeling entry, should I simply edit it on GitHub, or should that be documented by a separate PR?

[mattxwang]

Sorry for the late response, things have been hectic.

Do I need to merge main into the PR branch before the squash-merge?

Nope! Though, you can if it helps you debug and/or gives you peace of mind; it has no impact on the final commit (if squashed).

And to add the changelog entry, should I simply edit it on GitHub, or should that be documented by a separate PR?

Simply editing it on GitHub is fine; in this case, you can also bundle it into this commit, if you'd like.