Skip to content

Multi-version documentation

By default, plugin assume multi-version documentation publishing.

Configuration, responsible for versioning:

mkdocs.publish {
    docPath = '$version'  
    rootRedirect = true 
    rootRedirectTo = '$docPath'

    versionTitle = '$docPath'
    versionAliases = []
    generateVersionsFile = true
}

Tip

Usually it is more handy to manually set current doc version and not rely on project version because often documentation for currently released version is updated multiple times after release.

Important

Mkdocs-material suggests mike tool usage for publication. Gradle plugin implements absolutely the same workflow as mike, but much easier customizable (as gradle plugin). Material theme would still be able to show version switcher because plugin generates required versions.json file.

Workflow

Usually you work on documentation for current version only. When new version released - you publish new documentation version and continue evolving it. Old version stays published for the legacy users.

Older version update

When older documentation version needs to be updated switch off redirection index.html generation (so it would not override redirection to the latest version):

mkdocs.publish {
    docPath = '0.9'  
    rootRedirect = false  // site root must still redirect to '1.0' (assume it's already published)
}

Will build (without root index.html):

build/mkdocs/
    /0.9/    - mkdocs site for old version

Also, do not use versionAliases when publishing old version because it may override more recent docs version. Plugin would try to warn you in such cases:

WARNING: Publishing version '1.0' is older then the latest published '1.1' and the following overrides might not be desired: 
    root redirect override to '1.0'
    existing alias 'latest' override
    existing alias '1.x' override

Important

This warning is produced by mkdocsVersionsFile file and only when versions.json file generation is not disabled. This check can't be done under mkdocsBuild because publishing repository is required for validation.

So please, when releasing an old version use mkdocsVersionsFile to see all possible warnings before actual publication.

Publication layouts

You may define whatever layout you want, e.g.:

mkdocs.publish.docPath = 'en/1.0/'

Here generated site will be published into /en/1.0/ folder (not just version) and index.html generated at the root with correct redirection.

Warning

If you want to use version switcher then you should not use long version paths, because mkdocs-material would look for versions file only at one level up.

Aliases

It is possible to publish version not only into version folder, but also into aliased folders.

Could be useful for:

  • Publishing the latest documentation under latest alias, so users could always reference the latest docs with the same link.
  • Publishing docs for developing version under dev alias, so users could easily find dev docs.
  • Serving the latest (patch) version for some mojor version: e.g. 5.x alias could serve the latest published bugfix.

For example, to add latest alias:

mkdocs.publish {
    docPath = '1.0'  
    rootRedirect = true
    versionAliases = ['latest']
}

Will build:

build/mkdocs/
    /0.9/    
    /latest/
    index.html

Note

Alias folder contains a copy of generated documentation, which means that sitemap links would lead to path of exact version.

If same version is re-published - aliases would be correctly updated too.

It is also possible to redirect root into alias instead of exact version with rootRedirectTo option:

mkdocs.publish {
    versionAliases = ['latest']
    rootRedirectTo = 'latest'
}

Tip

In case of root redirection to alias it is better to enable version switcher to clearly show what version is active now (otherwise it would be not obvious)

Doc version switcher

Version switcher might be enabled in mkdocs.yml exactly as described in docs:

extra:
  version:
    provider: mike

Important

You don't need mike itself!

Important

You will not see switcher under mkdocsServe command, but if you call mkdocsVersionsFile (which would also call mkdocsBuild), and manually open new version it would show switcher with all versions (using generated versions.json)

Mkdocs-material requires only versions.json file stored at docs root. Plugin would automatically generate such file (following mike syntax):

  • Plugin verifies actually existing directories in gh-pages repository and would add them to generated versions file. So if you already have many versions published, just publish new version with enabled versions support and you'll see all of them in the version switcher.
  • Theme folders are detected by using \d+(\..*)? regexp (version folder must start with a number) and it must contain 404.html file.
  • Deeper versions folders are also supported: e.g. if mkdocs.publish.docPath = 'en/1.0/' then `en/1.0' folder would be recognized as version
  • Existing records in versions.json file are preserved for found version folders.
    • You can modify file manually (e.g. to modify version title) and it will not be overridden on next publication
    • You can manually remove version folder in repository and on next publication versions.json would be corrected
  • If aliases used, they would be correctly updated (e.g. latest removed from previous latest version.)

If you do not want to generate versions file:

mkdocs.publish.generateVersionsFile = false

To customize version title (shown in dropdown selection) use:

mkdocs.publish.versionTitle = '1.0 (important fix)'

Incremental versions

There is an alternative way for versions.json file generation for cases when publishing task is not used (e.g. when lightweight ru.vyarus.mkdocs-build plugin used).

The idea is to use existing versions file and add new version into it (in contrast, git based publication could detect removed version folders and remove versions from file accordingly).

Tip

Version aliases would be also correctly processed.

To enable incremental versions generation, specify current versions file location:

mkdocs.publish.existingVersionsFile = 'path/to/actual/versions.json'

You can also use a URL (http, ftp or anything that URL could handle):

mkdocs.publish.existingVersionsFile = 'https://xvik.github.io/gradle-mkdocs-plugin/versions.json'

When file specified, mkdocsBuild would load current file and apply new version there (if required). Updated versions file would be available in target build directory (same as with git publication).

Important

There will not be an error if file not found or due to download error - instead plugin would consider current file as not existing and would create a fresh versions file.

This is useful for the first publication.

Note

When git publication used, incremental versions file, generated by mkdocsBuild would be overridden by versions file, generated by publishing task. If required, it could be disabled with mkdocs.publish.generateVersionsFile = false, but keep in mind that publication mechanism is safer to use.