# How to display different version docs when user switch between different document versions？

**URL:** <https://discourse.gohugo.io/t/how-to-display-different-version-docs-when-user-switch-between-different-document-versions/47841>\
**Category:** support\
**Tags:** modules\
**Created:** [January 16, 2024, 7:35am UTC](https://discourse.gohugo.io/t/how-to-display-different-version-docs-when-user-switch-between-different-document-versions/47841 "2024-01-16T07:35:02Z")\
**Posts on this page:** 9\
**Page:** 1

<div class="post-metadata">

**Author:** ![Marty\_Mcfly](https://yyz2.discourse-cdn.com/flex036/user_avatar/discourse.gohugo.io/marty_mcfly/32/21082_2.png) [@Marty\_Mcfly](https://discourse.gohugo.io/u/Marty_Mcfly)\
**Post date:** [January 16, 2024, 7:35am UTC](https://discourse.gohugo.io/t/how-to-display-different-version-docs-when-user-switch-between-different-document-versions/47841/1 "2024-01-16T07:35:02Z")

</div>

Hi team, I build a website with Hugo, the website has a documentation section, each document has a different version, users can choose to view the documents corresponding to different versions. How to display the corresponding version number when switching to a version, just like a drop-down list?

---

<div class="post-metadata">

**Author:** ![panchtatvam](https://yyz2.discourse-cdn.com/flex036/user_avatar/discourse.gohugo.io/panchtatvam/32/20935_2.png) [@panchtatvam](https://discourse.gohugo.io/u/panchtatvam)\
**Post date:** [January 16, 2024, 9:48am UTC](https://discourse.gohugo.io/t/how-to-display-different-version-docs-when-user-switch-between-different-document-versions/47841/2 "2024-01-16T09:48:17Z")

</div>

You can either create subfolders in content folder for each version like :

```auto
Content
-- version1
-- version2

```

or you may use separate subdomains for every version of whole documentation.

In [Docsy theme](https://www.docsy.dev/docs/adding-content/versioning/), they provide version selector, but even there you would require your own strategy to host versions.

Also, a similar issue is resolved as per this [comment](https://discourse.gohugo.io/t/documentation-page-version-switch/3862/5), where the every version is deployed in a separate git branch.

---

<div class="post-metadata">

**Author:** ![gvaley](https://avatars.discourse-cdn.com/v4/letter/g/9fc348/32.png) [@gvaley](https://discourse.gohugo.io/u/gvaley)\
**Post date:** [March 7, 2025, 8:24am UTC](https://discourse.gohugo.io/t/how-to-display-different-version-docs-when-user-switch-between-different-document-versions/47841/3 "2025-03-07T08:24:45Z")

</div>

We really need an out-of-the-box solution for versions.

Docsy’s git branch approach works - I guess - but has a major drawback - the versions menu definition is bound to a branch, meaning you need to redeploy all previous versions every time you deploy a new version. Otherwise their version menus will not show the latest version. The problem will worsen the more versions you deploy. Or you can try to come up with a workaround to patch the older versions’ `hugo.yaml` files directly on the web server, which could be messy.

Another drawback of the git branch approach is you loose reusability. If I wanted to reuse content between versions (which is more than likely), I wouldn’t be able to. Changing a single typo in common content would again mean redeploying all previous versions, plus the manual work of changing the content in multiple branches.

---

<div class="post-metadata">

**Author:** ![jmooring](https://yyz2.discourse-cdn.com/flex036/user_avatar/discourse.gohugo.io/jmooring/32/4214_2.png) [@jmooring](https://discourse.gohugo.io/u/jmooring)\
**Post date:** [March 7, 2025, 8:42am UTC](https://discourse.gohugo.io/t/how-to-display-different-version-docs-when-user-switch-between-different-document-versions/47841/4 "2025-03-07T08:42:21Z")

</div>

With the added complexity of:

1. Multilingual sites (now we have another dimension)
2. Filling vertically (versions)
3. Filling horizontally (languages)

---

<div class="post-metadata">

**Author:** ![gvaley](https://avatars.discourse-cdn.com/v4/letter/g/9fc348/32.png) [@gvaley](https://discourse.gohugo.io/u/gvaley)\
**Post date:** [March 7, 2025, 9:38am UTC](https://discourse.gohugo.io/t/how-to-display-different-version-docs-when-user-switch-between-different-document-versions/47841/5 "2025-03-07T09:38:46Z")

</div>

True, but all the Static Site Generators cover the basics. The things that make a difference include:

- Advanced features like multi-lingual and versions
- Architecture–you want it to be as flexible as possible to be able to implement any features not offered natively

And while having a flexible architecture is great, some cornerstone features are simply not feasible as shortcodes/plugins. Versioning is one of them.

---

<div class="post-metadata">

**Author:** ![fekete-robert](https://yyz2.discourse-cdn.com/flex036/user_avatar/discourse.gohugo.io/fekete-robert/32/13363_2.png) [@fekete-robert](https://discourse.gohugo.io/u/fekete-robert)\
**Post date:** [March 7, 2025, 3:21pm UTC](https://discourse.gohugo.io/t/how-to-display-different-version-docs-when-user-switch-between-different-document-versions/47841/6 "2025-03-07T15:21:58Z")

</div>

Hi @gvaley, I never had time to write up how it works, but with some customizations we made something like what you describe at [GitHub - kube-logging/kube-logging.github.io: Logging operator documentation](https://github.com/kube-logging/kube-logging.github.io/) .

It’s been a while so I won’t remember every detail, but:

- the versions each have their own branch and their own github workflow, so they can be deployed independently
- there is some magic using a custom output called `releases` that generates the list for the version dropdown on main, based on the versions list that you define in the config.toml, docsy-style.
- every version includes that list using some js (see [kube-logging.github.io/layouts/partials/navbar-version-selector.html at master · kube-logging/kube-logging.github.io · GitHub](https://github.com/kube-logging/kube-logging.github.io/blob/master/layouts/partials/navbar-version-selector.html), [kube-logging.github.io/layouts/partials/navbar-version-selector.release at master · kube-logging/kube-logging.github.io · GitHub](https://github.com/kube-logging/kube-logging.github.io/blob/master/layouts/partials/navbar-version-selector.release), )
- there is a customization that if a page exists in main, then it sets the canonical url to the latest release ([kube-logging.github.io/layouts/partials/hooks/head-end.html at e25e1fbd8c9d9dd80f397bd0199720c66f21a85c · kube-logging/kube-logging.github.io · GitHub](https://github.com/kube-logging/kube-logging.github.io/blob/e25e1fbd8c9d9dd80f397bd0199720c66f21a85c/layouts/partials/hooks/head-end.html#L3))
- The workflows of the separate versions publish their output under `baseurl/versionnumber/docs/`
- The latest version (published by the main workflow) is under `baseurl/docs/`

It’s probably somewhat overengineered, but seemed a good idea at the time.

---

<div class="post-metadata">

**Author:** ![jmooring](https://yyz2.discourse-cdn.com/flex036/user_avatar/discourse.gohugo.io/jmooring/32/4214_2.png) [@jmooring](https://discourse.gohugo.io/u/jmooring)\
**Post date:** [March 7, 2025, 8:28pm UTC](https://discourse.gohugo.io/t/how-to-display-different-version-docs-when-user-switch-between-different-document-versions/47841/7 "2025-03-07T20:28:31Z")

</div>

I know that some of the approaches in the wild were implemented before modules and/or segmentation became available. Just thinking out loud, a couple of questions for all…

With multilingual sites, are you currently translating by file (e.g., `foo.de.md`) or by directory (e.g., `content/de/foo.md`)?

If you are translating by directory, would you be willing to translate by file for future projects, or to convert an existing site in the same way?

Translating by file has some advantages:

1. It’s easy to see when translated content is missing.
2. It’s easy to see which resources are shared or potentially missing.

```plaintext
content/
├── common/ 
│ ├── go.mod
│ ├── snippet-1.en.md
│ ├── snippet-1.de.md
│ ├── snippet-2.en.md
│ └── snippet-2.de.md
├── v1/
│ ├── tutorials/
│ │ ├── tutorial-1/
│ │ │ ├── index.de.md
│ │ │ ├── index.en.md
│ │ │ ├── photo.de.jpg
│ │ │ └── photo.en.jpg
│ │ ├── tutorial-2/
│ │ │ ├── index.en.md <-- where's the de version?
│ │ │ └── photo.en.jpg <-- shared resource, should there be a de version?
│ │ ├── _index.de.md
│ │ └── _index.en.md
│ ├── _index.de.md
│ ├── _index.en.md
│ └── go.mod
└── v2/
    ├── _index.de.md
    ├── _index.en.md
    └── go.mod

```

If the structure above is acceptable, a mono repo with multiple modules (including content that’s shared across versions) and (possibly) segmented builds might be a decent approach.

---

<div class="post-metadata">

**Author:** ![gvaley](https://avatars.discourse-cdn.com/v4/letter/g/9fc348/32.png) [@gvaley](https://discourse.gohugo.io/u/gvaley)\
**Post date:** [March 10, 2025, 12:20pm UTC](https://discourse.gohugo.io/t/how-to-display-different-version-docs-when-user-switch-between-different-document-versions/47841/8 "2025-03-10T12:20:41Z")

</div>

Appreciate the discussion.

Off the top of my head, this structure immediately introduces an issue: If we have to name resources differently for each lang, this means redoing all links to those resources inside the MD…unless we have an intelligent mechanism that automatically translates a `photo.md` target to `photo.de.md`, `photo.en.md` according to the current lang.

As a smaller drawback, it makes the tree harder to browse, especially in the presence of dozens of languages.

If I had to choose, I’d have separate folders.

My 2 cents on your other points:

1. Personally, I wouldn’t warry about missing resources in one lang or another, as Hugo will report them missing when running server or build.
2. This spurred a thought in my mind - wouldn’t it be nice to show a default language (say, EN) when a translation is missing in a language? This would also help with broken links issues when an article is completely missing.

---

<div class="post-metadata">

**Author:** ![jmooring](https://yyz2.discourse-cdn.com/flex036/user_avatar/discourse.gohugo.io/jmooring/32/4214_2.png) [@jmooring](https://discourse.gohugo.io/u/jmooring)\
**Post date:** [March 10, 2025, 7:04pm UTC](https://discourse.gohugo.io/t/how-to-display-different-version-docs-when-user-switch-between-different-document-versions/47841/9 "2025-03-10T19:04:10Z")

</div>

> [@gvaley](#):
>
> If we have to name resources differently for each lang

You don’t.  
[https://gohugo.io/content-management/multilingual/#page-bundles](https://gohugo.io/content-management/multilingual/#page-bundles)

> [@gvaley](#):
>
> I wouldn’t warry about missing resources in one lang or another, as Hugo will report them missing when running server or build.

No, it won’t. See above.

> [@gvaley](#):
>
> wouldn’t it be nice to show a default language

You can use module mounts for content, and [lang.Merge](https://gohugo.io/functions/lang/merge/) for page collections.