@mikeaja & @bep, thanks for the great suggestions. Looking at the Hugo site itself, navigation is handled as one big menu.main menu, and ordering is supplied by weights. That would work fairly well. Was hoping to be able to use Sections, possibly with some hints in the config.toml file. Ideally, the book could be groked from the file structure, with a creative theme.
@blezek could you sketch out how your ideal solution looks like? The current Hugo isnāt carved in stone, so great ideas will be implemented.
I donāt really see why you canāt use Sections. I would say it doesnāt really matter what is officially navigation. For me the menu feature is more about pre-set front matter, and saving time for typical menu situations. But any Range on any defined set can make menu links.
After trying out a bunch of different documentation generators, I decided to use Hugo for building our Docs site.
Iāve altered the section/post output to display content in longform - as series of cards rather than nested pagesā¦ the idea being to build something with an I.A. more akin to ReadtheDocs, but with our own custom design approach and various effects.
Site: https://docs.barricade.io/
Public on github: https://github.com/barricadeio/docs
Iāve been meaning to write a blog post about the process and the customized parts, but for now figured Iād share here.
Iām still trying to pin down a search solution (currently using swifttype, but once the trial runs out their pricing is $250+ a month). Going to check out hugo-lunr this weekend.
2 Likes
Your documentation site looks really neat.
Just yesterday, I had to build a documentation site for which I used MkDocs, It is really nice and is specifically made for documentation sites. My documentation site http://docs.zammu.in/search.html?q=pip , It also uses lunr.js for search. Btw, putting it on GitHub also allows you to accept corrections and contributions easily, Got a correction from the MkDocs author yesterday https://github.com/zammu/docs.zammu.in/pull/1
2 Likes
Wow. This site looks fantastic!
Iāve heard good things about hugo-lunr and am curious to see your findings.
Iād love to have feedback on what you think Hugo could do better for documentation sites. Itās definitely a goal of ours and one I feel like is in reach.
We would also benefit in hearing what Hugo does well for documentation sites from your perspective.
Lastly, if you ever want to contribute to the Hugo docs we would strongly benefit from your expertise.
1 Like
MkDocs is a good documentation solution along with Sphinx and a few others.
As you are someone who has used Hugo for other things I think it would be very insightful if you could share why you chose MkDocs for your specific project.
The main reason was the availability to the āreadthedocsā theme and the ease with which I was able to set it up. I think that is because MkDocs is specifically built for Documentation. I think for Hugo to have the same ease we need some āstarter packsā which have stuff pre configured for āProject Documentationā, āBlogā, āWebsiteā etc,. Iāll add more comments after I spend some time analyzing MkDocs.
1 Like
First, that site is gorgeous. Like Isaac Hayes sexy gorgeous. Second, I just took a really quick look at the way you did the sections as ācardsā which reminds me of a project Iāve been working on for eons in my āspareā time. Lots of writers (not code writers, English/Spanish/etc writers) use some kind of virtual pasteboard layout for chapters/books. Using Hugo and/or gitbook to format output is a great idea, especially since the formats are already built into gitbook export. However, nobody has written a pleasant way to write prose and rearrange documents and then wired that up to something to spit it out. At least not that Iāve seen. Iād rather write in vim than gitbookās interface.
Anyway, great work, I am very impressed and will look more into that public repo.
@flynnduism that doc site looks absolutely fantastic. I see that the license is MIT ā but I expect there are some ānot so genericā stuff in there that means that to use the theme for something else you would have to do changes to the theme itself? Or at lteast override some templates?
/cc @spf13 - we have had other people making the most beautiful themes wanting to be added to the themes repo ā but as the themes are sub folders in another repo, I have not clue (donāt think itās possible) to do so. It would be great if we could do that, but I believe that means adding another service outside of GitHub.
Agreed. The current solution works in that itās easy and only depends on git.
An ideal solution would be a repository system that would be able to contain / share themes, partials and shortcodes and could support github full repos and files and directories within a repo. That would be a lot of work though and I donāt think worth it yet given some of the other priorities.
@flynnduism This site looks freakinā fantastic!
I donāt suppose some of this design is MIT, eh? Haha. Iām looking for a really great theme for some internal-only documentation at my work. Nevertheless, looking forward to the blog post and nice work!
Themes for documentations seem to be missing in the portfolio of Hugo. To fix this gap I decided to port a theme geared towards this department as my next project.
The Material theme was original created for Hugoās companion Mkdocs. Credits should go to Martin Donath as the original theme creator.
Check it out if you like.
5 Likes
This looks really, really good. Iām almost tempted to suggest Hugo use this for its docs.
The demo-version on themes.gohugo.io seems to be broken, though.
Good job, @digitalcraftsman - I know I will use this theme in the future.
1 Like
Thank you
I still wrap my head around this issue but I pushed some updates. Hopefully, the demo version at themes.gohugo.io will work. The local version of the build-script looked promising.
Alternatively, I hosted a demo with Github pages. Update: the problem was fixed and you can view the demo here.
Full search and localization support are still missing but the next release of Hugo looks promising for fixes 
1 Like
Iām impressed! Your site kept me and Iām visiting it - together with the repo - some times improving my own site! Job well done! Thanks for this inspiration 
We already have plans to update the Hugo docs theme via hugo#1725, but Iād love to see us mock up the docs site in this new Material theme to compare it to.
I am assessing the feasibility of porting an existing HTML documentation site to Hugo.
Itās a large documentation site (5 MB) with a lot of nested pages.
I plan to break the existing pages down from 100 Ć 50 kB pages, into 1,000 Ć 5 kB pages, for ease of reading and editing. So a nested navigation menu, capable of multiple nested levels, is a key requirement.
The state of the art in Hugo-based documentation
Iāve searched around a bit for prior art.
-
I found four themes (Material, Bootie, Grav, Alabaster) which are specifically for documentation.
These look like they would be great for simple project documentation, with a small number of pages and relatively flat structure (i.e. no nested sub-pages of sub-pages.)
Iāve put links and screenshots to those below, to save future readers the trouble of searching for them.
-
I found three examples of Hugo being used for large project documentation - Docker, Balsamiq, and Camunda.
These look much more suitable for the kind of large documentation site I need, with navigation elements that suit a deeply nested structure.
Again, Iāve put links below, to save readers the trouble of searching.
Themes
-
matcornic's port of Grav Learn
Deployed examples
- Camunda
Notes / Possible Improvements
-
Currently thereās no documentation about how to use Hugo to write a documentation site. Itās mostly geared towards people who want to use Hugo to write a blog or a simple flat website.
-
The state of documentation themes is improving, i.e. Material theme. (thanks @digitalcraftsman!) These are great for a flat documentation site with a few pages - would suit Github projects for example.
-
There is a gap in stand-alone documentation themes for large projects - currently have to look to large projects i.e. Docker, Camunda, Balsamiq and adapt their existing themes.
-
A Search Box would be a great enhancement. I see @digitalcraftsman (again!) is already on that: https://github.com/digitalcraftsman/hugo-material-docs/issues/2
It would be definetily a big plus if we could create nest pages to order a lot of content in smaller logical units. There were already discussions about it adapting the way Hugo handles sections. Keep an eye on
1 Like
Iāve hacked your Material Docs theme to have the functionality I needed. I copied & pasted stuff from the Docker Docs theme until I got something that worked.
I am no HTML / CSS / JS wizard, but it works.
See my fork: https://github.com/LiaungYip/hugo-material-docs
Todo:
- Make it look less awful
Implementation in /content/
The menu structure is defined in /config.toml:
[[menu.main]]
name = "data"
identifier = "datafilestagpages"
parent = "listfilepages"
[[menu.main]]
name = "ability"
identifier = "datafilesability"
parent = "datafilestagpages"
... dozens more ...
Then each pageās front matter points towards one of the pre-defined menu items in config.toml. Hereās content\datafilestagpages\datafilesability\appliedname.md:
+++
date = "2016-07-10"
title = "appliedname"
original_url = "listfilepages/datafilestagpages/datafilesability.html#appliedname"
[menu.main]
identifier = "datafilesability_appliedname"
parent = "datafilesability"
+++
# appliedname
## Status
Deprecated 6.05.01 - use FACT
... Rest of content follows ...
1 Like