mkdocs-multiversion-plugin

mkdocs-multiversion-plugin is a plugin for mkdocs - a fast, simple and downright gorgeous gorgeous static site generator that's geared towards building project documentation.

mkdocs-multiversion-plugin allows you to build and have different versions of your project documentation.

How It Works

mkdocs-multiversion-plugin works by creating a new version of documentation inside mkdocs site_dir/<version> directory and adds configuration file containing information about versions to site_dir/multiversion.json. The plugin doesn't create new branches in your git repository.

Setup

Install the plugin using pip:

pip install mkdocs-multiversion-plugin

Next, add the following lines to your mkdocs.yml:

plugins:
  - multiversion

If you have no plugins entry in your config file yet, you'll likely also want to add the search plugin. MkDocs enables it by default if there is no plugins entry set.

Configuration

Guide to all available configuration settings.

To change some behavior of the plugin you need to set proper config option in mkdocs.yml under plugin section.

plugins:
  - multiversion:
    branch_whitelist: None
    version_in_site_name: False

List of available config options:

Name	Type	Default value	Description
version_in_site_name	string	True	Adds the version name to the mkdocs site_name config.
branch_whitelist	string	^.*$	Whitelist branch names, regex.
tag_whitelist	string	^.*$	Whitelist tag names, regex.
latest_version_name_format	string	latest release ({version})	Latest version name format, argument: {version}.
version_name_format	string	{version}	Version name format, argument: {version.
css_dir	string	css	The name of the directory for css files.
javascript_dir	string	js	The name of the directory for javascript files.
versions_url	string	''	The URL for the versions file.
versions_file_name	string	multiversion.json, index.php	The name for the file on the server containing generated versions.
generate_versions_file	bool	true	Specifies whether to generate a file with versions.
versions_provider	string	static	Available version providers: php, static.

If the generate_versions_file configuration option is false, you need to deliver the file with the available versions yourself.

The file should contain JSON in the format:

{
    "stable" : {
        "name" : "stable",
        "latest" : false
    },
    "0.2.0" : {
        "latest" : true,
        "name" : "latest release (0.2.0)"
    },
    "0.1.0" : {
        "latest" : false,
        "name" : "0.1.0"
    }
}

Versions provider

There are two documentation versions providers:

• static - static json file generated during building documentation containing versions from git repository.
• php - the dynamic engine that generates a list of available versions on the server. A server with PHP support is required for its operation. Generated versions are a list of directories on the server.

Static provider configuration:

plugins:
  - multiversion

PHP provider configuration:

plugins:
  - multiversion:
    versions_provider: php

It is possible to override name of the static file: versions_file_name. Be careful to enter the correct path to the file. In case it is a relative path, the name will be prefixed with the path to the base directory: base_url.

Contributing

Please note that mkdocs-multiversion-plugin is currently in Beta and there may be missing feature/documentation so if you could help out by either:

1. finding and reporting bugs
2. contributing by checking out the issues

License

BSD-3-Clause