Only first child in entire site gets expanded/shown in nav bar

[Arthur Zey]

Describe the bug
Despite Front Matter that's exactly the same between children of a parent (except for nav_order), only the first child has the sidebar navigation expanded.

To Reproduce
Steps to reproduce the behavior:
Parent page:

---
title:          Product 1
nav_order:      200
has_children:   true
---

Test for Product 1!

Child 1:

---
title:          Overview
nav_order:      100
parent:         Product 1
has_children:   true
---

Test for Product 1!

Child 2:

---
title:          Getting Started
nav_order:      200
parent:         Product 1
has_children:   true
---

Test for Product 1!

(Removing has_children from the children doesn't change the behavior; I intended to have children in the future for these pages/sections.)

Expected behavior
Parent:

Child 1:

I expect Child 2 to look similar to Child 1 (but obviously with Child 2's content and "Getting Started" bolded in the sidebar instead of "Overview").

Screenshots
Instead, I see this:

Notice that the breadcrumbs correctly show its being nested under the parent (Product 1), but the side navbar is not open.

Interestingly, even though Product 2 (a sibling of the parent above) also has children with an equivalent structure, loading that page does not expand its navbar, either:

Desktop (please complete the following information):

• OS: macOS 14.4.1
• Browser: Chrome
• Version: 124.0.6367.8 (Official Build) beta (arm64)

Additional context

This is all rendered locally using bundle exec jekyll serve:
ruby 3.2.3 (2024-01-18 revision 52bb2ac0a6) [arm64-darwin23]
Bundler version 2.3.26
jekyll 4.3.3

This was a new installation yesterday using the template instructions, and Gemfile contents are as follows:

source 'https://rubygems.org'

gem "jekyll", "~> 4.3.3" # installed by `gem jekyll`
# gem "webrick"        # required when using Ruby >= 3 and Jekyll <= 4.2.2

gem "just-the-docs", "0.8.1" # pinned to the current release
# gem "just-the-docs"        # always download the latest release

_config.yml:

title: Product Documentation
description: Documentation for Products
theme: just-the-docs

aux_links:
  Template Repository: https://github.com/just-the-docs/just-the-docs-template

defaults:
  -
    scope:
      path: ""
    values:
      layout: "default"

[Peter Mosses]

@ArthurZey thanks for submitting this issue.

The reported behaviour appears to be due to the combination of has_children: true and front matter defaults:

_config.yml:

...
defaults:
  -
    scope:
      path: ""
    values:
      layout: "default"

After adding has_children: true to the front matter of docs/ui-components/typography.md in a local clone of the theme docs, and adding the above front matter defaults in _config.yml, I get:

The theme file assets/js/just-the-docs.js is in the scope of the defaults, and gets corrupted by the insertion of the default layout code (see the JS error log in the browser and the contents of _site/assets/js/just-the-docs.js; the navigation expanders and search also stop working).

Try limiting the scope of the front matter defaults to exclude the assets directory. If that doesn't fix the navigation issue on your site, I'll need to take a look at your repo (if public, otherwise a minimal test site that exhibits the issue) to diagnose the bug.

@mattxwang I think the theme should prevent front matter defaults from affecting its files; I'll submit a PR.

[Arthur Zey]

@pdmosses: You ROCK. This was exactly the issue, and I hope that #1447 is accepted soon.

For now, I have had to create another scope for each subdirectory of my site, which is a bit tedious and ugly, but it works.

Ideally, I would have liked to put all my content into a _docs subdirectory (that I would then make the path in the scope) and add a include: ['_docs'] line in my _config.yml, but then the problem is that the URL root starts with _docs. This wouldn't be a problem, except that I want _docs to be mapped to my URL root and then to have Jekyll respect the rest of the directory structure for constructing URLs, but some modest Googling and help from ChatGPT suggests that this isn't possible without writing some custom code. Is that consistent with your understanding?

So in my repo, /_docs/product1/getting-started/installation/index.md would get rendered in the URL as /product1/getting-started/installation/, without needing to do any manual specification for a permalink in the md file's Front Matter.

I'm out of luck, right?

Thanks again for your speedy help!

[Matt Wang]

Thanks for the detailed report @ArthurZey and the quick identification @pdmosses! I just gave an approving review, so hopefully you won't have to deal with this problem for too much longer.

I'm out of luck, right?

If it's mission critical, you can always use the branch @pdmosses made for the PR as the remote theme for your site until the fix gets merged + a release gets cut. This would let you use his changes without depending on us! But, you'd want to switch back to using the stable version once you merge.

This wouldn't be a problem, except that I want _docs to be mapped to my URL root and then to have Jekyll respect the rest of the directory structure for constructing URLs, but some modest Googling and help from ChatGPT suggests that this isn't possible without writing some custom code.

You can use Jekyll's collections-specific permalink variables to configure the output URL for each item in your collection - which can include putting them at the root!

[Peter Mosses]

@ArthurZey Thanks for confirming the suggested cause of the reported issue. #1447 has now been approved and merged into main, and should soon be included in a new release.

@mattxwang wrote:

You can use Jekyll's collections-specific permalink variables to configure the output URL for each item in your collection - which can include putting them at the root!

See the theme collection configuration docs for how to include Jekyll collections in the main navigation.

Although I've used collections extensively for Just the Docs Tests, I've never tried configuring permalinks for them, but I hope the cited Jekyll docs are clear enough.

[Matt Wang]

@ArthurZey just cut a new release - you should be able to update the RubyGem version and get the fix. Let us know if this doesn't resolve your problem!

[Arthur Zey]

I changed the version to 0.8.2 in my Gemfile after running gem update, and I can confirm that it's fixed for me! Thanks!

Also, @mattxwang and @pdmosses: At the risk of hijacking this thread inappropriately--

Thank you for suggesting collections. This is an okay approach, but the problem is that because each of my products' subdirectories has an index.md file in it, using /:path/ for the permalink properly strips out the _docs, but then appends index/ to each of my pages. Yes, I could rename every index.md file to the name of the directory that contains it and then put it one directory higher, but that's a weird workaround and then doesn't keep related files together.

So I'd want

• /_docs/product1/concepts/index.md to render at /product1/concepts/
• /_docs/product1/concepts/some-page.md to render at /product1/concepts/some-page/

I'd prefer to not have to do this:

• /_docs/product1/concepts.md to render at /product1/concepts/
• /_docs/product1/concepts/some-page.md to render at /product1/concepts/some-page/

Looking through the Jekyll and Just the Docs docs, I don't see that there's a way to achieve my goal. Is my understanding right?

[Peter Mosses]

@ArthurZey I don't have any experience with setting up permalinks for collections. It seems weird that :path includes the base filename (in contrast to :path for pages).

When publishing sites on GitHub Pages sites you can use a docs folder for the website sources. Would that allow you to get the desired URLs without the use of collections?

[Arthur Zey]

@pdmosses: Thanks for your reply. Yeah, that is weird (about :path), but I guess I'm out of luck. A docs directory wouldn't really help me (that would be unnecessary hierarchy), since the whole repo is for documentation. I just wanted to separate out content more elegantly from all the config files etc, rather than muddling it all in at the Jekyll root (so it doesn't matter much whether the Jekyll root is in docs directory of the repo or not).

Frankly, I think I'm going to go with my less-preferred option, creating a concepts.md file outside the concepts directory, for instance. It's not the end of the world.

Thank you again!