Docs versioning: Docusaurus and MkDocs

In this article, I explain how to add versioning to your docs generated with Docusaurus or MkDocs Material.

The goal is to add versions selector to the docs site generated with Docusaurus or MkDocs Material.


Sometimes, you’re asked to add versions to your documentation based on the product versions. For example, when developers launch a new major release of their product, their change the product version from 1.5 to 2.0. In this case, they want their new product version to have the respective new docs describing new features. At the same time, they still want the customers who use the older version of their product to read the old docs without new features.

In my previous article, I showed how to create a documentation site using Docusaurus or MkDocs Material. In this article, I’ll show how to add a version selector to select a specific version of your docs.

Docs versioning in MkDocs Material

I was able to build a test site with docs versioning. It’s not that straightforward though. Anyway, I’ll try to reproduce the steps and build another one with step by step instructions.


You need to have Python with pip for MkDocs. Then you can install MkDocs and the MkDocs Material packages using pip.

  1. Ensure Python is installed: You can check if Python is installed on your system by opening a command prompt and typing python --version. If Python is installed, you will see something like Python 3.11.3. If you don’t have Python installed, install it from their official website.

  2. Ensure pip is installed: You can check if pip is installed by typing pip --version in the command prompt. If pip is installed, it will display the version.

  3. Install MkDocs: Type pip install mkdocs in the command prompt. Make sure MkDocs is installed by typing mkdocs --version.

  4. Install MkDocs Material: Type pip install mkdocs-material in the command prompt. To check if MkDocs Material is installed, type mkdocs serve --help. This command should list material as an option under the --theme. If material is listed, it means that Material for MkDocs is installed correctly.

    Material theme

For more information, see MkDocs Installation and MkDocs Material Installation.

Install the MkDocs site

You can continue creating a brand new MkDocs Material site using these instructions. Or, you can fork my repo with the ready configuration:

  1. Fork or download the zipped project from here:

  2. Open the mkdocs.yml file to edit the configuration of your site.

    site_name: Docs site
        - Introduction: ''
        - User Guide:
            - 'Test': 'test-folder/'
            - 'Test 1': 'test-folder/'
            - 'Test 2': 'test-folder/'
        - About:
            - 'About this site': ''
        - navigation.footer
    name: material
    custom_dir: overrides
    logo: img/logo.svg
    favicon: img/favicon.ico
        scheme: default
        accent: light blue
    - stylesheets/extra.css
    - search
    - mike
        provider: mike
        - icon: fontawesome/brands/github
        - icon: fontawesome/brands/linkedin
    generator: false
    - pymdownx.superfences:
            - name: mermaid
            class: mermaid
            format: !!python/name:pymdownx.superfences.fence_code_format
    - admonition
    - pymdownx.details
    - pymdownx.tabbed:
        alternate_style: true
    copyright: Copyright © 2023 Ivan Cheban
  3. Open the project folder in the VS Code terminal or in the command prompt and install the missing plugins:

    pip install mike
  4. To run the site on your local host, type: mkdocs serve. This starts the site in your browser with this address:

    MkDocs local site

Docs versioning on local host

To deploy a new version of your docs on a local host:

  1. Run: mike deploy --push --update-aliases 0.1 latest where 0.1 is the version you make the latest. Then run mike deploy --push --update-aliases 0.2 latest to make 0.2 the latest version.

  2. Run mike serve to open your site in the local host with this address: http://localhost:8000/0.2/. When you go to the older version from the version selector, you’ll see this message:

Latest version message

Deploy MkDocs Material to GitHub Pages

Now that you’ve checked that your MkDocs Material site works locally, it’s time to deploy it on GitHub as a public site.

  1. Create a gh-pages branch in your repository.

  2. In the web interface of your repository, Go to Settings > Pages and selected gh-pages as a branch to deploy your site from. Save the changes.

  3. At the root of your MkDocs project, create a new GitHub Actions workflow file: .github/workflows/ci.yml, and copy and paste the following contents:

    name: ci 
        - master 
        - main
    contents: write
        runs-on: ubuntu-latest
        - uses: actions/checkout@v4
        - name: Configure Git Credentials
            run: |
            git config github-actions[bot]
            git config 41898282+github-actions[bot]        
        - uses: actions/setup-python@v5
            python-version: 3.x
        - run: echo "cache_id=$(date --utc '+%V')" >> $GITHUB_ENV 
        - uses: actions/cache@v4
            key: mkdocs-material-${{ env.cache_id }}
            path: .cache
            restore-keys: |
        - run: pip install mkdocs-material
        - run: pip install mike
        - run: mkdocs gh-deploy --force
  4. Commit and push your changes.

Last modified April 27, 2024: added a docs versining article (2eafa0d)