Package: mike
mikemikeis a Python utility that makes it easy to deploy multiple versions of
yourMkDocs-powered docs to a Git branch, suitable for
hosting on Github viagh-pages. To see an example of this in action, take a
look at the documentation forbfg9000.Why Use mike?mike is built around the idea that once you've generated your docs for a
particular version, you should never need to touch that version again. This
means you never have to worry about breaking changes in MkDocs, since your old
docs (built with an old version of MkDocs) are already generated and sitting in
yourgh-pagesbranch.While mike is flexible, it's optimized around putting your docs in a<major>.<minor>directory, with optional aliases (e.g.latestordev) to
particularly notable versions. This makes it easy to make permalinks to whatever
version of the documentation you want to direct people to.How It Worksmike works by creating a new Git commit on yourgh-pagesbranch every time you
deploy a new version of your docs usingmike deploy(or other mike subcommands
that change yourgh-pagesbranch). When deploying a particular version,
previously-deployed docs for that version are erased and overwritten, but docs
for other versions remain untouched.InstallationLike most Python projects, mike usessetuptools, so installation
is what you might expect:pipinstallmikeOnce you've installed mike, you might also want to set up shell-completion for
it. If you haveshtabinstalled, you can do this withmike generate-completion, which will print the shell-completion code for your
shell. For more details on how to set this up, consult shtab'sdocumentation.UsageBefore Using mikeBefore using mike for the first time, you may want to usemike delete --allto delete any old documentation on yourgh-pagesbranch before building your new versioned docs. (If you prefer, you can also
manually move your old documentation to a subdirectory of yourgh-pagesbranch
so that it's still accessible.)ConfigurationTo help integrate into the MkDocs build process, mike uses an MkDocs plugin.
This plugin is added by default when building your documentation with mike, but
by adding it explicitly to yourmkdocs.ymlfile, you can configure how the
plugin works. The plugin adds a version selector to supported themes as well as
updating thesite_url(if you set it) to point to the version of the docs that
are being built:plugins:-mike:# These fields are all optional; the defaults are as below...alias_type:symlinkredirect_template:nulldeploy_prefix:''canonical_version:nullversion_selector:truecss_dir:cssjavascript_dir:jsalias_type: The method to create aliases; one of:symlink: Create a symbolic link from the alias to the base directory of
the documentationredirect: Create an HTML redirect for each page of the documentationcopy: Copy all the files of the documentation to the alias's pathredirect_template: The template file to use when creating HTML redirects; ifnull, use the default templatedeploy_prefix: The root directory to put the generated docs in; this can be
useful if you'd like to have other pages at the root of your site, or to host
multiple, independently-versioned sets of docs side by sidecanonical_version: The "canonical" version to use for the documentation,
useful for telling search engines what pages to prefer (e.g.latestif
you've defined that as an alias that always points to the latest release); ifnull, mike will use the version specified viamike deployversion_selector: True if the version selector should be shown on pages;
false otherwisecss_dir: The directory to place the version selector's CSSjavascript_dir: The directory to place the version selector's JavascriptBuilding Your Docsmike 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:mikedeploy[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 thedeploycommand to host a
particularly-relevant version of your docs somewhere special (e.g.latest):mikedeploy[version][alias]...If[version]already exists, this command willalsoupdate all of the
pre-existing aliases for it. Normally, if an alias specified on the command line
is already associated with another version, this will return an error. If youdowant to move an alias from another version to this version (including
when the new version itself was previously an alias), you can pass-u/--update-aliasesto allow this. For example, this can be useful when
releasing a new version and updating thelatestalias to point to this new
version.By default, each alias creates a symbolic link to the base directory of the real
version of the docs; to create a copy of the docs for each alias, you can pass--alias-type=copy, or to use a simple HTML redirect for each page, you can
pass--alias-type=redirect. If you're using redirects, you can customize the
redirect template with-T/--template; this takes a path to aJinjatemplate that accepts an{{href}}variable.If you'd like to specify a title for this version that doesn't match the version
string, you can pass-t TITLE/--title=TITLEas well. You can set custom
properties for this version as well, using--prop-set,--prop-set-string,--prop-set-all,--prop-delete, and--prop-delete-all(see theManaging
Propertiessection for more details).In addition, you can specify where to deploy your docs via-b/--branch,-r/--remote, and--deploy-prefix, specifying the branch, remote, and
directory prefix within the branch, respectively. Finally, to push your docs to
a remote branch, simply add-p/--pushto your command.You can also specify many of these options via yourmkdocs.ymlconfiguration
as shown above. For example,--alias-typecan also be specified viaplugins.mike.alias_type. (For--branchand--remote, you can use the
built-in MkDocs fieldsremote_branchandremote_name.)Viewing Your DocsTo test that your docs have been built as expected, you can serve them locally
from a dev server:mikeserveBy default, this serves the docs onhttp://localhost:8000, but you can
change this with-a/--dev-addr. Remember though,this is for testing only.
To host your docs for real, you should use a real web server.Deleting DocsSometimes 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 thedeletesubcommand:mikedelete[identifier]...Ifidentifieris a version, this will delete the version and all its aliases
from the branch; if it's an alias, it will only delete that alias.If you'd like tocompletelywipe the contents of your docs branch, just runmike delete --all. Likedeployabove, you can specify--branch,--push,
etc to control how the commit is handled.Listing DocsIf you ever need to see the list of all currently-deployed doc versions, you can
run:mikelistTo list the info for a particular version, you can just pass the version name or
an alias to that version:mikelist[identifier]Sometimes, you need this information to be consumed by another tool. In that
case, pass-j/--jsonto return the list of doc versions as JSON.Setting the Default VersionWith all the versions of docs you have, you may want to set adefaultversion
so that people going to the root of your site are redirected to the latest
version of the docs:mikeset-default[identifier]If you want to use a different template from the default, you can pass-T/--template; this takes a path to aJinjatemplate that accepts
an{{href}}variable. (Note that this pagealwaysuses a redirect, no matter
the setting ofalias_type/--alias-type.)Likedeployanddeleteabove, you can specify--branch,--push,
etc to control how the commit is handled.Changing a Version's TitleAs you update your docs, you may want to change the title of a particular
version. For example, your1.0docs might have the title1.0.0, and when you
release a new patch, you want to update the title to1.0.1. You can do this
with theretitlecommand:mikeretitle[identifier][title]As with other commands that change your docs, you can specify--branch,--push, etc to control how the commit is handled.Adding a New Version AliasSometimes, you might need to add a new alias for a version without rebuilding
your documentation. You can use thealiascommand for this:mikealias[identifier][alias]...As withdeploy, you can pass-u/--update-aliasesto change where an
existing alias points to.Once again, you can specify--branch,--push, etc to control how the commit
is handled.Managing PropertiesEach version of your documentation can have any arbitrary properties assigned to
it that you like. You can use these properties to hold extra metadata, and then
your documentation theme can consult those properties to do whatever you like.
When using the built-in MkDocs themes, mike supports one property:hidden.
When this istrue, that version will be hidden from the version selector
(unless it's the current version).You can get properties viapropscommand:mikeprops[identifier][prop]Ifpropis specified, this will return the value of that property; otherwise,
it will return all of that version's properties as a JSON object.You can also set properties by specifying one or more of--set prop=json,--set-string prop=str,--set-all json,--delete prop, and--delete-all.
(If you prefer, you can also set properties at the same time as deploying via
the--prop-*options.)When getting or setting a particular property, you can specify it with a
limited JSONPath-like syntax. You can use bare field names, quoted field
names, and indices/field names inside square brackets. The only operator
supported is.. For example, this is a valid expression:foo."bar"[0]["baz"]When setting values, you can add to the head or tail of a list via theheadortailkeywords, e.g.:foo[head]As usual, you can specify--branch,--push, etc to control how the commit is
handled.More DetailsFor more details on the available options, consult the--helpcommand for
mike.Version OrderingThere are lots of versioning schemes out there, but mike tries its best to order
your versions in a reasonable manner. Version identifiers that "look like"
versions (e.g.1.2.3,1.0b1,v1.0) are treated as ordinary versions,
whereas other identifiers, likedevel, are treated as development versions,
and placedaboveordinary versions.The above scheme should get things right most of the time, but you can always
post-process yourversions.jsonfile to manipulate the ordering to suit your
needs.Staying in Syncmike will do its best to stay in-sync with your remote repository and will
automatically update your local branch to match the remote's if possible (note
that mikewon'tautomaticallygit fetchanything). If your local branch has
diverged from your remote, mike will leave it as-is and ask you what to do. To
ignore the remote's state, just pass--ignore; to update to the remote's
state, pass--rebase.CNAME(and Other Special Files)Some special files that you'd like to deploy along with your documentation (such
asCNAME) aren't related to a particular version of the docs, and instead need
to go in the root directory of your site. There's no special handling for this
in mike, but since your built docs live on a Git branch, it's still easy to
manage: check out yourgh-pagesbranch (or wherever your built docs
live), and commit the necessary files to the root directory.Deploying via CISince mike just generates commits to an ordinary Git branch, it should work
smoothly with your favorite CI system. However, you should keep in mind that
some CI systems make shallow clones of your repository, meaning that the CI job
won't have a local instance of your documentation branch to commit to. This will
naturally cause issues when trying to push the commit. This is easy to resolve
though; just manually fetch yourgh-pagesbranch (or whichever you deploy to)
before running mike:gitfetchorigingh-pages--depth=1You may also need toconfigure a Git userso that mike can
make commits:gitconfiguser.nameci-bot
gitconfiguser.emailci-bot@example.comAlternately, you can set the environment variablesGIT_COMMITTER_NAMEandGIT_COMMITTER_EMAIL(as well asGIT_COMMITTER_DATEif you like):GIT_COMMITTER_NAME=ci-botGIT_COMMITTER_EMAIL=ci-bot@example.com\mikedeploy1.0For Theme AuthorsIf you'd like to provide support for mike in your theme, you just need to
fetchversions.jsonand build a version selector.versions.jsonlooks like
this:[{"version":"1.0","title":"1.0.1","aliases":["latest"]},{"version":"0.9","title":"0.9","aliases":[],"properties":"anything"}]Every version has aversionstring, atitle(which may be the same asversion), a list ofaliases, and optionally, apropertiesattribute that
can hold anything at all. Thesepropertiescan be used by other packages,
themes, etc in order to add their own custom metadata to each version.If you're creating a third-party extension to an existing theme, you add a
setuptools entry point formike.themespointing to a Python submodule that
containscss/andjs/subdirectories containing the extra code to be
installed into the user's documentation. This will then automatically be
included via themikeplugin in the user'smkdocs.ymlfile.To see some examples of how to work with this, check themike/themes/mkdocsdirectory.LicenseThis project is licensed under theBSD 3-clause license.