添加git存储库¶

如果您的文档与源代码有关，MkDocs材料提供 作为项目存储库的一部分显示信息的能力 静态站点，包括星和叉。此外 可以显示[上次更新和创建日期]以及[贡献者]。

配置¶

存储库¶

为了在您的项目中显示指向项目存储库的链接 documentation，将mkdocs.yml中的repo_url设置为以下内容的公共url 您的存储库，例如：

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

指向存储库的链接将显示在big上的搜索栏旁边 屏幕，并在较小屏幕尺寸上作为主导航抽屉的一部分。

此外，对于托管在GitHub或GitLab上的公共存储库 最新发布标签¹，以及星和叉的数量 自动请求和呈现。

存储库名称¶

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

repo_name: squidfunk/mkdocs-material

存储库图标¶

虽然默认存储库图标是通用的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

代码操作¶

如果[存储库URL]指向有效的GitHub、GitLab或Bitbucket 存储库中，MkDocs提供了一个名为edit_uri的设置 解析到承载文档的子文件夹。

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

edit_uri: edit/main/docs/

在确保“edit_uri”配置正确后，代码按钮 可以添加动作。支持两种类型的代码操作：“编辑”和“查看”` （仅限GitHub）：

theme:
  features:
    - content.action.edit

theme:
  features:
    - content.action.view

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

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

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

修订¶

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

文件日期¶

[git修订日期本地化]插件增加了对添加日期的支持 最后更新和创建每页底部的文档。安装它 使用pip：

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

然后，在mkdocs.yml中添加以下行：

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

支持以下配置选项：

此选项指定是否 在构建项目时启用该插件。如果你想切换 关闭插件，例如对于本地构建，使用[环境变量]：

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

日期格式为 显示。有效值为“date”、“datetime”、“iso_date”、“iso _datetime”` 以及“timeago”：

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

启用显示 与上次更新页面旁边的页面关联的文件的创建日期 页面底部的日期：

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

使用构建环境时

如果您通过CI系统进行部署，可能需要调整您的 获取代码时的CI设置。有关更多信息，请参见 [git修订日期本地化]。

允许回退到 执行mkdocs-build的时间。在以下情况下可以用作后备 构建是在git存储库之外执行的：

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

此扩展的其他配置选项不受官方支持 MkDocs的材料，这就是为什么它们可能会产生意想不到的结果。使用 他们的风险由你自己承担。

文档贡献者¶

[git committers]²插件呈现所有贡献者的GitHub头像， 链接到每个页面底部的GitHub配置文件。一如既往，它可以 使用pip进行安装：

pip install mkdocs-git-committers-plugin-2

然后，在mkdocs.yml中添加以下行：

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

支持以下配置选项：

此选项指定是否 在构建项目时启用该插件。如果你想切换 关闭插件，例如对于本地构建，使用[环境变量]：

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

此属性必须设置为包含您的存储库的slug 文档。slug必须遵循“/”模式：

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

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

plugins:
  - git-committers:
      branch: main

此扩展的其他配置选项不受官方支持 MkDocs的材料，这就是为什么它们可能会产生意想不到的结果。使用 他们的风险由你自己承担。

文档作者¶

[git authors]插件是轻量级的替代品 [git committers]插件，从git中提取文档的作者以显示 它们位于每页的底部。

MkDocs的材料为[git作者]提供了深度集成。这意味着 [自定义覆盖](https://timvink.github.io/mkdocs-git-authors-plugin/usage.html#mkdocs-材料主题） 并且添加了额外的样式（如漂亮的图标）。 只需使用pip进行安装：

pip install mkdocs-git-authors-plugin

然后，在mkdocs.yml中添加以下行：

plugins:
  - git-authors