Versioning only part of the docs

[mumrah]

I was reading through the doc versioning section here https://www.docsy.dev/docs/adding-content/versioning/. For my use case, I only want to version a portion of my docs. For example, configs and API reference. Is this possible? Or must the whole site be versioned and separately deployed?

[fekete-robert]

Hi, I think this largely depends on what is your exact use case. The doc versioning you've linked was designed to provide links to versioned urls, and that's about it - it doesn't provide a way to actually deploy those versioned docs. Depending on your needs, you might have different options:

• If you want the version links only on certain pages, it should be fairly easy to customize the navbar template to show the version menu only on pages where you set a specific parameter in the frontmatter.
• If your API docs come from an external source and are on a single page, you can create a placeholder page and manually add links to each versioned API ref page.
• If the configs you've mentioned are config snippets within the content pages, you can use tabbed panes (https://www.docsy.dev/docs/adding-content/shortcodes/#tabbed-panes) to show the different versions (and use version numbers instead of languages in the header).

[mumrah]

Thanks, this gives me some ideas. My main concern was avoiding backports of pages that don't strictly need versioning, such as a quick start guide. I'm wondering if maybe two sites is the solution -- one for API and configuration reference, and one for more static stuff.

If you want the version links only on certain pages

This combined with the "these are old docs" banner might be enough.

What is the usual way for a project to deal with this problem? Do most just backport doc fixes to all previous release branches?

[fekete-robert]

I think that lots of projects just make the old docs available somehow (either as a separate site with a subdomain, or just dump the contents into a versioned folder) and forget about it. If you actually want to maintain multiple versions and be able to port/cherry-pick patches between them, then the "one-subdomain-for-each-version" is the usual way to go. Other solutions can be done as well with some customizations and tricks in your build process (and/or the well-aimed use of hugo modules), but that's not straightforward and requires some considerations - also, it's easy to overengineer it ;).

But hugo (plus github workflows or other similar things you might be using) are really flexible, so all sorts of things can be done. (An example of slight overengineering is https://kube-logging.dev/ , here we didn't use subdomains, and every version comes from a separate branch and a separate workflow, so when you modify something in an older version, you don't have to rebuild and redeploy everything, just the specific version, and even that's done automatically.)

[mumrah]

So, for kube-logging.dev, each older branch just publishes the whole site to a subdirectory? Like 4.5 publishes to https://kube-logging.dev/4.5/ and your main branch publishes to the https://kube-logging.dev root directory? That's an interesting approach. I do like that better than subdomains.

[fekete-robert]

Yes, that's right.

[repsejnworb]

I'm currently developing a solution to this for my company's needs.

I'll try and split the "framework" out into a repo to showcase it to you for inspiration.

tldr until then: I made a datafile for defining versioned parts, where I define versions, stable and a root path.
Under that path I make copies, so fx /content/apps/fisk has subdirs /latest, /v1.2, /v0.9 (these match the datafile, and both folders and datafile are handled by scripts to prevent human error).

Then apart from a bunch of helpers (like verref to link to versions) it is basically mainly driven by two partials. One calculating the state, based off the URL (selected_product, active_version (from url or stable), hidden_paths) and one that filters out hidden_paths (calced by state).

Then I just add a call to my state-partial in the head-hook and populate $Page.Store with it (don't try global for anything that will change 🤣 hugo parallell while building bugs were fun to figure out) and with a small modification to Docsy's sidebar-tree and section-info I just add a second $pages assign where I call my filtering partial (which grabs the state from the page store)