mirror of
https://github.com/squidfunk/mkdocs-material.git
synced 2024-11-23 23:21:00 +01:00
Documentation
This commit is contained in:
squidfunk
parent
10a2b4faf8
commit
3cce3ea9b1
2
.github/workflows/documentation.yml
vendored
2
.github/workflows/documentation.yml
vendored
@ -48,6 +48,8 @@ jobs:
|
||||
run: |
|
||||
pip install .
|
||||
pip install \
|
||||
mkdocs-git-committers-plugin-2>=0.4 \
|
||||
mkdocs-git-revision-date-plugin>=0.3 \
|
||||
mkdocs-minify-plugin>=0.3 \
|
||||
mkdocs-redirects>=1.0 \
|
||||
mkdocs-rss-plugin>=0.17
|
||||
|
||||
@ -180,9 +180,10 @@ which are currently exclusively available to sponsors:
|
||||
|
||||
<div class="mdx-columns" markdown>
|
||||
|
||||
- [x] [Document contributors] :material-alert-decagram:{ .mdx-pulse title="Added on June 24, 2022" }
|
||||
- [x] [Automatic light / dark mode] :material-alert-decagram:{ .mdx-pulse title="Added on June 11, 2022" }
|
||||
- [x] [Content tabs: anchor links] :material-alert-decagram:{ .mdx-pulse title="Added on June 4, 2022" }
|
||||
- [x] [Navigation pruning] :material-alert-decagram:{ .mdx-pulse title="Added on May 25, 2022" }
|
||||
- [x] [Navigation pruning]
|
||||
- [x] [Tooltips]
|
||||
- [x] [Chinese search support]
|
||||
- [x] [Tag icons]
|
||||
@ -281,13 +282,14 @@ are released for general availability.
|
||||
- [x] [Tooltips]
|
||||
- [x] [Content tabs: anchor links]
|
||||
- [x] [Automatic light / dark mode]
|
||||
- [ ] Document authors/contributors
|
||||
- [x] [Document contributors]
|
||||
|
||||
[Privacy plugin]: ../setup/ensuring-data-privacy.md
|
||||
[Card grids]: ../reference/grids.md
|
||||
[Tooltips]: ../reference/tooltips.md
|
||||
[Content tabs: anchor links]: ../reference/content-tabs.md#anchor-links
|
||||
[Automatic light / dark mode]: ../setup/changing-the-colors.md#automatic-light-dark-mode
|
||||
[Document contributors]: ../setup/adding-a-git-repository.md#document-contributors
|
||||
|
||||
#### $ 16,000 – Chipotle
|
||||
|
||||
|
||||
@ -42,6 +42,12 @@
|
||||
"external": {
|
||||
"description": "External plugins, schema provided by us",
|
||||
"oneOf": [
|
||||
{
|
||||
"$ref": "plugins/external/git-authors.json"
|
||||
},
|
||||
{
|
||||
"$ref": "plugins/external/git-committers.json"
|
||||
},
|
||||
{
|
||||
"$ref": "plugins/external/git-revision-date.json"
|
||||
},
|
||||
|
||||
39
docs/schema/plugins/external/git-authors.json
vendored
Normal file
39
docs/schema/plugins/external/git-authors.json
vendored
Normal file
@ -0,0 +1,39 @@
|
||||
{
|
||||
"$schema": "https://json-schema.org/draft-07/schema",
|
||||
"title": "Git authors plugin",
|
||||
"oneOf": [
|
||||
{
|
||||
"markdownDescription": "https://timvink.github.io/mkdocs-git-authors-plugin/",
|
||||
"enum": [
|
||||
"git-authors"
|
||||
]
|
||||
},
|
||||
{
|
||||
"type": "object",
|
||||
"properties": {
|
||||
"git-authors": {
|
||||
"markdownDescription": "https://timvink.github.io/mkdocs-git-authors-plugin/options.html",
|
||||
"type": "object",
|
||||
"properties": {
|
||||
"enabled": {
|
||||
"title": "Enable plugin",
|
||||
"markdownDescription": "https://timvink.github.io/mkdocs-git-authors-plugin/options.html#enabled",
|
||||
"type": "boolean",
|
||||
"default": true
|
||||
},
|
||||
"exclude": {
|
||||
"title": "List of Markdown file patterns",
|
||||
"markdownDescription": "https://timvink.github.io/mkdocs-git-authors-plugin/options.html#exclude",
|
||||
"type": "array",
|
||||
"items": {
|
||||
"pattern": "(\\*|\\.md)$"
|
||||
}
|
||||
}
|
||||
},
|
||||
"additionalProperties": false
|
||||
}
|
||||
},
|
||||
"additionalProperties": false
|
||||
}
|
||||
]
|
||||
}
|
||||
44
docs/schema/plugins/external/git-committers.json
vendored
Normal file
44
docs/schema/plugins/external/git-committers.json
vendored
Normal file
@ -0,0 +1,44 @@
|
||||
{
|
||||
"$schema": "https://json-schema.org/draft-07/schema",
|
||||
"title": "Git committers plugin",
|
||||
"oneOf": [
|
||||
{
|
||||
"markdownDescription": "https://github.com/ojacques/mkdocs-git-committers-plugin-2",
|
||||
"enum": [
|
||||
"git-committers"
|
||||
]
|
||||
},
|
||||
{
|
||||
"type": "object",
|
||||
"properties": {
|
||||
"git-authors": {
|
||||
"markdownDescription": "https://github.com/ojacques/mkdocs-git-committers-plugin-2",
|
||||
"type": "object",
|
||||
"properties": {
|
||||
"enabled": {
|
||||
"title": "Enable plugin",
|
||||
"markdownDescription": "https://github.com/ojacques/mkdocs-git-committers-plugin-2#config",
|
||||
"type": "boolean",
|
||||
"default": true
|
||||
},
|
||||
"repository": {
|
||||
"title": "Repository slug",
|
||||
"markdownDescription": "https://github.com/ojacques/mkdocs-git-committers-plugin-2#config",
|
||||
"type": "string"
|
||||
},
|
||||
"token": {
|
||||
"title": "Personal access token",
|
||||
"markdownDescription": "https://github.com/ojacques/mkdocs-git-committers-plugin-2#config",
|
||||
"type": "string"
|
||||
}
|
||||
},
|
||||
"additionalProperties": false,
|
||||
"required": [
|
||||
"repository"
|
||||
]
|
||||
}
|
||||
},
|
||||
"additionalProperties": false
|
||||
}
|
||||
]
|
||||
}
|
||||
@ -6,8 +6,8 @@ template: overrides/main.html
|
||||
|
||||
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.
|
||||
static site, including stars and forks. Furthermore, the
|
||||
[date of last update and creation], as well as [contributors] can be shown.
|
||||
|
||||
## Configuration
|
||||
|
||||
@ -34,7 +34,7 @@ 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
|
||||
pre-release) for the latest tag you want to display next to the number of
|
||||
stars and forks.
|
||||
|
||||
[repo_url support]: https://github.com/squidfunk/mkdocs-material/releases/tag/0.1.0
|
||||
@ -42,7 +42,7 @@ GitHub repositories also include the tag of the latest release.[^1]
|
||||
[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
|
||||
#### Repository name
|
||||
|
||||
[:octicons-tag-24: 0.1.0][repo_name support] ·
|
||||
:octicons-milestone-24: Default: _automatically set to_ `GitHub`, `GitLab` _or_
|
||||
@ -59,7 +59,7 @@ 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
|
||||
#### Repository icon
|
||||
|
||||
[:octicons-tag-24: 5.0.0][icon.repo support] ·
|
||||
:octicons-milestone-24: Default:
|
||||
@ -103,7 +103,7 @@ Some popular choices:
|
||||
[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
|
||||
#### Edit button
|
||||
|
||||
[:octicons-tag-24: 0.1.0][edit_uri support] ·
|
||||
:octicons-milestone-24: Default: _automatically set_
|
||||
@ -130,65 +130,35 @@ changed by setting [`edit_uri`][edit_uri] in `mkdocs.yml`:
|
||||
[GitLab]: https://about.gitlab.com/
|
||||
[Bitbucket]: https://bitbucket.org/
|
||||
|
||||
### Revision date
|
||||
### Revisioning
|
||||
|
||||
[:octicons-tag-24: 4.6.0][git-revision-date support] ·
|
||||
[:octicons-cpu-24: Plugin][git-revision-date]
|
||||
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.
|
||||
|
||||
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
|
||||
[date of last update and creation]: #document-dates
|
||||
[contributors]: #document-contributors
|
||||
[authors]: #document-authors
|
||||
|
||||
#### Document dates
|
||||
|
||||
[:octicons-tag-24: 4.6.0][git-revision-date-localized support] ·
|
||||
[:octicons-cpu-24: Plugin][git-revision-date-localized]
|
||||
|
||||
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-plugin
|
||||
pip install mkdocs-git-revision-date-localized-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
|
||||
- git-revision-date-localized:
|
||||
enable_creation_date: true
|
||||
```
|
||||
|
||||
The following configuration options are supported:
|
||||
@ -205,18 +175,6 @@ The following configuration options are supported:
|
||||
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] ·
|
||||
@ -230,6 +188,17 @@ The following configuration options are supported:
|
||||
enable_creation_date: true
|
||||
```
|
||||
|
||||
`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
|
||||
```
|
||||
|
||||
The other configuration options of this extension are not officially supported
|
||||
by Material for MkDocs, which is why they may yield unexpected results. Use
|
||||
@ -238,3 +207,97 @@ 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
|
||||
|
||||
#### Document contributors :material-alert-decagram:{ .mdx-pulse title="Added on June 24, 2022" }
|
||||
|
||||
[:octicons-heart-fill-24:{ .mdx-heart } Sponsors only][Insiders]{ .mdx-insiders } ·
|
||||
[:octicons-tag-24: insiders-4.19.0][Insiders] ·
|
||||
[:octicons-cpu-24: Plugin][git-committers] ·
|
||||
:octicons-beaker-24: Experimental
|
||||
|
||||
The [git-committers][^2] 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`:
|
||||
|
||||
[^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.
|
||||
|
||||
```
|
||||
pip install mkdocs-git-committers-plugin-2
|
||||
```
|
||||
|
||||
Then, add the following lines to `mkdocs.yml`:
|
||||
|
||||
``` yaml
|
||||
plugins:
|
||||
- git-committers:
|
||||
repository: squidfunk/mkdocs-material
|
||||
token: !ENV GH_TOKEN
|
||||
```
|
||||
|
||||
The following configuration options are supported:
|
||||
|
||||
`repository`{ #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>`:
|
||||
|
||||
``` yaml
|
||||
plugins:
|
||||
- git-committers:
|
||||
repository: squidfunk/mkdocs-material
|
||||
```
|
||||
|
||||
`token`{ #committers-repository }
|
||||
|
||||
: :octicons-milestone-24: Default: _none_ – This property should[^3] be set to
|
||||
a [personal access token], which is used by the plugin to query GitHub's API
|
||||
for document contributor 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.
|
||||
|
||||
``` yaml
|
||||
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.
|
||||
|
||||
[Insiders]: ../insiders/index.md
|
||||
[git-committers]: https://github.com/ojacques/mkdocs-git-committers-plugin-2
|
||||
[personal access token]: https://docs.github.com/en/github/authenticating-to-github/creating-a-personal-access-token
|
||||
[rate limits]: https://docs.github.com/en/rest/overview/resources-in-the-rest-api#rate-limiting
|
||||
|
||||
#### Document authors :material-alert-decagram:{ .mdx-pulse title="Added on June 24, 2022" }
|
||||
|
||||
[:octicons-heart-fill-24:{ .mdx-heart } Sponsors only][Insiders]{ .mdx-insiders } ·
|
||||
[:octicons-tag-24: insiders-4.19.0][Insiders] ·
|
||||
[:octicons-cpu-24: Plugin][git-authors] ·
|
||||
:octicons-beaker-24: 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`:
|
||||
|
||||
``` yaml
|
||||
plugins:
|
||||
- git-authors
|
||||
```
|
||||
|
||||
[git-authors]: https://github.com/timvink/mkdocs-git-authors-plugin/
|
||||
|
||||
@ -180,7 +180,7 @@ theme:
|
||||
[navigation.expand enabled]: ../assets/screenshots/navigation-expand.png
|
||||
[navigation.expand disabled]: ../assets/screenshots/navigation.png
|
||||
|
||||
### Navigation pruning :material-alert-decagram:{ .mdx-pulse title="Added on May 25, 2022" }
|
||||
### Navigation pruning
|
||||
|
||||
[:octicons-heart-fill-24:{ .mdx-heart } Sponsors only][Insiders]{ .mdx-insiders } ·
|
||||
[:octicons-tag-24: insiders-4.16.0][Insiders] ·
|
||||
|
||||
Loading…
Reference in New Issue
Block a user