# Doc versioning mechanism
**URL:** https://discourse.cmake.org/t/doc-versioning-mechanism/4814
**Category:** Development
**Created:** [January 11, 2022, 8:18am UTC](https://discourse.cmake.org/t/doc-versioning-mechanism/4814 "2022-01-11T08:18:21Z")
**Posts on this page:** 12
**Page:** 1
### Author:  [@jwuttke](https://discourse.cmake.org/u/jwuttke)
#### Post date: [January 11, 2022, 8:18am UTC](https://discourse.cmake.org/t/doc-versioning-mechanism/4814/1 "2022-01-11T08:18:21Z")
The versioning mechanism of the CMake docs is outstanding. I’d like to copy it in a project of mine. I cannot find the sources though, at least not by grepping for “This documents an old version of”
or “Click here to see the latest release” or “select a version from the drop-down menu above”
Is the versioning mechanism part of the CMake sources? Or does it come with a Sphinx module? Is it open source at all?
---
### Author:  [@ben.boeckel](https://discourse.cmake.org/u/ben.boeckel)
#### Post date: [January 11, 2022, 1:31pm UTC](https://discourse.cmake.org/t/doc-versioning-mechanism/4814/2 "2022-01-11T13:31:38Z")
@brad.king
---
### Author:  [@brad.king](https://discourse.cmake.org/u/brad.king)
#### Post date: [January 11, 2022, 2:28pm UTC](https://discourse.cmake.org/t/doc-versioning-mechanism/4814/3 "2022-01-11T14:28:44Z")
We configure sphinx with a custom template directory [here](https://gitlab.kitware.com/cmake/cmake/-/blob/v3.22.1/Utilities/Sphinx/conf.py.in#L29). That directory contains a custom layout template, which has [special version switch code](https://gitlab.kitware.com/cmake/cmake/-/blob/v3.22.1/Utilities/Sphinx/templates/layout.html#L20-25) activated by passing `-A versionswitch=1` when [running sphinx](https://gitlab.kitware.com/cmake/cmake/-/blob/v3.22.1/.gitlab/os-linux.yml#L492). The version switch code loads `version_switch.js`, which we publish on the web host [here](https://cmake.org/cmake/help/version_switch.js).
The addition of the “This documents an old version of” and “Click here to see the latest release” is done by internal infrastructure we use to prepare the documentation for publication on `cmake.org`. Basically it updates that same `layout.html` template:
```auto
{%- block relbar1 %}
{{ super() }}
{% if outdated is defined %}
{% endif %}
{% endblock %}
```
Then all the versions except the latest are built with the sphinx `-A outdated=1` flag.
---
### Author:  [@jwuttke](https://discourse.cmake.org/u/jwuttke)
#### Post date: [January 11, 2022, 2:46pm UTC](https://discourse.cmake.org/t/doc-versioning-mechanism/4814/4 "2022-01-11T14:46:04Z")
That’s very helpful. Many thanks, Brad.
The “internal infrastructure” you mention is just a few scripts to run Sphinx and deploy? Hence nothing I need to worry about before deciding on whether to take the CMake docs as template for my own project?
---
### Author:  [@brad.king](https://discourse.cmake.org/u/brad.king)
#### Post date: [January 11, 2022, 2:47pm UTC](https://discourse.cmake.org/t/doc-versioning-mechanism/4814/5 "2022-01-11T14:47:49Z")
Yes, the internal infrastructure just makes a few tweaks for publication on `cmake.org`. It’s nothing heavy. My post above links everything you should need for the version scheme.
---
### Author:  [@hwhsu1231](https://discourse.cmake.org/u/hwhsu1231)
#### Post date: [April 21, 2023, 5:10pm UTC](https://discourse.cmake.org/t/doc-versioning-mechanism/4814/6 "2023-04-21T17:10:37Z")
Excuse me @brad.king. I wondered how does CMake Team maintain/update `version_switch.js` and some other important files hosted in the the `https://cmake.org/cmake/help` automatically?
---
### Author:  [@brad.king](https://discourse.cmake.org/u/brad.king)
#### Post date: [April 25, 2023, 6:12pm UTC](https://discourse.cmake.org/t/doc-versioning-mechanism/4814/7 "2023-04-25T18:12:34Z")
`version_switch.js` is updated and pushed to `cmake.org` manually as part of our release process.
---
### Author:  [@hwhsu1231](https://discourse.cmake.org/u/hwhsu1231)
#### Post date: [April 30, 2023, 9:26am UTC](https://discourse.cmake.org/t/doc-versioning-mechanism/4814/8 "2023-04-30T09:26:06Z")
@brad.king
Execuse me. I wondered how is the “Version Switcher” added into the HTML page after using `-A versionswitch=1` in the command-line?
The following commands are what I use to build the CMake Docs locally:
```plaintext
sphinx-build --version
git clone --depth 1 --no-single-branch https://github.com/Kitware/CMake.git
cd CMake
git checkout v3.25.1 --quiet
git describe --tag
mkdir build && cd build
cmake ../Utilities/Sphinx -GNinja -DSPHINX_HTML=ON -DSPHINX_FLAGS="-A versionswitch=1"
cmake --build .
```
And the following is the code snippet of its HTML code:
Compared to the HTML downloaded from `cmake.org`, we can see that there are lots of stuff inside the `` label:
How does CMake Team modify this snippet in every HTML file when publishing and hosting on `cmake.org`?
---
### Author:  [@jtxa](https://discourse.cmake.org/u/jtxa)
#### Post date: [April 30, 2023, 4:18pm UTC](https://discourse.cmake.org/t/doc-versioning-mechanism/4814/9 "2023-04-30T16:18:27Z")
The included `version_switch.js` modifies the rendered HTML on-the-fly in the browser memory.
If you save the HTML to disk, you will see the same empty `span` element as the one you generated.
---
### Author:  [@hwhsu1231](https://discourse.cmake.org/u/hwhsu1231)
#### Post date: [May 1, 2023, 6:41am UTC](https://discourse.cmake.org/t/doc-versioning-mechanism/4814/10 "2023-05-01T06:41:53Z")
@jtxa Thansk for you replies!!
It seems that there are some match mechanism in the `version_switch.js`, checking whether the current href is hosted in the `cmake.org/cmake/help`. If I want to test this `version_switch.js` _ **locally** _, what should I do?
- The following file is downloaded from the [https://cmake.org/cmake/help/latest/](https://cmake.org/cmake/help/latest/) directly:
- The following directory is where I generate HTML files:
- The following commands are what I use to generate HTML files:
Should I modify the `version_switch.js` to make it suitable for HTML files hosted locally? If so, what should I do?
---
### Author:  [@hwhsu1231](https://discourse.cmake.org/u/hwhsu1231)
#### Post date: [January 22, 2024, 2:58pm UTC](https://discourse.cmake.org/t/doc-versioning-mechanism/4814/12 "2024-01-22T14:58:44Z")
### Problem Description
Hello, CMake Team.
Recently, I checked the contents of [https://cmake.org/cmake/help/version\_switch.js](https://cmake.org/cmake/help/version_switch.js), and accententally found that there are some changes made by CMake Team.
Because I stored a copy of `version_switch.js` at the time that the latest release is `v3.26` for research purposes, after compareing the previous one (`v3.26` is the latest) and the current one (`v3.28` is the latest), I found that:
1. For `build_select()` function, the current one replaced this line:
2. For `on_switch()` function, the current one refactored it from:
3. For `$(document).ready(function()`, it’s replaced with `document.addEventListener` totally.
Out of curiosity, could someone please explain the reason for this change?
May I ask if this is related to that:
1. the version 3.28 started to use **‘sphinx-build 6.2.1’** to build its documentation,
2. and cannot use **‘jQuery’** anymore?
### Attachments
- The previous one: [version\_switch.js](https://discourse.cmake.org/uploads/short-url/peS9gIxyusYXa9yeBfZy8jBReko.js) (2.5 KB)
- The current one: [version\_switch.js](https://discourse.cmake.org/uploads/short-url/ffpukTUd1suGzGO6sc8tWguSk0f.js) (2.8 KB)
---
### Author:  [@brad.king](https://discourse.cmake.org/u/brad.king)
#### Post date: [January 22, 2024, 3:12pm UTC](https://discourse.cmake.org/t/doc-versioning-mechanism/4814/13 "2024-01-22T15:12:35Z")
Yes, the change was because of the update to Sphinx, which no longer includes jQuery in the generated HTML documentation files. The new implementation doesn’t use jQuery and works for all the older versions of the documentation too.