Skip to content

添加 git 存储库

¥Adding a git repository

如果您的文档与源代码相关，Material for MkDocs 可以将项目代码库的信息（包括 star 和 fork）作为静态站点的一部分显示到项目中。此外，还可以显示上次更新和创建的日期以及贡献者。

¥If your documentation is related to source code, Material for MkDocs provides the ability to display information to the project's repository as part of the static site, including stars and forks. Furthermore, the date of last update and creation, as well as contributors can be shown.

配置

¥Configuration

存储库

¥Repository

0.1.0

¥0.1.0

为了将项目存储库的链接显示为文档的一部分，请将mkdocs.yml中的repo_url设置为存储库的公共 URL，例如：

¥In order to display a link to the repository of your project as part of your documentation, set repo_url in mkdocs.yml to the public URL of your repository, e.g.:

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

在大屏幕上，存储库的链接将显示在搜索栏旁边，而在小屏幕上，则显示为主导航栏的一部分。

¥The link to the repository will be rendered next to the search bar on big screens and as part of the main navigation drawer on smaller screen sizes.

此外，对于托管在GitHub或GitLab上的公共存储库，会自动请求和呈现最新版本的标签1以及星标和分支的数量。

¥Additionally, for public repositories hosted on GitHub or GitLab, the latest release tag1, as well as the number of stars and forks, are automatically requested and rendered.

存储库名称

¥Repository name

0.1.0自动设置为 GitHub、GitLab 或 Bitbucket

¥0.1.0 automatically set to GitHub, GitLab or Bitbucket

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

¥MkDocs will infer the source provider by examining the URL and try to set the repository name automatically. If you wish to customize the name, set repo_name in mkdocs.yml:

repo_name: squidfunk/mkdocs-material

存储库图标

¥Repository icon

5.0.0

¥5.0.0

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

¥While the default repository icon is a generic git icon, it can be set to any icon bundled with the theme by referencing a valid icon path in mkdocs.yml:

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

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

一些受欢迎的选择：

¥Enter a few keywords to find the perfect icon using our icon search and click on the shortcode to copy it to your clipboard:

  • – fontawesome/brands/git

    ¥ – fontawesome/brands/git

  • – fontawesome/brands/git-alt

    ¥ – fontawesome/brands/git-alt

  • – fontawesome/brands/github

    ¥ – fontawesome/brands/github

  • – fontawesome/brands/github-alt

    ¥ – fontawesome/brands/github-alt

  • – fontawesome/brands/gitlab

    ¥ – fontawesome/brands/gitlab

  • – fontawesome/brands/gitkraken

    ¥ – fontawesome/brands/gitkraken

  • – fontawesome/brands/bitbucket

    ¥ – fontawesome/brands/bitbucket

  • – fontawesome/solid/trash

    ¥ – fontawesome/solid/trash

代码操作

¥Code actions

9.0.0

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

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

¥Some popular choices:

edit_uri: edit/main/docs/

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

¥9.0.0 

theme:
  features:
    - content.action.edit

theme:
  features:
    - content.action.view

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

¥If the repository URL points to a valid GitHub, GitLab or Bitbucket repository, MkDocs provides a setting called edit_uri, which resolves to the subfolder where your documentation is hosted.

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

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

修订

¥Revisioning

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

¥If your default branch is called main, change the setting to:

文件日期

¥Document dates

4.6.0 git-revision-date-localized

¥After making sure that edit_uri is correctly configured, buttons for code actions can be added. Two types of code actions are supported: edit and view (GitHub only):

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

¥The icon of the edit and view buttons can be changed with the following lines:

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

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

¥Enter a few keywords to find the perfect icon using our icon search and click on the shortcode to copy it to your clipboard:

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 ：

¥The following plugins are fully integrated with Material for MkDocs, allowing for showing the date of last update and creation of a document, as well as links to all contributors or authors involved.

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

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

¥4.6.0 git-revision-date-localized

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

使用构建环境时

¥The git-revision-date-localized plugin adds support for adding the date of last update and creation of a document at the bottom of each page. Install it with pip:

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

¥Then, add the following lines to mkdocs.yml:

fallback_to_build_date

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

¥The following configuration options are supported:

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

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

¥true This option specifies whether the plugin is enabled when building your project. If you want to switch the plugin off, e.g. for local builds, use an environment variable:

文档贡献者

¥Document contributors

9.5.0 git 提交者

¥date The format of the date to be displayed. Valid values are date, datetime, iso_date, iso_datetime and timeago:

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

¥false Enables the display of the creation date of the file associated with the page next to the last updated date at the bottom of the page:

pip install mkdocs-git-committers-plugin-2

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

¥When using build environments

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

支持以下配置选项：

¥If you are deploying through a CI system, you might need to adjust your CI settings when fetching the code. For more information, see git-revision-date-localized.

enabled

true此选项指定在构建项目时是否启用该插件。如果您想关闭该插件（例如在本地构建时），请使用环境变量：

¥false Enables falling back to the time when mkdocs build was executed. Can be used as a fallback when the build is performed outside of a git repository:

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

此属性必须设置为包含文档的存储库的 slug。该 slug 必须遵循以下格式<username>/<repository> ：

¥The other configuration options of this extension are not officially supported by Material for MkDocs, which is why they may yield unexpected results. Use them at your own risk.

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

master此属性应设置为用于检索贡献者的仓库分支。要使用main分支，请执行以下操作：

¥9.5.0 git-committers 

plugins:
  - git-committers:
      branch: main

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

¥The git-committers2 plugin renders the GitHub avatars of all contributors, linking to their GitHub profiles at the bottom of each page. As always, it can be installed with pip:

文档作者

¥Document authors

9.5.0 git 作者

¥Then, add the following lines to mkdocs.yml:

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

¥The following configuration options are supported:

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

¥true This option specifies whether the plugin is enabled when building your project. If you want to switch the plugin off, e.g. for local builds, use an environment variable:

pip install mkdocs-git-authors-plugin

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

¥ This property must be set to the slug of the repository that contains your documentation. The slug must follow the pattern <username>/<repository>:

plugins:
  - git-authors

  1. 遗憾的是，GitHub 仅提供 API 端点来获取最新版本，而非最新标签。因此，请确保为您想要在 star 和 fork 数量旁边显示的最新标签创建一个版本（而非预发布版本） 。对于 GitLab，虽然可以获取按更新时间排序的标签列表，但使用的是等效的 API 端点。因此，请确保也为 GitLab 仓库创建一个版本。↩

  2. 我们目前建议使用git-committers插件的 fork，因为它包含许多尚未合并回原插件的改进。更多信息请参阅byrnereese/mkdocs-git-committers-plugin#12。↩