feat: add versioning setup

[h-enk]

Set up

1. In ./config/_default/params.toml under [options]:
   • set docsVersioning = true
   • add docsVersion = 1.0
2. In ./config/production/config.toml, set canonifyURLs = false
3. In ./config/_default_/config.toml under [permalinks], set docs = "/docs/1.0/:sections[1:]/:title/"
4. In ./layouts/index.redirects add:

/docs/1.0/prologue/   /docs/1.0/prologue/introduction/
/docs/1.0/help/       /docs/1.0/help/how-to-update/
/docs/1.0/            /docs/1.0/prologue/introduction/
/docs/                /docs/1.0/prologue/introduction/

/docs/0.1/*           https://v0-1-0--doks-versioning-poc.netlify.app/docs/0.1/:splat  200
/docs/0.2/*           https://v0-2-0--doks-versioning-poc.netlify.app/docs/0.2/:splat  200

5. Update ./config/_default/menus.en.toml, section [[main]]:

[[main]]
  name = "Docs"
  url = "/docs/1.0/prologue/introduction/"
  weight = 10

6. Update ./layouts/partials/header/header.html, section {{ if eq .Site.Params.options.docsVersioning true -}}, lines 107..122:

{{ if eq .Site.Params.options.docsVersioning true -}}
<div class="dropdown ms-3">
  <button class="btn btn-doks-light dropdown-toggle" id="doks-versions" data-bs-toggle="dropdown" aria-expanded="false" data-bs-display="static" aria-label="Toggle version menu">
    <span class="d-none d-lg-inline">Doks</span> v{{ .Site.Params.docsVersion }}
  </button>
  <ul class="dropdown-menu dropdown-menu-end shadow rounded border-0" aria-labelledby="doks-versions">
    <li><a class="dropdown-item current" aria-current="true" href="/docs/{{ .Site.Params.docsVersion }}/prologue/introduction/">Latest ({{ .Site.Params.docsVersion }}.x)</a></li>
    <li><hr class="dropdown-divider"></li>
    <li><a class="dropdown-item" href="/docs/0.2/prologue/introduction/">v0.2.x</a></li>
    <li><a class="dropdown-item" href="/docs/0.1/prologue/introduction/">v0.1.x</a></li>
    <li><hr class="dropdown-divider"></li>
    <li><a class="dropdown-item" href="/docs/versions/">All versions</a></li>
  </ul>
</div>
{{ end -}}

7. Update ./data/docs-versions.yml

8. In Netlify, under Site Settings > Build & deploy > Branches, set Branch deploys to All.

Process

1. Prepare new release in local code
2. Push changes
3. Add new release in Github

Notes

• When pushing changes to the master or main branch, the changes will be part of the next release, and already visible on the live website.
• Use a next branch (merge when issuing the next release), when you do not want future release changes already visible on the live website.
• Use a separate branch or repo, if would like to be able to update previous releases.

Features

• Search within a version

Resources

• Proxy to another service
• Bootstrap Docs
• twbs/bootstrap

[h-enk]

https://versioning--doks.netlify.app/

[h-enk]

POC (demo will be available w/ Doks v0.3.5): https://doks-versioning-poc.netlify.app/

[james-d-elliott]

Just noting on the v0.1.x version it's not showing v0.2.x as the latest or at all in the drop down:

https://doks-versioning-poc.netlify.app/docs/0.1/prologue/introduction/

[h-enk]

Just noting on the v0.1.x version it's not showing v0.2.x as the latest or at all in the drop down:

https://doks-versioning-poc.netlify.app/docs/0.1/prologue/introduction/

Correct, that's because future releases are not known with the present release (the docs pages are versioned). The versions page is not versioned, and always shows all versions.

[james-d-elliott]

Not overly familiar with the nuts and bolts of what is possible regarding hugo, so my intention is to provide food for thought, not delay this in its current form.

I had assumed that using a json data source we'd be able to provide the details for each page dynamically instead of doing it this way, however there may be some nuanced limitations to that or a specific reason it doesn't apply here.

Maybe that will be something to add later or something more advanced users can take advantage of if hugo doesn't support generation of json data sources itself or doesn't support it in this particular use case?

[h-enk]

Thanks for your input. Yeah, I've thought about that too. I'm not quite sure if /how (preferably no workarounds) that's possible with Hugo. I know that building pages from data source is not yet supported — see also Build pages from data source.

Definitely something to keep an eye on, and for a future change for the better. If you have ideas about how to set this up?

[james-d-elliott]

Sadly I do not, I am an absolute novice when it comes to hugo haha! I did get the impression it can kind of be done but not how, and it seems there are a lot of unsolved issues related to versioning for many themes.