mirror of
https://github.com/snachodog/just-the-docs.git
synced 2025-04-26 13:02:23 -06:00
bce3c32f46
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.)