We use Hugo to render our documentation using the docDock theme and it has been great. The markdown files are versioned along with the code in their various github repositories so it’s easy to keep the documentation in sync. The problem is that each repository is therefore its own static site. We have 4 different sets of SDK documentation, each with its own navigation hierarchy. I’d love to have a shared left nav menu with links to each of the other sites in which the current site’s sub-navigation is open and the others are just the top-level links, but I’m struggling with how to get the nesting right.
So I guess I have a few related questions:
Is there a way to have all the links in a site be nested under a heading in the menu but have that heading be expanded one level automatically?
Can the top-level _index.md be linked to from that heading instead of from the home icon?
I know I can add external links with [[menu.shortcuts]] in config.toml. Can they be positioned above the main navigation based on the front matter of the files?
Regarding your main question about sharing a menu between multiple sites: the docs say that you can partition your site config into multiple files. I’m not sure how exactly you’d partition it in this case, but if you could separate all of the common config between the sites (including the common portion of the menu config) into a file or a directory, I bet you could make that part into a git submodule, the same way you add a theme. The common config would live in a separate repo with independent versioning and all of the sites would import it as a submodule.
Re 2: That sounds pretty simple. I don’t know how to configure that in that theme, but I’m confident that it could be done. The “getting started” link in the menu on https://docdock.netlify.app/original/ looks similar to what you want.
Re 3: The front matter of which files? These are external links, right? You could order the menu items in the config or the front matter of the internal pages using the weight (menu_weight?) property.
(By the way, the product suite you’re documenting sounds really cool!)
It seems like you should rather create one site and pull the content from the different parts in via Hugo Modules. Then you can store the content in different repos while still maintaining only one site.
Thank you both–I appreciate the kind words and help. I didn’t know about Hugo Modules–that could be exactly what we need! But I’m having trouble with it. When I run hugo mod init in my docs subdirectory in one of the repos, nothing seems to happen. Even when I pass it --verbose there’s no console message and no files are created. And if I run the same command again, it doesn’t complain. What might I be doing wrong?
To answer your question about the front matter:
I mean on the individual sub-sites, the menu structure is created by the subfolder structure. There’s no explicit Parent property, just notation like this at the beginning of _index.md in each subdirectory.
What I’ve found is that even if I set the weight on the `[[shortcut]`` entries to lower numbers than the weight in the front matter, the auto-generated menu items are always listed first. If I can get hugo module to work, this might be moot because all the documentation will be in the same directory structure. But I’m still trying to understand it.
It turns out that installing hugo from snap on ubuntu 18.04 was the problem. It claimed to be the right version, but the hugo mod command didn’t do anything. Once I got the proper binary installed, I was able to init the modules. Woohoo!
But I still have some confusion about how best to use modules. If I just want to import the content, should my go.mod file be in the content subfolder? (I.e. run hugo mod init in the content directory rather than at the root of the hugo project?)
I’m also trying to figure out the relationship between the import and mount config options. If I have multiple imports, does it know which import goes with which mount?
I’ll just summarize a few lessons learned here in case anyone else stumbles over the same things I did:
Don’t install hugo via snap on ubuntu 18.04. brew install works on Mac though.
config.json works better than config.yaml for specifying multiple modules with different paths. (It’s possible I could have gotten it to work with yaml with sufficient trial and error, but switching to json worked immediately!)
While it seems to work to map the layouts subfolder for all the modules to the same target, I needed to have the same sub-directory structure for static and for content in order for images to be embedded correctly.
If you point to a branch for one of the submodules while you’re developing, you can run hugo mod get github.com/myrepo/docs-src@branchname, but once you merge that branch in and delete it, you may have an issue running it again to point to master. Just delete the entries from go.mod before you re-run.