内部人员入门¶

¥Getting started with Insiders¶

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

¥Material for MkDocs Insiders is a compatible drop-in replacement for Material for MkDocs, and can be installed similarly using pip, docker or git. Note that in order to access the Insiders repository, you need to become an eligible sponsor of @squidfunk on GitHub.

要求¶

¥Requirements¶

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

¥After you've been added to the list of collaborators and accepted the repository invitation, the next step is to create a personal access token for your GitHub account in order to access the Insiders repository programmatically (from the command line or GitHub Actions workflows):

前往https://github.com/settings/tokens
¥Go to https://github.com/settings/tokens
点击生成新令牌
¥Click on Generate a new token
输入名称并选择repo范围
¥Enter a name and select the repo scope
生成令牌并将其存储在安全的地方
¥Generate the token and store it in a safe place

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

¥Some of the instructions below require that the GH_TOKEN environment variable is set to the value of the personal access token you generated in the previous step. Note that the personal access token must be kept secret at all times, as it allows the owner to access your private repositories.

安装¶

¥Installation¶

使用 pip¶

¥with pip¶

MkDocs Insiders 的资料可以通过pip安装。通常情况下，您需要安装最新版本，但也可以安装特定的旧版本，甚至是最新的开发版本。请确保已按照上述说明设置GH_TOKEN变量。

¥Material for MkDocs Insiders can be installed with pip. You will normally want to install the latest release but can also install a specific older release or even the latest development version. Make sure you have the GH_TOKEN variable set as instructed above.

Specific releaseLatest

从 Insiders 仓库的标签列表中选择相应的标签。在下面的pip命令中，将 URL 末尾的标签替换为您想要的标签。

¥Pick the corresponding tag from the list of tags for the Insiders repository. In the pip command below, replace the tag at the end of the URL with the one you want.

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¶

¥with docker¶

如果您想在 Docker 中使用 MkDocs Insiders 的 Material，则需要执行一些额外的步骤。虽然我们无法为 Insiders 1提供托管的 Docker 镜像，但GitHub Container Registry允许简单便捷地进行自托管：

¥In case you want to use Material for MkDocs Insiders from within Docker, some additional steps are necessary. While we cannot provide a hosted Docker image for Insiders¹, GitHub Container Registry allows for simple and comfortable self-hosting:

Fork Insiders 仓库
¥Fork the Insiders repository
在你的 fork 上启用GitHub Actions 2
¥Enable GitHub Actions on your fork
创建新的个人访问令牌3转到https://github.com/settings/tokens单击生成新令牌输入名称并选择write:packages范围生成令牌并将其存储在安全的地方
¥Create a new personal access token³
在你的 fork 上添加GitHub Actions secret将名称设置为GHCR_TOKEN将值设置为上一步中创建的个人访问令牌
¥Go to https://github.com/settings/tokens
创建新版本以构建并发布 Docker 镜像
¥Click on Generate a new token
在你的 fork 上安装Pull App ，以与上游保持同步
¥Enter a name and select the write:packages scope

创建新标签（发布）时，构建工作流会自动运行。当上游代码库发布新的 Insiders 版本时，拉取应用会创建一个包含更改的拉取请求，并拉取新的标签。构建工作流会接收该标签，并自动构建 Docker 镜像并将其发布到您的私有镜像仓库。

¥The build workflow is automatically run when a new tag (release) is created. When a new Insiders version is released on the upstream repository, the Pull App will create a pull request with the changes and pull in the new tag, which is picked up by the build workflow that builds and publishes the Docker image automatically to your private registry.

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

¥Now, you should be able to pull the Docker image from your private registry:

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

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

¥Should you wish to add additional plugins to the insiders container image, follow the steps outlined in the Getting Started guide.

使用 git¶

¥with git¶

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

¥Of course, you can use Material for MkDocs Insiders directly from git:

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

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

¥The theme will reside in the folder mkdocs-material/material. When cloning from git, the theme must be installed, so MkDocs can find the built-in plugins:

pip install -e mkdocs-material

内置插件¶

¥Built-in plugins¶

当您使用仅通过内部人员提供的内置插件时，外部贡献者将无法在其本地计算机上构建您的文档项目。这就是我们开发内置组插件的原因，该插件允许有条件地加载插件：

¥When you're using built-in plugins that are solely available via Insiders, outside contributors won't be able to build your documentation project on their local machine. This is the reason why we developed the built-in group plugin that allows to conditionally load plugins:

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

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

¥Of course, you can also enable both groups with:

CI=true INSIDERS=true mkdocs build

此前，Insiders 提供了一个专用的 Docker 镜像，供所有赞助商使用。2021 年 3 月 21 日，该镜像因#2442中概述和讨论的原因而被弃用。该镜像已于 2021 年 6 月 1 日被移除。↩
¥Generate the token and store it in a safe place
在 fork 仓库时，GitHub 将禁用所有工作流程。虽然这是一个合理的默认设置，但您需要启用 GitHub Actions 才能自动构建 Docker 镜像并将其发布到GitHub Container Registry上。↩
¥Add a GitHub Actions secret on your fork
虽然您可以将write:packages范围添加到为访问 Insiders 存储库而创建的个人访问令牌中，但创建专用令牌更安全，您只能使用该令牌发布 Docker 镜像。↩
¥Set the name to GHCR_TOKEN