Hugo

How to Doc Variations

Hi There. I am trying configure Hugo to support multiple versions of roughly the same content. For example, if I had documentation for “How to configure Widget” and then I have instructions for various operating systems, say, iOS, MacOs, and Windows. So the idea would be that the page loads with “How to configure Widget for iOS” but then there is a drop-down that lets you select the other variants of the documentation.

At first I thought the multilingual feature might help out here, but then that complicates things for when you actually do want language translations. I was wondering if anyone might have some ideas on how I might go about this.

I would probably relate articles, or use a shared taxonomy term across them, perhaps “series”.

For front matter, something like:

series: widget

As for the drop-down, you could use the menu-ing system, or just build it as a partial and populate it with the links that are related or in the same series. :slight_smile:

Thanks, Maiki, I hadn’t thought of using those features in this situation.

But from an organization standpoint, I’d could still keep the markdown files in the same directory, right?

Yes. Front matter variables are how we organize our content how we want, but link them to each other and build navigation as we want. :slight_smile:

Hey Maiki,

One issue I see with using related content is that the dropdown will only include the other two alternative docs. I really want the dropdown to contain all three so that you can navigate between them. Seems like it should be easier to make a list of all the documents inside a branch bundle.

Thanks again for your input.

Okay, I gotcha. In that case, I’d say the drop-down has to contain all the things in a series, rather than related, ne? So I’d opt for a taxonomy to link the context together. Then when you grab the links for your drop-down you can list everything in whatever term you choose for that group of content pieces.

I like the front matter series, in English it’s a good word to mean what it does. I suggest trying that, and seeing if it fits your content model. :slight_smile:

So you could just use page bundles:

the relation would be implicit, rather than explicitly stated/computed (i.e. taxonomies or related content)

A directory structure could look lie this:

documentation/
├── configure-widget-a/
│   ├── index.md
│   ├── win.md
│   ├── mac.md
│   ├── ios.md
│   └── linux.md
│
├── configure-widget-b/
│   ├── index.md
│   ├── win.md
│   ├── mac.md
│   ├── ios.md
│   └── linux.md
│
...

Your templates would then render the index.md files and could pull other content from the other .md files (most likely through page resources https://gohugo.io/content-management/page-resources/).

Henry, thanks! That’s what I was thinking.

The problem I have had with this approach is developing the dropdown navigation. I have not been able to figure out how to loop though and create a list of the files in that directory. Note: some of these directories will be nested 2 or three levels down.

Thanks again, Maiki. I am going to try implementing this and see how it works.