Make it easier to create a "docs only" site #368
Merged
Conversation
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
This introduces no change in behaviour for the default case, but for sites that use cascade to render most pages as a "docs" type, it allows the tree to be correctly rooted from the home page (type docs itself) and also allows specific sections to act as their own separate root, by setting toc_root=true in their front matter.
Collaborator
|
Oh this is brilliant! You definitely weren't able to do this back when I created the "just docs" site (or at least not nearly so gracefully). Do you want to add docs on how to create a site that uses this feature as well - maybe on the increasingly huge "Adding content" page (which we may need to split)? |
|
This sounds perfect. |
Contributor
Author
|
Great! I wrote up some docs. I agree that page could probably use a bit of restructuring at some point; hopefully someone will have the time and inclination to take that on :-) |
Collaborator
|
I love it! Thanks so much for this. Merging now. |
Collaborator
|
@gwatts do you want to send a mail to the docsy-users list letting people know about the new feature? I'll update the example site with the latest Docsy as well. |
Contributor
Author
|
thanks @LisaFC ! Post sent! |
This was referenced Oct 13, 2025
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
3 participants
Add this suggestion to a batch that can be applied as a single commit.
This suggestion is invalid because no changes were made to the code.
Suggestions cannot be applied while the pull request is closed.
Suggestions cannot be applied while viewing a subset of changes.
Only one suggestion per line can be applied in a batch.
Add this suggestion to a batch that can be applied as a single commit.
Applying suggestions on deleted lines is not supported.
You must change the existing code in this line in order to create a valid suggestion.
Outdated suggestions cannot be applied.
This suggestion has been applied or marked resolved.
Suggestions cannot be applied from pending reviews.
Suggestions cannot be applied on multi-line comments.
Suggestions cannot be applied while the pull request is queued to merge.
Suggestion cannot be applied right now. Please check back later.
The "docs only" example created for issue #173 has been a super useful reference for my own internal docs site - However, I got to thinking whether Hugo's new target cascading front matter (introduced in 0.76.0) would allow us to do the same thing, with much less copying of Docsy's layout templates.
The problem with having to copy the templates, is that it becomes work to keep those templates up to date with the improvements made in the theme itself - Much better to have as little customization of those as possible.
To that end, I created a version of your example with zero custom layouts: https://github.com/gwatts/mostlydocs (example rendered: https://mostlydocs.netlify.app/ )
Getting the section menu to work correctly for that required a couple of small tweaks, which is what this PR is for.
The first commit hides the search result page from the section list on the home page. The second ensures that the home page is correctly included in the section menu, if the home page is of type "docs".
It also adds a "toc_root" parameter - I use that on the example site to add a "blog" section that does not appear in that documentation menu, so that the blog appears to be separate. Setting it to false (or omitting it), causes any blog section to be included in the tree like any other section.
Of course, if your site is really "just docs" you can just delete that blog section entirely.
None of this should have any effect on sites using Docsy today (if i've done this right ;-) ).