Skip to content

Adding a git repository

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 · Default: none

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. Additionally, for public repositories hosted on GitHub or GitLab, the number of stars and forks is automatically requested and rendered.

GitHub repositories also include the tag of the latest release.1

Repository name

0.1.0 · Default: 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: squidfunk/mkdocs-material

Repository icon

5.0.0 · Default: fontawesome/brands/git-alt

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:

    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

    Edit button

    0.1.0 · Default: automatically set

    If the repository URL points to a GitHub, GitLab or Bitbucket repository, an edit button is displayed at the top of each document. This behavior can be changed by setting edit_uri in mkdocs.yml:

    edit_uri: edit/master/docs/
    
    edit_uri: ""
    

    Revisioning

    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.

    Document dates

    4.6.0 · Plugin

    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:

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

    Then, add the following lines to mkdocs.yml:

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

    The following configuration options are supported:

    type

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

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

    7.1.4 · Default: 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:

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

    Default: 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-revision-date-localized:
          fallback_to_build_date: true
    

    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.

    Document contributors

    Sponsors only · insiders-4.19.0 · Plugin · Experimental

    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:

    pip install mkdocs-git-committers-plugin-2
    

    Then, add the following lines to mkdocs.yml:

    plugins:
      - git-committers:
          repository: squidfunk/mkdocs-material
          token: !ENV GH_TOKEN
    

    The following configuration options are supported:

    repository

    Default: none · Required – 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: squidfunk/mkdocs-material
    
    token

    Default: none – This property should3 be set to a personal access token, which is used by the plugin to query GitHub's API for document contributor information:

    plugins:
      - git-committers:
          token: !ENV GH_TOKEN
    

    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.

    Document authors

    Sponsors only · insiders-4.19.0 · Plugin · Experimental

    The git-authors plugin extracts the authors of a document from git to display them at the bottom of each page. It's a lightweight alternative to the git-committers plugin. Install it with pip:

    pip install mkdocs-git-authors-plugin
    

    Then, add the following lines to mkdocs.yml:

    plugins:
      - git-authors
    

    1. 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. 

    2. 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. 

    3. Setting a personal access token is not required, but recommended, as GitHub has very low rate limits on their APIs that you'll probably run into. When using a token, rate limits are much higher.