Is there a way to create a consistent menu across multiple sites?

[renaissanceGeek]

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:

1. 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?
2. Can the top-level _index.md be linked to from that heading instead of from the home icon?
3. 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?

If it helps, here is my work-in-progress for the top-level site that links to the other four: https://docs-pr-1.onrender.com/

Thank you very much!

[RobertWarrenGilmore]

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.

Regarding related question 1: This may help: https://docdock.netlify.app/original/content-organisation/#unfolded-menu-entry-by-default

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

[olafghanizadeh]

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.

[renaissanceGeek]

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:

@RobertWarrenGilmore

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.

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.

+++
title = "Server Setup"
description = ""
weight = 1
+++

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.

[olafghanizadeh]

@renaissanceGeek

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?

Can you share your config for the modules? You need to configure the correct mounts, and they will not be visible in your file system unless you vendor them.

[yaythomas]

For Hugo Modules to work, both the source/origin repo and the consuming/client repo needs to have hugo mod init run on them. . .

[pointyfar]

@yaythomas

both the source/origin repo and the consuming/client repo needs to have hugo mod init run on them. .

The consumed module does not need to be a Hugo module.

---

@renaissanceGeek it would be a lot easier to help if we could see your site source repo/s.

[renaissanceGeek]

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.e. something like this:

[module]
    [[module.imports]]
        path = "github.com/cobaltspeech/sdk-cubic/docs-src/"
    [[module.mounts]]
        source = "content"
        target = "content/sdk-cubic"
    [[module.imports]]
        path = "github.com/cobaltspeech/sdk-diatheke/docs-src/"
    [[module.mounts]]
        source = "content"
        target = "content/sdk-diatheke"

Also, relating back to my previous question, should the import path be the root or the content folder directly?

Here is the top-level repo I’m trying to link the others into: https://github.com/cobaltspeech/cobaltspeech.github.io/pull/1

Here are two of the repos that contain the actual content. They are currently stand-alone hugo sites:

cobaltspeech/sdk-cubic

cobaltspeech/sdk-diatheke

[yaythomas]

thanks! I just learnt something myself!

[pointyfar]

Here’s an example of mine while I have a look at yours:

Parent project: https://github.com/pointyfar/hmd-main
Content module: https://github.com/pointyfar/hmd-content
Theme module: https://github.com/pointyfar/hmd-theme

Site: https://brave-yalow-9c02d4.netlify.app/

On my main (hmd-main) repo, I import hmd-content, hmd-theme, which are Hugo modules, and Bulma CSS, which is not a Hugo module.

[pointyfar]

The following works for me. I had to import/mount layouts as well otherwise it complains of missing shortcodes.

hugo new site module-site
cd module-site
hugo mod init
hugo mod get github.com/cobaltspeech/sdk-cubic

[[module.imports]]
  path = "github.com/cobaltspeech/sdk-cubic"
  disable=false
  [[module.imports.mounts]]
    source="docs-src/layouts"
    target="layouts"
  [[module.imports.mounts]]
    source="docs-src/content"
    target="content/sdk-cubic"

@renaissanceGeek

If I have multiple imports, does it know which import goes with which mount?

It’s probably easier to see the relationships in json:

{
  "module": {
    "imports": [
      {
        "disable": false,
        "path": "github.com/cobaltspeech/sdk-cubic",
        "mounts": [
          {
            "source": "docs-src/layouts",
            "target": "layouts"
          },
          {
            "source": "docs-src/content",
            "target": "content/sdk-cubic"
          }
        ]
      },
      {
        "disable": false,
        "path": "other-import",
        "mounts": [
          {
            "source": "...",
            "target": "..."
          },
          {
            "source": "...",
            "target": "..."
          }
        ]
      }

    ]
  }
}

[renaissanceGeek]

Customer needs pushed this effort to the back burner for a little while, but I just wanted to close the loop and offer a big thank you to @pointyfar, @yaythomas, @olafghanizadeh, and @RobertWarrenGilmore for all your help! Hugo Modules were indeed the answer, and I now have One Site to Rule Them All for our product documentation: https://docs.cobaltspeech.com/.

I’ll just summarize a few lessons learned here in case anyone else stumbles over the same things I did:

1. Don’t install hugo via snap on ubuntu 18.04. brew install works on Mac though.
2. 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!)
3. 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.
4. 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.

Thanks again!