Skip to content

开始使用 Insiders

MkDocs Insiders 的材料是 MkDocs 材料的兼容替代品，可以使用pip、docker或git进行类似的安装。请注意，为了访问 Insiders 存储库，您需要成为 GitHub 上的@squidfunk 的[合格赞助商]。

要求

在您被添加到协作者列表并接受存储库邀请之后，下一步是为您的 GitHub 帐户创建一个个人访问令牌，以便以编程方式访问 Insiders 存储库（从命令行或 GitHub Actions 工作流）：

  1. 访问https://github.com/settings/tokens
  2. 点击生成新令牌
  3. 输入名称并选择repo范围
  4. 生成令牌并将其存储在安全的位置

安装

使用 pip

可以使用pip安装 MkDocs Insiders 的材料：

pip install git+https://${GH_TOKEN}@github.com/squidfunk/mkdocs-material-insiders.git

GH_TOKEN环境变量必须设置为您在上一步生成的个人访问令牌的值。请注意，个人访问令牌必须始终保密，因为它允许所有者访问您的私有存储库。

使用 docker

如果您想在 Docker 中使用 MkDocs Insiders 的材料，需要进行一些额外的步骤。虽然我们无法为 Insiders 提供托管的 Docker 镜像1，但[GitHub 容器注册表]允许简单且方便的自托管：

  1. [Fork Insiders 存储库]
  2. 在您的分支上启用GitHub Actions2
  3. 创建一个新的个人访问令牌3
    1. 访问https://github.com/settings/tokens
    2. 点击生成新令牌
    3. 输入名称并选择write:packages范围
    4. 生成令牌并将其存储在安全的位置
  4. 在您的分支上添加一个[GitHub Actions 秘密]
    1. 将名称设置为GHCR_TOKEN
    2. 将值设置为在前一步中创建的个人访问令牌
  5. 创建新版本以构建和发布 Docker 镜像
  6. 在您的分支上安装Pull App以与上游保持同步

当创建新标签（发布）时，publish工作流程4会自动运行。当上游存储库发布新的 Insiders 版本时，Pull App将创建一个包含更改的拉取请求，并拉取新标签，然后由publish工作流程自动构建并将 Docker 镜像自动发布到您的私有注册表。

现在，您应该能够从您的私有注册表中拉取 Docker 镜像：

docker login -u ${GH_USERNAME} -p ${GHCR_TOKEN} ghcr.io
docker pull ghcr.io/${GH_USERNAME}/mkdocs-material-insiders

如果您希望向 Insiders 容器映像添加其他插件，请按照入门指南中的步骤进行操作。

使用 git

当然，您可以直接从git使用 MkDocs Insiders 的材料：

git clone git@github.com:squidfunk/mkdocs-material-insiders.git mkdocs-material

主题将位于文件夹mkdocs-material/material中。从git克隆时，必须安装主题，以便 MkDocs 可以找到内置插件：

pip install -e mkdocs-material

升级

在升级 Insiders 时，您应始终检查 MkDocs 材料的版本，该版本构成版本限定符的第一部分，例如 Insiders 4.x.x当前基于8.x.x：

8.x.x-insiders-4.x.x

如果主版本号增加，建议查阅升级指南并按照步骤确保您的配置是最新的并且已进行了所有必要的更改。如果您使用pip安装了 Insiders，可以使用以下命令升级安装：

pip install --upgrade git+https://${GH_TOKEN}@github.com/squidfunk/mkdocs-material-insiders.git

注意事项

本节描述了在将 Insiders 与 MkDocs 材料一起使用时需要考虑的一些方面，以确保没有访问 Insiders 的用户仍然可以构建您的文档。

内置插件

当使用仅通过 Insiders 提供的内置插件时，可能需要将mkdocs.yml配置拆分为基本配置和具有插件覆盖的配置。请注意，这是 MkDocs 的一个限制，可以通过使用配置继承来缓解：

INHERIT: mkdocs.yml
plugins:
  - search
  - social
  - tags

# 除了Insiders插件之外的所有配置

现在，当您处于具有访问 Insiders 的环境中（例如在 CI 流水线中），您可以使用以下命令构建文档项目：

mkdocs build --config-file mkdocs.insiders.yml

共享插件和扩展配置

如果您想在mkdocs.insiders.yml和mkdocs.yml之间共享plugins或markdown_extensions，可以在两个文件中使用替代的键值语法。上述示例将如下所示：

INHERIT: mkdocs.yml
plugins:
  social: {}

# 以上是其他配置
plugins:
  search: {}
  tags: {}

  1. 早期，Insiders 提供了一个专用的 Docker 镜像，适用于所有赞助商。2021 年 3 月 21 日，出于#2442 中概述和讨论的原因，该镜像已被弃用。于 2021 年 6 月 1 日删除。 ↩

  2. 当分叉存储库时，GitHub 会禁用所有工作流程。虽然这是一个合理的默认设置，但您需要启用 GitHub Actions 才能自动构建和发布 Docker 镜像在[GitHub 容器注册表]上。 ↩

  3. 虽然您可以将write:packages范围添加到用于访问 Insiders 存储库的个人访问令牌中，但更安全的做法是创建一个专用令牌，仅用于发布 Docker 镜像。 ↩

  4. Insiders 存储库包含两个 GitHub Actions 工作流程：

    • build.yml – 构建和检查项目（在分支上禁用）
    • publish.yml – 构建和发布 Docker 镜像

    ↩