Only first child in entire site gets expanded/shown in nav bar about just-the-docs HOT 8 CLOSED

@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.

from just-the-docs.

@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!

from just-the-docs.

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!

from just-the-docs.

@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.

from just-the-docs.

@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!

from just-the-docs.

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?

from just-the-docs.

@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?

from just-the-docs.

@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!

from just-the-docs.