mike

mike is a Python command-line utility that makes it easy to publish and maintain multiple versions of MkDocs-powered documentation on a Git branch, ready for hosting on GitHub Pages via gh-pages. Each mike deploy creates a commit that adds or updates one version’s docs while leaving other versions untouched.

Built around the idea that once a version is generated you should never have to rebuild it, mike organizes docs into per-version directories with optional aliases like latest or dev, so you can maintain stable permalinks and safely evolve your documentation across releases.

What You Get

• Subcommands like mike deploy, mike alias, mike set-default, and mike delete for managing versions
• Per-version documentation directories with stable permalinks
• Optional aliases such as latest or dev pointing at notable versions
• Immutable historical builds so old docs never need rebuilding
• Shell-completion generation and GitHub Pages-friendly output

Common Use Cases

• Publishing versioned documentation for a library on GitHub Pages
• Keeping docs for old releases available alongside the latest version
• Maintaining a ‘latest’ alias that always points at the current release
• Rolling documentation deploys into a CI/CD release pipeline

Under The Hood

Architecture - mike is a subcommand-driven CLI whose logic lives in the mike/ package. A console_scripts entry point dispatches to commands (deploy, alias, set-default, delete, list, serve) that manipulate a dedicated docs branch through Git; when deploying, it builds or copies MkDocs output into a <major>.<minor> directory, updates a versions manifest, and creates a commit while preserving other versions’ trees. Tech Stack - Pure Python packaged with setuptools (setup.py/setup.cfg), integrating with MkDocs, Git (via subprocess/plumbing), and optional shtab for shell completion. It targets standard CPython and installs a single mike executable. Code Quality - The repository includes a test/ suite with codecov coverage tracking and a documented CHANGES log; it is a mature, established project, though recent development activity is low. Command modules are cleanly separated and the Git-manipulation logic is centralized. API Design - As a tool the surface is its CLI, which is ergonomic and discoverable: verbs map to intuitive subcommands, helptext is thorough, and shell completion plus sensible defaults (the <major>.<minor> layout and alias conventions) keep the common deploy workflow to a single command.