Versioning for a singe page

[mo-anon]

Currently, MkDocs (with plugins like mike) supports versioning at the site-wide level, meaning that versioning affects the entire documentation set. However, in many cases, versioning is only needed for specific documents or sections, while the rest of the content remains unaffected.

For example, let's say there is a single document, like a technical specification or an API reference, that needs versioning. Other parts of the site (like introduction pages, general guides, etc.) may not require multiple versions. Versioning the entire site for a single file creates unnecessary complexity and overhead, both for maintaining the documentation and for users navigating through it.

Is there a way to achieve versioning for a single site?

[kamilkrzyskow]

Hello @mo-anon,
versioning of the whole documentation makes sure the integrity is upheld. Like the navigation between documents would always work etc.

I can see several issues with versioning a single file:

1. The directory structure of the documentation could change over time, and this would result in that, the internal cross-links of the old versioned document would not be valid anymore.
2. As MkDocs is a static site generator each page is its own HTML file. So for example you have a /API/ page and an older version under /API/0.1/ the 0.1 version has a deeper directory structure, so the links might need to be readjusted to make the navigation work. But this could be resolved with using /API/latest/ to keep the same level of relative paths.
3. How would someone define the versions? In the page meta front matter? Would the version be linked to a certain commit hash?

Given the "ambiguity" of this approach, I think this needs a very subjective/opinionated solution.
As you want to version the API, you might want to look into the mkdocstrings plugin and generate several API documentations based on different commits/tags. If the plugin doesn't support this internally and you have to provide some root directory for the sources you could fetch different versions of the repository using git in CI.

[mo-anon]

The documentation of an API was just an example. Here is my problem:

I have a certain source code from which I need to document specific functions. Over time, this source code slightly changes due to new features, etc. In my documentation, I still want to keep the "old" source code, as it is still in use, but I also want to document the new one. What would be the best approach to display this? Currently, I am using tabs to separate the two versions.

[hellt]

Every other month I think about it, and I miss it a lot, indeed.

For technical docs that have subcomponents (like an embedded app or API or dependency), this would be a very nice feature.

[mo-anon]

My issue is as follows: I need to document smart contracts that, over time, are upgraded with new features or other changes. Whenever a new version is released, I need to update the documentation accordingly.

One option would be to set up a separate file in the navigation, for example:

• Smart Contract V1
• Smart Contract V2

However, this approach becomes messy as the number of versions increases. My ideal solution would be to implement versioning on a single page, allowing the user to switch between V1, V2, etc., when visiting the page.

[hellt]

yeah, I wish mkdocs would have this ability indeed

[squidfunk]

We're working on making versioning scopable and much more flexible than it currently is, as noted in our latest blog post. Please understand that we're currently working on a tectonic shift for the project, so this might still take some time, but we're working very hard on it. This currently has my undivided attention.

[mo-anon]

@squidfunk thanks for the heads up and thank you for your awesome work!!