versioning.md

title	date	weight	description
Doc Versioning	2020-02-02	4	Customize navigation and banners for multiple versions of your docs.

Depending on your project's releases and versioning, you may want to let your users access previous versions of your documentation. How you deploy the previous versions is up to you. This page describes the Docsy features that you can use to provide navigation between the various versions of your docs and to display an information banner on the archived sites.

Adding a version drop-down menu

If you add some [params.versions] in hugo.toml/hugo.yaml/hugo.json, the Docsy theme adds a version selector drop down to the top-level menu. You specify a URL and a name for each version you would like to add to the menu, as in the following example:

{{< tabpane >}} {{< tab header="Configuration file:" disabled=true />}} {{< tab header="hugo.toml" lang="toml" >}}

Add your release versions here

[[params.versions]] version = "master" url = "https://master.kubeflow.org"

[[params.versions]] version = "v0.2" url = "https://v0-2.kubeflow.org"

[[params.versions]] version = "v0.3" url = "https://v0-3.kubeflow.org" {{< /tab >}} {{< tab header="hugo.yaml" lang="yaml" >}} params: versions: - version: master url: 'https://master.kubeflow.org' - version: v0.2 url: 'https://v0-2.kubeflow.org' - version: v0.3 url: 'https://v0-3.kubeflow.org' {{< /tab >}} {{< tab header="hugo.json" lang="json" >}} { "params": { "versions": [ { "version": "master", "url": "https://master.kubeflow.org" }, { "version": "v0.2", "url": "https://v0-2.kubeflow.org" }, { "version": "v0.3", "url": "https://v0-3.kubeflow.org" } ] } } {{< /tab >}} {{< /tabpane >}}

Remember to add your current version so that users can navigate back!

The default title for the version drop-down menu is Releases. To change the title, change the site parameter version_menu in hugo.toml/hugo.yaml/hugo.json:

{{< tabpane >}} {{< tab header="Configuration file:" disabled=true />}} {{< tab header="hugo.toml" lang="toml" >}} [params] version_menu = "Releases" {{< /tab >}} {{< tab header="hugo.yaml" lang="yaml" >}} params: version_menu: Releases {{< /tab >}} {{< tab header="hugo.json" lang="json" >}} { "params": { "version_menu": "Releases" } } {{< /tab >}} {{< /tabpane >}}

If you set the version_menu_pagelinks parameter to true, then links in the version drop-down menu point to the current page in the other version, instead of the main page. This can be useful if the document doesn't change much between the different versions. Note that if the current page doesn't exist in the other version, the link will be broken.

You can read more about Docsy menus in the guide to navigation and search.

Displaying a banner on archived doc sites

If you create archived snapshots for older versions of your docs, you can add a note at the top of every page in the archived docs to let readers know that they’re seeing an unmaintained snapshot and give them a link to the latest version.

For example, see the archived docs for Kubeflow v0.6:

Figure 1. The banner on the archived docs for Kubeflow v0.6

To add the banner to your doc site, make the following changes in your hugo.toml/hugo.yaml/hugo.json file:

1. Set the site parameter archived_version to true:

   {{< tabpane >}} {{< tab header="Configuration file:" disabled=true />}} {{< tab header="hugo.toml" lang="toml" >}} [params] archived_version = true {{< /tab >}} {{< tab header="hugo.yaml" lang="yaml" >}} params: archived_version: true {{< /tab >}} {{< tab header="hugo.json" lang="json" >}} { "params": { "archived_version": true } } {{< /tab >}} {{< /tabpane >}}

2. Set the site parameter version to the version of the archived doc set. For example, if the archived docs are for version 0.1:

   {{< tabpane >}} {{< tab header="Configuration file:" disabled=true />}} {{< tab header="hugo.toml" lang="toml" >}} [params] version = "0.1" {{< /tab >}} {{< tab header="hugo.yaml" lang="yaml" >}} params: version: 0.1 {{< /tab >}} {{< tab header="hugo.json" lang="json" >}} { "params": { "version": "0.1" } } {{< /tab >}} {{< /tabpane >}}

3. Make sure that site parameter url_latest_version contains the URL of the website that you want to point readers to. In most cases, this should be the URL of the latest version of your docs:

   {{< tabpane >}} {{< tab header="Configuration file:" disabled=true />}} {{< tab header="hugo.toml" lang="toml" >}} [params] url_latest_version = "https://your-latest-doc-site.com" {{< /tab >}} {{< tab header="hugo.yaml" lang="yaml" >}} params: url_latest_version: https://your-latest-doc-site.com {{< /tab >}} {{< tab header="hugo.json" lang="json" >}} { "params": { "url_latest_version": "https://your-latest-doc-site.com" } } {{< /tab >}} {{< /tabpane >}}