mirror of
https://github.com/squidfunk/mkdocs-material.git
synced 2024-11-30 18:24:35 +01:00
241 lines
8.1 KiB
Markdown
241 lines
8.1 KiB
Markdown
---
|
||
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
|
||
|
||
### Repository
|
||
|
||
[:octicons-tag-24: 0.1.0][repo_url support] ·
|
||
: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`][repo_url] in `mkdocs.yml` to the public URL of
|
||
your repository, e.g.:
|
||
|
||
``` yaml
|
||
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]
|
||
|
||
[^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 show up next to the number of
|
||
stars and forks.
|
||
|
||
[repo_url support]: https://github.com/squidfunk/mkdocs-material/releases/tag/0.1.0
|
||
[repo_url]: https://www.mkdocs.org/user-guide/configuration/#repo_url
|
||
[latest release]: https://docs.github.com/en/rest/reference/releases#get-the-latest-release
|
||
[create a release]: https://docs.github.com/en/repositories/releasing-projects-on-github/managing-releases-in-a-repository#creating-a-release
|
||
|
||
### Repository name
|
||
|
||
[:octicons-tag-24: 0.1.0][repo_name support] ·
|
||
: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`][repo_name] in `mkdocs.yml`:
|
||
|
||
``` yaml
|
||
repo_name: squidfunk/mkdocs-material
|
||
```
|
||
|
||
[repo_name support]: https://github.com/squidfunk/mkdocs-material/releases/tag/0.1.0
|
||
[repo_name]: https://www.mkdocs.org/user-guide/configuration/#repo_name
|
||
|
||
### Repository icon
|
||
|
||
[:octicons-tag-24: 5.0.0][icon.repo support] ·
|
||
:octicons-milestone-24: Default:
|
||
[`fontawesome/brands/git-alt`][icon.repo default]
|
||
|
||
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`:
|
||
|
||
``` yaml
|
||
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:
|
||
|
||
<div class="mdx-iconsearch" data-mdx-component="iconsearch">
|
||
<input class="md-input md-input--stretch mdx-iconsearch__input" placeholder="Search icon" data-mdx-component="iconsearch-query" value="git" />
|
||
<div class="mdx-iconsearch-result" data-mdx-component="iconsearch-result" data-mdx-mode="file">
|
||
<div class="mdx-iconsearch-result__meta"></div>
|
||
<ol class="mdx-iconsearch-result__list"></ol>
|
||
</div>
|
||
</div>
|
||
|
||
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`
|
||
|
||
[icon.repo support]: https://github.com/squidfunk/mkdocs-material/releases/tag/5.0.0
|
||
[icon.repo default]: https://github.com/squidfunk/mkdocs-material/blob/master/material/.icons/fontawesome/brands/git-alt.svg
|
||
[icon search]: ../reference/icons-emojis.md#search
|
||
|
||
### Edit button
|
||
|
||
[:octicons-tag-24: 0.1.0][edit_uri support] ·
|
||
: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`][edit_uri] in `mkdocs.yml`:
|
||
|
||
=== "Customize edit path"
|
||
|
||
``` yaml
|
||
edit_uri: edit/master/docs/
|
||
```
|
||
|
||
=== "Hide edit button"
|
||
|
||
``` yaml
|
||
edit_uri: ""
|
||
```
|
||
|
||
[edit_uri support]: https://github.com/squidfunk/mkdocs-material/releases/tag/0.1.0
|
||
[edit_uri]: https://www.mkdocs.org/user-guide/configuration/#edit_uri
|
||
[GitHub]: https://github.com/
|
||
[GitLab]: https://about.gitlab.com/
|
||
[Bitbucket]: https://bitbucket.org/
|
||
|
||
### Revision date
|
||
|
||
[:octicons-tag-24: 4.6.0][git-revision-date support] ·
|
||
[:octicons-cpu-24: Plugin][git-revision-date]
|
||
|
||
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 lines to `mkdocs.yml`:
|
||
|
||
``` yaml
|
||
plugins:
|
||
- git-revision-date
|
||
```
|
||
|
||
The following configuration options are supported:
|
||
|
||
`enabled_if_env`{ #enabled-if-env }
|
||
|
||
: :octicons-milestone-24: Default: _none_ – When specified, the plugin will
|
||
only be invoked if the environment variable exists. This makes it easy to
|
||
disable extraction for cases when the repository is not available:
|
||
|
||
``` yaml
|
||
plugins:
|
||
- git-revision-date:
|
||
enabled_if_env: CI
|
||
```
|
||
|
||
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.
|
||
|
||
[git-revision-date support]: https://github.com/squidfunk/mkdocs-material/releases/tag/4.6.0
|
||
[git-revision-date]: https://github.com/zhaoterryy/mkdocs-git-revision-date-plugin
|
||
|
||
### Revision date, localized
|
||
|
||
[:octicons-tag-24: 4.6.0][git-revision-date-localized support] ·
|
||
[:octicons-cpu-24: Plugin][git-revision-date-localized]
|
||
|
||
Similarly, the [git-revision-date-localized] plugin adds support for adding
|
||
a localized update and creation 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`:
|
||
|
||
``` yaml
|
||
plugins:
|
||
- git-revision-date-localized
|
||
```
|
||
|
||
The following configuration 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`:
|
||
|
||
``` yaml
|
||
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 a git repository:
|
||
|
||
``` yaml
|
||
plugins:
|
||
- git-revision-date-localized:
|
||
fallback_to_build_date: true
|
||
```
|
||
|
||
`enable_creation_date`{ #enable-creation-date }
|
||
|
||
: [:octicons-tag-24: 7.1.4][enable_creation_date support] ·
|
||
: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:
|
||
|
||
``` yaml
|
||
plugins:
|
||
- git-revision-date-localized:
|
||
enable_creation_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.
|
||
|
||
[git-revision-date-localized support]: https://github.com/squidfunk/mkdocs-material/releases/tag/4.6.0
|
||
[git-revision-date-localized]: https://github.com/timvink/mkdocs-git-revision-date-localized-plugin
|
||
[enable_creation_date support]: https://github.com/squidfunk/mkdocs-material/releases/tag/7.1.4
|