添加 Git 仓库¶

如果您的文档与源代码相关，Material for MkDocs 提供了将项目信息显示为静态网站的一部分的能力，包括星标和分支。此外，[最后更新和创建日期]以及[贡献者]也可以显示。

配置¶

仓库¶

0.1.0

为了在文档中显示项目仓库的链接，请在 mkdocs.yml 中将 repo_url 设置为您仓库的公共 URL，例如：

repo_url: https://github.com/squidfunk/mkdocs-material

在大屏幕上，仓库链接将渲染在搜索栏旁边，而在小屏幕上则作为主导航抽屉的一部分。

此外，对于托管在 GitHub 或 GitLab 的公共仓库，最新的发布标签¹以及星标和分支的数量会被自动请求并渲染。

仓库名称¶

0.1.0 automatically set to GitHub, GitLab or Bitbucket

MkDocs 将通过检查 URL 来推断源提供者，并尝试自动设置 仓库名称。如果您希望自定义名称，请在 mkdocs.yml 中设置 repo_name：

repo_name: squidfunk/mkdocs-material

仓库图标¶

5.0.0

默认的仓库图标是一个通用的 git 图标，但可以通过在 mkdocs.yml 中引用有效的图标路径，将其设置为主题中捆绑的任何图标：

theme:
  icon:
    repo: fontawesome/brands/git-alt # (1)!

1. 输入几个关键字以使用我们的 [图标搜索] 找到完美的图标，然后点击短代码将其复制到剪贴板：

一些流行的选择：

• – fontawesome/brands/git
• – fontawesome/brands/git-alt
• – fontawesome/brands/github
• – fontawesome/brands/github-alt
• – fontawesome/brands/gitlab
• – fontawesome/brands/gitkraken
• – fontawesome/brands/bitbucket
• – fontawesome/solid/trash

代码操作¶

9.0.0

如果 [仓库 URL] 指向有效的 GitHub、GitLab 或 Bitbucket 仓库，MkDocs 提供一个名为 edit_uri 的设置，该设置解析为托管文档的子文件夹。

如果您的默认分支名为 main，请将设置更改为：

edit_uri: edit/main/docs/

确保 edit_uri 配置正确后，可以添加代码操作按钮。支持两种类型的代码操作：edit 和 view（仅限 GitHub）：

theme:
  features:
    - content.action.edit

theme:
  features:
    - content.action.view

可以使用以下行更改编辑和查看按钮的图标：

theme:
  icon:
    edit: material/pencil # (1)!
    view: material/eye

1. 输入几个关键字以使用我们的 [图标搜索] 找到完美的图标，然后点击短代码将其复制到剪贴板：

版本控制¶

以下插件与 Material for MkDocs 完全集成，允许显示文档的 [最后更新和创建日期]，以及所有 [贡献者] 或 [作者] 的链接。

文档日期¶

4.6.0 git-revision-date-localized

git-revision-date-localized 插件支持在每个页面底部添加文档的最后更新和创建日期。使用 pip 安装它：

pip install mkdocs-git-revision-date-localized-plugin

然后，将以下行添加到 mkdocs.yml：

plugins:
  - git-revision-date-localized:
      enable_creation_date: true

支持以下配置选项：

enabled

true 此选项指定在构建项目时插件是否启用。如果您希望关闭插件，例如用于本地构建，请使用 [环境变量]：

plugins:
  - git-revision-date-localized:
      enabled: !ENV [CI, false]

type

date 要显示的日期格式。有效值为 date、datetime、iso_date、iso_datetime 和 timeago：

plugins:
  - git-revision-date-localized:
      type: date

enable_creation_date

false 启用在页面底部显示与页面关联的文件的创建日期，旁边显示最后更新日期：

plugins:
  - git-revision-date-localized:
      enable_creation_date: true

使用构建环境时

如果您通过 CI 系统进行部署，您可能需要在获取代码时调整 CI 设置。有关更多信息，请参见 git-revision-date-localized。

fallback_to_build_date

false 启用回退到执行 mkdocs build 的时间。当构建在 git 仓库外部执行时，可以用作回退：

plugins:
  - git-revision-date-localized:
      fallback_to_build_date: true

此扩展的其他配置选项未被 Material for MkDocs 官方支持，因此可能会产生意想不到的结果。请自行承担风险使用它们。

文档贡献者¶

9.5.0 git-committers

git-committers² 插件在每个页面底部渲染所有贡献者的 GitHub 头像，并链接到他们的 GitHub 个人资料。和往常一样，可以使用 pip 安装：

pip install mkdocs-git-committers-plugin-2

然后，将以下行添加到 mkdocs.yml：

plugins:
  - git-committers:
      repository: squidfunk/mkdocs-material
      branch: main

支持以下配置选项：

enabled

true 此选项指定在构建项目时插件是否启用。如果您希望关闭插件，例如用于本地构建，请使用 [环境变量]：

plugins:
  - git-committers:
      enabled: !ENV [CI, false]

repository

此属性必须设置为包含您文档的仓库的 slug。slug 必须遵循 <username>/<repository> 的模式：

plugins:
  - git-committers:
      repository: squidfunk/mkdocs-material

branch

master 此属性应设置为要从中检索贡献者的仓库分支。要使用 main 分支：

plugins:
  - git-committers:
      branch: main

此扩展的其他配置选项未被 Material for MkDocs 官方支持，因此可能会产生意想不到的结果。请自行承担风险使用它们。

文档作者¶

9.5.0 git-authors

git-authors 插件是 git-committers 插件的轻量级替代方案，从 git 中提取文档的作者并在每个页面底部显示他们。

Material for MkDocs 对 git-authors 提供了深度集成。这意味着不需要 自定义覆盖，并且添加了额外的样式（例如漂亮的图标）。只需使用 pip 安装：

pip install mkdocs-git-authors-plugin

然后，将以下行添加到 mkdocs.yml：

plugins:
  - git-authors