Adding a git repository¶

If your documentation is related to source code, MaterialX 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

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/jaywhj/mkdocs-materialx

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.

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

Repository name¶

0.1.0 automatically set to GitHub, GitLab or Bitbucket

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: jaywhj/mkdocs-materialx

Repository icon¶

5.0.0

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)!

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

Some popular choices:

– 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

Code actions¶

9.0.0

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.

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

edit_uri: edit/main/docs/

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):

Edit this page View source of this page

theme:
  features:
    - content.action.edit

theme:
  features:
    - content.action.view

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

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

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

Document dates & authors¶

10.0.4 document-dates

You can add date and author information to your documents via the next-generation Date & Author plugin document-dates.

Installation¶

Install it with pip:

pip install mkdocs-document-dates

Then, add the following lines to mkdocs.yml:

plugins:
  - document-dates

Configuration¶

The following configuration options are supported:

position

top This option specifies the display position of the plugin. Valid values are top, bottom:

plugins:
  - document-dates:
      position: top

type

date This option specifies the type of date to be displayed. Valid values are date, datetime, timeago:

plugins:
  - document-dates:
      type: date

exclude

This option specifies a list of excluded files:

plugins:
  - document-dates:
      exclude:
        - temp.md   # Example: exclude the specified file
        - blog/*    # Example: exclude all files in blog folder, including subfolders

date_format

%Y-%m-%d This option specifies the date formatting string:

plugins:
  - document-dates:
      date_format: '%Y-%m-%d'   # e.g., %Y-%m-%d, %b %d, %Y
      time_format: '%H:%M:%S'   # valid only if type=datetime

show_created

true This option specifies whether to display the creation date. Valid values are true, false:

plugins:
  - document-dates:
      show_created: true

When using build environments

If you are deploying through a CI system, you might need to adjust your CI settings when fetching the code:

Github Actions: set fetch-depth to 0 (docs)
Gitlab Runners: set GIT_DEPTH to 0 (docs)
Bitbucket pipelines: set clone: depth: full (docs)
Azure Devops pipelines: set Agent.Source.Git.ShallowFetchDepth to something very high like 10e99 (docs)

show_updated

true This option specifies whether to display the last updated date. Valid values are true, false:

plugins:
  - document-dates:
      show_updated: true

show_author

true This option specifies the type of author display. Valid values are true(avatar), false(hidden), text(text):

plugins:
  - document-dates:
      show_author: true   # true(avatar) text(text) false(hidden)

Customization settings¶

In addition to the above basic configuration, the plug-in also provides a wealth of customization options to meet a variety of individual needs:

Specify datetime: introduces the mechanism for obtaining document dates and methods for personalized customization, you can manually specify the creation date and last updated date for each document
Specify author: introduces the mechanism for obtaining document authors and methods for personalized customization, you can manually specify the author information for each document, such as name, link, avatar, email, etc.
Specify avatar: you can manually specify the avatar for each author, support local file path and URL path
Configuration structure and style: you can freely configure the plugin's display structure in mkdocs.yml or Front Matter. You can quickly set the plugin styles through preset entrances, such as icons, themes, colors, fonts, animations, dividing line and so on
Use template variables: can be used to optimize sitemap.xml for site SEO; can be used to re-customize plug-ins, etc.
Add recent updates module: enable list of recently updated documents (in descending order of update date), this is ideal for sites with a large number of documents, so that readers can quickly see what's new
Add localized languages: more localization languages for timeago and tooltip
Other tips: introducing the Do's of using plugin in Docker

For more details: Document dates & authors

Document contributors¶

9.5.0 git-committers

The git-committers² 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:

pip install mkdocs-git-committers-plugin-2

Then, add the following lines to mkdocs.yml:

plugins:
  - git-committers:
      repository: jaywhj/mkdocs-materialx
      branch: main

The following configuration options are supported:

enabled

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:

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

repository

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-committers:
      repository: jaywhj/mkdocs-materialx

branch

master This property should be set to the branch of the repository from which to retrieve the contributors. To use the main branch:

plugins:
  - git-committers:
      branch: main

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

Unfortunately, GitHub only provides an API endpoint to obtain the latest release - not the latest tag. Thus, make sure to create a release (not pre-release) for the latest tag you want to display next to the number of stars and forks. For GitLab, although it is possible to get a list of tags sorted by update time, the equivalent API endpoint is used. So, make sure you also create a release for GitLab repositories. ↩
We currently recommend using a fork of the git-committers plugin, as it contains many improvements that have not yet been merged back into the original plugin. See byrnereese/mkdocs-git-committers-plugin#12 for more information. ↩