MkDocs Merge

这个简单的工具允许您将多个MkDocs站点的源代码合并成一个，将每个指定的站点转换为主站点的子站点。

支持将具有相同 site_name 的站点统一到一个子站点。

变更日志

在此处访问变更日志：https://ovasquez.github.io/mkdocs-merge/changelog/

注意：从版本0.6开始，MkDocs Merge增加了对MkDocs 1.0的支持，并放弃了之前版本的支持。有关MkDocs 1.0变更的更多详情，请参阅MkDocs 1.0。

MkDocs-Merge官方支持Python版本3.8、3.9和3.10。它已在之前的3.X版本中测试过，但不再官方支持。

安装

$ pip install mkdocs-merge

用法

$ mkdocs-merge run MASTER_SITE SITES [-u]...

参数

• MASTER_SITE：MkDocs站点的路径，其中包含基本 mkdocs.yml 文件。其他所有站点都将合并到此。
• SITES：要合并的每个MkDocs站点的路径。每个这些路径应包含一个 mkdocs.yml 文件和一个 docs 文件夹。
• -u（可选）：将具有相同 "site_name" 的站点统一到一个子站点。

示例

$ mkdocs-merge run root/mypath/mysite /another/path/new-site /newpath/website

将在 root/mypath/mysite 下创建一个单独的 MkDocs 网站，并将 /another/path/new-site 和 /newpath/website 下的网站添加为子页面。

原始 root/mypath/mysite/mkdocs.yml

...
nav:
  - Home: index.md
  - About: about.md

合并后的 root/mypath/mysite/mkdocs.yml

...
nav:
  - Home: index.md
  - About: about.md
  - new-site: new-site/home/another.md # Page merged from /another/path/new-site
  - website: website/index.md # Page merged from /newpath/website

开发

开发安装

克隆仓库并在安装命令中指定 dev 依赖。项目已更新为使用 pyproject.toml，因此版本需要在 __init__.py 和 pyproject.toml 中手动同步。

# Using quotes for zsh compatibility
$ pip install -e '.[dev]'

测试

可以从根目录使用 tox 运行测试。tox 是开发依赖的一部分。

$ tox

发布

发布流程已更新为使用 GitHub Actions。

项目状态

非常基础的实现。代码可以工作，但不允许指定合并的选项。

待办工作

• 重构大型函数。
• GitHub Actions 构建。
• 发布 pip 包。
• 更好的错误处理。
• 通过 CLI 选项合并配置。
• 单元测试（进行中）。
• CLI 集成测试。
• 考虑更复杂的情况。
• 使 MkDocs 合并模块友好：感谢 mihaipopescu