Fix: auto-generated child navigation (TOC) (#1590)

Fix #1587

As reported in issue #1587, the auto-generated child navigation (TOC) has a bug: it can be incorrectly omitted. This happens when the first page built is a parent page. The omission is caused by a side-effect of including the cached site-nav HTML: the code that generates the site-nav is executed the first time the cached HTML is included, and assignments in the executed code may overwrite the values of variables. 

@kevinlin1 suggested a simple and safe way to fix this bug: move the inclusion of the site-nav in `components/children_nav.html` so that it is executed before all local assignments. This PR implements that suggestion, and applies the same fix to two other files.

### Testing

A test for this bug has been added to the [_Just the Docs Tests_ repo](https://github.com/just-the-docs/just-the-docs-tests). The first page rendered when building the website is `About this site` in the TESTS collection, and it is now the `parent` of the page [`Test TOC`](https://just-the-docs.github.io/just-the-docs-tests/tests/about/test-toc/), which should be listed in its auto-generated child navigation. (The test page uses `nav_exclude: true` to avoid the link to it appearing in the main navigation, but that doesn't affect the test of this PR.)

The following steps check that the bug appears when building _Just the Docs Tests_ with v0.10.0 of the theme:

1. Clone the [Just the Docs Tests repo](https://github.com/just-the-docs/just-the-docs-tests).
2. Build and serve the website locally using:
    ```sh
    JTD_ORG=just-the-docs JTD_REF=v0.10.0 bundle install
    JTD_ORG=just-the-docs JTD_REF=v0.10.0 bundle exec jekyll serve
    ```
3. Check that the `Test TOC` page at `.../just-the-docs-tests/tests/about/test-toc/` is a child of the `About this site` page at `.../just-the-docs-tests/tests/about/`.
4. Check that no auto-generated child navigation appears on the latter page.

The following steps check that the bug does not appear when building _Just the Docs Tests_ with this PR branch:

5. Build and serve the website locally using:
    ```sh
    JTD_ORG=pdmosses JTD_REF=fix-toc bundle install
    JTD_ORG=pdmosses JTD_REF=fix-toc bundle exec jekyll serve
    ```
6. Check that the `Test TOC` page at `.../just-the-docs-tests/tests/about/test-toc/` is a child of the `About this site` page at `.../just-the-docs-tests/tests/about/`.
7. Check that an auto-generated child navigation with a link to the `Test TOC` page appears on the latter page.

(It seems unnecessary to check that the reported bug does not appear on other pages, since subsequent includes of the cached site-nav cannot assign to any variables.)

CHANGELOG.md

@@ -18,12 +18,14 @@ This website is built from the `HEAD` of the `main` branch of the theme reposito
 Code changes to `main` that are *not* in the latest release:
 
 - Fixed: `back_to_top` not displaying when no other footer variables are set by [@mattxwang] in [#1461]
+- Fixed: auto-generated child navigation (TOC) by [@pdmosses] in [#1590]
 
 Docs changes made since the latest release:
 
 - N/A
 
 [#1461]: https://github.com/just-the-docs/just-the-docs/pull/1461
+[#1590]: https://github.com/just-the-docs/just-the-docs/pull/1590
 
 ## Release v0.10.0
 

_includes/components/breadcrumbs.html

@@ -11,14 +11,14 @@
 
 {%- if page.url != "/" and page.parent and page.title -%}
 
-{%- capture nav_list_link -%}
-<a href="{{ page.url | relative_url }}" class="nav-list-link">
-{%- endcapture -%}
-
 {%- capture site_nav -%}
 {%- include_cached components/site_nav.html all=true -%}
 {%- endcapture -%}
 
+{%- capture nav_list_link -%}
+<a href="{{ page.url | relative_url }}" class="nav-list-link">
+{%- endcapture -%}
+
 {%- capture nav_list_simple -%}
 <ul class="nav-list">
 {%- endcapture -%}

_includes/components/children_nav.html

@@ -11,23 +11,24 @@
 {%- comment -%}
   Whether a page has any children is checked efficiently by inspecting the cached
   site_nav. If the page has no children, nav_children is set to an empty array;
-  otherwise nav_children is left unset.
+  otherwise nav_children is left unset. (The site_nav is rendered the first time
+  it is included, and that may overwrite various variables.)
 {%- endcomment -%}
 
 {%- if page.has_children == false -%}
   {%- assign nav_children = "" | split: "" -%}
 {%- else -%}
 
+  {%- capture site_nav -%}
+  {%- include_cached components/site_nav.html all=true -%}
+  {%- endcapture -%}
+
   {%- assign nav_children = nil -%}
 
   {%- capture nav_list_link -%}
   <a href="{{ page.url | relative_url }}" class="nav-list-link">
   {%- endcapture -%}
 
-  {%- capture site_nav -%}
-  {%- include_cached components/site_nav.html all=true -%}
-  {%- endcapture -%}
-
   {%- capture nav_list_simple -%}
   <ul class="nav-list">
   {%- endcapture -%}

_includes/css/activation.scss.liquid

@@ -20,6 +20,10 @@
   - The other two rules ensure that all folding collections are expanded.
 {%- endcomment -%}
 
+{%- capture site_nav -%}
+{%- include_cached components/site_nav.html -%}
+{%- endcapture -%}
+
 {%- capture activation_no_nav_link %}
     .site-nav ul li a {
       background-image: none;
@@ -39,10 +43,6 @@
 <a href="{{ page.url | relative_url }}" class="nav-list-link">
 {%- endcapture -%}
 
-{%- capture site_nav -%}
-{%- include_cached components/site_nav.html -%}
-{%- endcapture -%}
-
 {%- if site_nav contains nav_list_link -%}
 
   {%- capture nav_list -%}