Mike 项目使用教程

1. 项目介绍

Mike 是一个 Python 实用工具，旨在通过 Git 轻松管理 MkDocs 驱动的文档的多个版本。它特别适用于通过 GitHub Pages 托管文档。Mike 的核心理念是，一旦为特定版本生成了文档，就不应再触及该版本。这意味着您无需担心 MkDocs 中的破坏性更改，因为旧文档（使用旧版本的 MkDocs 构建）已经生成并存储在 gh-pages 分支中。

Mike 的灵活性使其能够将文档放置在 <major>.<minor> 目录中，并提供可选的别名（例如 latest 或 dev），以便轻松创建指向特定版本文档的永久链接。

2. 项目快速启动

安装 Mike

Mike 使用 setuptools，因此安装过程与大多数 Python 项目类似：

pip install mike

配置 MkDocs

在 mkdocs.yml 文件中添加 Mike 插件：

plugins:
  - mike:
      alias_type: symlink
      redirect_template: null
      deploy_prefix: ''
      canonical_version: null
      version_selector: true
      css_dir: css
      javascript_dir: js

部署文档

使用以下命令部署当前版本的文档：

mike deploy [version] [alias]

例如，部署版本 1.0 并设置别名为 latest：

mike deploy 1.0 latest

推送文档

将文档推送到远程分支：

mike deploy 1.0 latest -p

3. 应用案例和最佳实践

应用案例

Mike 特别适用于需要维护多个版本文档的项目，例如软件库、API 文档或开源项目的文档。通过使用 Mike，您可以轻松管理不同版本的文档，确保每个版本的文档独立且不会因 MkDocs 的更新而受到影响。

最佳实践

1. 版本命名规范：建议使用 <major>.<minor> 格式命名版本，避免使用补丁号，以便更清晰地管理版本。
2. 别名管理：为特别重要的版本设置别名（如 latest 或 dev），以便用户可以轻松访问最新或开发中的文档。
3. 定期清理：定期使用 mike delete --all 清理旧版本的文档，避免 gh-pages 分支过于臃肿。

4. 典型生态项目

MkDocs

MkDocs 是一个快速、简单且美观的静态站点生成器，适用于构建项目文档。Mike 与 MkDocs 紧密集成，使得管理多个版本的文档变得非常方便。

GitHub Pages

GitHub Pages 是一个静态站点托管服务，直接从 GitHub 仓库托管您的网站。Mike 通过 Git 管理文档版本，特别适合与 GitHub Pages 结合使用。

shtab

shtab 是一个用于生成 shell 补全脚本的工具。安装 shtab 后，可以使用 mike generate-completion 为 Mike 生成 shell 补全脚本，提高命令行操作效率。

通过以上模块的介绍和实践，您可以快速上手并充分利用 Mike 项目，有效管理 MkDocs 驱动的文档版本。