mike 0.1.1

Manage multiple versions of your MkDocs-powered documentation

mike is a Python utility to easily deploy multiple versions of your MkDocs-powered docs to a Git branch, suitable for deploying to Github via gh-pages.

Installation

Like most Python projects, mike uses setuptools, so you can install it like most any other Python package:

pip install mike

Usage

Building Your Docs

Before your first build, you’ll probably want to add the version selector to your MkDocs config. Simply run the following command in the directory with your mkdocs.yml file to install the extra CSS and JS files to your docs:

mike install-extras

mike is designed to produce one version of your docs at a time. That way, you can easily deploy a new version without touching any older versions of your docs; this can be especially important if your old docs are no longer buildable with the newest version of MkDocs (or if they weren’t built with MkDocs at all!). To deploy the current version of your docs, simply run:

mike deploy [version]

Where [version] is the current version of your project, represented however you like (I recommend using [major].[minor] and excluding the patch number). You can also pass aliases to the deploy command to host a particularly-relevant version of your docs somewhere special (e.g. latest):

mike deploy [version] [alias]...

If you’d like to specify a title for this version that doesn’t match the version string, you can pass -t TITLE/--title=TITLE as well.

Finally, to push your docs to a remote branch, simply add -p/--push to your command. (Note: this will likely become the default eventually.)

Deleting Docs

Sometimes you need to delete an old version of your docs, either because you made a mistake or you’re pruning unsupported versions. You can do this via the delete subcommand:

mike delete [version-or-alias]...

If you’d like to completely wipe the contents of your docs branch, just run mike delete --all. Like deploy above, you can specify -p/--push to push this commit as well.

Listing Docs

If you ever need to see the list of all currently-deployed doc versions, you can run:

mike list

Setting the Default Version

With all the versions of docs you have, you may want to set a default version so that people going to the root of your site are redirected to the latest version of the docs:

mike set-default [version-or-alias]

Like deploy and delete above, you can specify -p/--push to` push this commit as well.

Renaming a Version

As you update your docs, you may want to rename the title of a particular version. For example, your 1.0 docs might have the title 1.0.0, and when you release a new patch, you want to update the title to 1.0.1. You can do this with the rename command:

mike rename [version-or-alias] [title]

More Details

For more details on the available options (e.g. specifying which branch to push to), consult the --help command for mike.

For Theme Authors

If you’d like to provide support for mike in your theme, you just need to fetch versions.json and build a version selector. versions.json looks like this:

[
  {"version": "1.0", "title": "1.0.1", "aliases": ["latest"]},
  {"version": "0.9", "title": "0.9", "aliases": []}
]

To see an example of how to work with this, check the `mike/themes/mkdocs <mike/themes/mkdocs>`__ directory.

License

This project is licensed under the BSD 3-clause license.