开始与Insiders合作¶

MkDocs Insiders的材料是材料的兼容直接替代品 对于MkDocs，可以使用pip进行类似的安装， 〔docker〕〔docker〕或〔git〕〔git〕。请注意，为了访问内部人员 在GitHub上，你需要[成为@squidfunk的合格赞助商]。

必要条件¶

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

1. Go to https://github.com/settings/tokens
2. Click on Generate a new token
3. Enter a name and select the repo scope
4. Generate the token and store it in a safe place

以下一些说明要求“GH_TOKEN”环境 变量设置为您的个人访问令牌的值 在前面的步骤中生成的。请注意，个人访问令牌 必须始终保密，因为它允许所有者访问 您的私人存储库。

安装¶

使用pip¶

MkDocs Insider的材料可以用pip安装。你会 通常希望安装最新版本，但也可以安装 特定的旧版本，甚至最新的开发版本。 确保按照上述指示设置了“GH_TOKEN”变量。

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

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

使用docker¶

如果你想在Docker中为MkDocs Insider使用Material 需要额外的步骤。虽然我们无法提供托管的Docker镜像 对于内部人员¹，[GitHub容器注册表]允许简单和 舒适的自托管：

1. Fork the Insiders repository
2. Enable GitHub Actions on your fork²
3. Create a new personal access token³
   1. Go to https://github.com/settings/tokens
   2. Click on Generate a new token
   3. Enter a name and select the write:packages scope
   4. Generate the token and store it in a safe place
4. Add a GitHub Actions secret on your fork
   1. Set the name to GHCR_TOKEN
   2. Set the value to the personal access token created in the previous step
5. Create a new release to build and publish the Docker image
6. Install Pull App on your fork to stay in-sync with upstream

当有新标记时，build工作流会自动运行 （release）已创建。当新的Insiders版本在上游发布时 在仓库中，Pull App将创建一个包含更改的Pull请求 拉入新标签，该标签由`build工作流获取 自动构建Docker镜像并将其发布到您的私有 注册表。

现在，您应该能够从私有注册表中提取Docker映像：

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

如果您希望在内部人员容器映像中添加其他插件，请按照以下步骤操作 在[入门指南]中概述（../geting-Started.md#with docker）。

使用git¶

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

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

主题将位于“mkdocs material/material”文件夹中。克隆时 从git开始，必须安装主题，这样MkDocs才能找到内置的 插件：

pip install -e mkdocs-material

内置插件¶

当你使用仅通过Insiders提供的内置插件时， 外部贡献者将无法在他们的基础上构建您的文档项目 本地机器。这就是我们开发[内置组插件]的原因 允许有条件地加载插件：

plugins:
  - search
  - social

  # CI=true mkdocs build
  - group:
      enabled: !ENV CI
      plugins:
        - git-revision-date-localized
        - git-committers

  # INSIDERS=true mkdocs build
  - group:
      enabled: !ENV INSIDERS
      plugins:
        - optimize
        - privacy

当然，您也可以通过以下方式启用这两个组：

CI=true INSIDERS=true mkdocs build