mirror of https://github.com/squidfunk/mkdocs-material.git synced 2024-06-14 11:52:32 +03:00

Daniel Webber 9c8ff64084 Change content

2023-09-14 23:21:40 +08:00

16 KiB

Raw Blame History

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

:octicons-tag-24: 0.1.0 · :octicons-milestone-24: 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.¹

Repository name

:octicons-tag-24: 0.1.0 · :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-tag-24: 5.0.0 · :octicons-milestone-24: Default: :fontawesome-brands-git-alt: – 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)!

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

:octicons-tag-24: 9.0.0 · :octicons-unlock-24: Feature flag

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

=== ":material-file-edit-outline: Edit this page"

``` yaml
theme:
  features:
    - content.action.edit
```

=== ":material-file-eye-outline: View source of this page"

``` yaml
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:

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

:octicons-tag-24: 4.6.0 · :octicons-cpu-24: 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:

enabled{ #+git-revision-date-localized.enabled }

:octicons-milestone-24: Default: 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-revision-date-localized:
      enabled: !ENV [CI, false]

type{ #+git-revision-date-localized.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

enable_creation_date{ #+git-revision-date-localized.enable_creation_date }

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

!!! note If you are deploying through a CI system, please do the CI configuration as described in the git-revision-date-localized documentation.

[With Github Actions](../publishing-your-site.md#with-github-actions):

=== "Material for MkDocs"

    ``` yaml hl_lines="14 15"
    name: ci # (1)!
    on:
      push:
        branches:
          - master # (2)!
          - main
    permissions:
      contents: write
    jobs:
      deploy:
        runs-on: ubuntu-latest
        steps:
          - uses: actions/checkout@v3
            with:
              fetch-depth: 0
          - uses: actions/setup-python@v4
            with:
              python-version: 3.x
          - run: echo "cache_id=$(date --utc '+%V')" >> $GITHUB_ENV # (3)!
          - uses: actions/cache@v3
            with:
              key: mkdocs-material-${{ env.cache_id }}
              path: .cache
              restore-keys: |
                mkdocs-material-
          - run: pip install mkdocs-material # (4)!
          - run: mkdocs gh-deploy --force
    ```

    1.  You can change the name to your liking. 

    2.  At some point, GitHub renamed `master` to `main`. If your default branch
        is named `master`, you can safely remove `main`, vice versa.

    3.  Store the `cache_id` environmental variable to access it later during cache
        `key` creation. The name is case-sensitive, so be sure to align it with `${{ env.cache_id }}`.

        - The `--utc` option makes sure that each workflow runner uses the same time zone.
        - The `%V` format assures a cache update once a week. 
        - You can change the format to `%F` to have daily cache updates. 

        You can read the [manual page] to learn more about the formatting options of the `date` command.

    4.  This is the place to install further [MkDocs plugins] or Markdown
        extensions with `pip` to be used during the build:

        ``` sh
        pip install \
          mkdocs-material \
          mkdocs-awesome-pages-plugin \
          ...
        ```

=== "Insiders"

    ``` yaml hl_lines="15 16"
    name: ci
    on:
      push:
        branches:
          - master
          - main
    permissions:
      contents: write
    jobs:
      deploy:
        runs-on: ubuntu-latest
        if: github.event.repository.fork == false
        steps:
          - uses: actions/checkout@v3
            with:
              fetch-depth: 0
          - uses: actions/setup-python@v4
            with:
              python-version: 3.x
          - run: echo "cache_id=$(date --utc '+%V')" >> $GITHUB_ENV
          - uses: actions/cache@v3
            with:
              key: mkdocs-material-${{ env.cache_id }}
              path: .cache
              restore-keys: |
                mkdocs-material-
          - run: apt-get install pngquant # (1)!
          - run: pip install git+https://${GH_TOKEN}@github.com/squidfunk/mkdocs-material-insiders.git
          - run: mkdocs gh-deploy --force
    env:
      GH_TOKEN: ${{ secrets.GH_TOKEN }} # (2)!
    ```

    1.  This step is only necessary if you want to use the
        [built-in optimize plugin] to automatically compress images.

    2.  Remember to set the `GH_TOKEN` environment variable to the value of your
        [personal access token] when deploying [Insiders], which can be done
        using [GitHub secrets].

fallback_to_build_date{ #+git-revision-date-localized.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 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

:octicons-heart-fill-24:{ .mdx-heart } Sponsors only{ .mdx-insiders } · :octicons-tag-24: insiders-4.19.0 · :octicons-cpu-24: Plugin · :octicons-beaker-24: Experimental

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: squidfunk/mkdocs-material
      branch: main

The following configuration options are supported:

enabled{ #+git-committers.enabled }

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

repository{ #+git-committers.repository }

:octicons-milestone-24: Default: none · :octicons-alert-24: 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

branch{ #+git-committers.branch }

:octicons-milestone-24: Default: 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 Material for MkDocs, which is why they may yield unexpected results. Use them at your own risk.

Document authors

:octicons-heart-fill-24:{ .mdx-heart } Sponsors only{ .mdx-insiders } · :octicons-tag-24: insiders-4.19.0 · :octicons-cpu-24: Plugin · :octicons-beaker-24: Experimental

The git-authors plugin is a lightweight alternative to the git-committers plugin and extracts the authors of a document from git to display them at the bottom of each page.

Insiders offers deep integration for git-authors. This means the customized overrides are not necessary, and additional styling (such as nice icons) are added. Simply install it with pip:

pip install mkdocs-git-authors-plugin

Then, add the following lines to mkdocs.yml:

plugins:
  - git-authors

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. ↩︎
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. ↩︎

16 KiB Raw Blame History Unescape Escape

Adding a git repository

Configuration

Repository

Repository name

Repository icon

Code actions

Revisioning

Document dates

Document contributors

Document authors

16 KiB

Raw Blame History