mirror of https://github.com/squidfunk/mkdocs-material.git synced 2024-12-18 10:25:58 +01:00

squidfunk b6cd73e083 Updated documentation

2021-10-10 12:19:14 +02:00

6.1 KiB

Raw Blame History

template
overrides/main.html

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 statistics like stars and forks. Furthermore, individual documents can be linked to specific source files.

Configuration

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

Repository name

:octicons-file-code-24: Source · :octicons-milestone-24: 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

:octicons-file-code-24: Source · :octicons-milestone-24: 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

Some popular choices:

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

Edit button

:octicons-file-code-24: Source · :octicons-milestone-24: 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:

=== "Customize edit path"

``` yaml
edit_uri: edit/master/docs/
```

=== "Hide edit button"

``` yaml
edit_uri: ""
```

Revision date

:octicons-file-code-24: Source · :octicons-cpu-24: Plugin

The git-revision-date plugin adds support for displaying the date a document was last updated at the bottom of each page. It can be installed with pip:

pip install mkdocs-git-revision-date-plugin

Then, add the following to mkdocs.yml:

plugins:
  - git-revision-date

The following options are supported:

enabled_if_env{ #enabled-if-env }

:octicons-milestone-24: Default: none – When specified the data will only be extracted from git if the environment variable exists. This makes it possible to disable extraction for cases when the repository is not available:

plugins:
  - git-revision-date:
      enabled_if_env: CI

Material for MkDocs doesn't provide official support for the other options of this plugin, so they may be supported but might yield unexpected results. Use them at your own risk.

Revision date, localized

:octicons-file-code-24: Source · :octicons-cpu-24: Plugin

Similarly, the git-revision-date-localized plugin adds support for adding a localized updated at and created at date at the bottom of each page. It can be installed with pip:

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

Then, add the following to mkdocs.yml:

plugins:
  - git-revision-date-localized

The following options are supported:

type{ #type }

:octicons-milestone-24: 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

fallback_to_build_date{ #fallback-to-build-date }

:octicons-milestone-24: 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 the git repository:

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

enable_creation_date{ #enable-creation-date }

:octicons-milestone-24: Default: false – Enables the display of the created at date of the file associated with the page next to the updated at date at the bottom of the page:

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