Add AI documentation skills
This commit is contained in:
@@ -0,0 +1,113 @@
|
||||
# Adding a comment system
|
||||
|
||||
Material for MkDocs allows to easily add the third-party comment system of your
|
||||
choice to the footer of any page by using [theme extension]. As an example,
|
||||
we'll be integrating [Giscus], which is Open Source, free, and uses GitHub
|
||||
discussions as a backend.
|
||||
|
||||
[Giscus]: https://giscus.app/
|
||||
|
||||
## Customization
|
||||
|
||||
### Giscus integration
|
||||
|
||||
Before you can use [Giscus], you need to complete the following steps:
|
||||
|
||||
1. __Install the [Giscus GitHub App]__ and grant access to the repository
|
||||
that should host comments as GitHub discussions. Note that this can be a
|
||||
repository different from your documentation.
|
||||
2. __Visit [Giscus] and generate the snippet__ through their configuration tool
|
||||
to load the comment system. Copy the snippet for the next step. The
|
||||
resulting snippet should look similar to this:
|
||||
|
||||
``` html
|
||||
<script
|
||||
src="https://giscus.app/client.js"
|
||||
data-repo="<username>/<repository>"
|
||||
data-repo-id="..."
|
||||
data-category="..."
|
||||
data-category-id="..."
|
||||
data-mapping="pathname"
|
||||
data-reactions-enabled="1"
|
||||
data-emit-metadata="1"
|
||||
data-theme="light"
|
||||
data-lang="en"
|
||||
crossorigin="anonymous"
|
||||
async
|
||||
>
|
||||
</script>
|
||||
```
|
||||
|
||||
The [`comments.html`][comments] partial (empty by default) is the best place to
|
||||
add the snippet generated by [Giscus]. Follow the guide on [theme extension]
|
||||
and [override the `comments.html` partial][overriding partials] with:
|
||||
|
||||
``` html hl_lines="3"
|
||||
{% if page.meta.comments %}
|
||||
<h2 id="__comments">{{ lang.t("meta.comments") }}</h2>
|
||||
<!-- Insert generated snippet here -->
|
||||
|
||||
<!-- Synchronize Giscus theme with palette -->
|
||||
<script>
|
||||
var giscus = document.querySelector("script[src*=giscus]")
|
||||
|
||||
// Set palette on initial load
|
||||
var palette = __md_get("__palette")
|
||||
if (palette && typeof palette.color === "object") {
|
||||
var theme = palette.color.scheme === "slate"
|
||||
? "transparent_dark"
|
||||
: "light"
|
||||
|
||||
// Instruct Giscus to set theme
|
||||
giscus.setAttribute("data-theme", theme) // (1)!
|
||||
}
|
||||
|
||||
// Register event handlers after documented loaded
|
||||
document.addEventListener("DOMContentLoaded", function() {
|
||||
var ref = document.querySelector("[data-md-component=palette]")
|
||||
ref.addEventListener("change", function() {
|
||||
var palette = __md_get("__palette")
|
||||
if (palette && typeof palette.color === "object") {
|
||||
var theme = palette.color.scheme === "slate"
|
||||
? "transparent_dark"
|
||||
: "light"
|
||||
|
||||
// Instruct Giscus to change theme
|
||||
var frame = document.querySelector(".giscus-frame")
|
||||
frame.contentWindow.postMessage(
|
||||
{ giscus: { setConfig: { theme } } },
|
||||
"https://giscus.app"
|
||||
)
|
||||
}
|
||||
})
|
||||
})
|
||||
</script>
|
||||
{% endif %}
|
||||
```
|
||||
|
||||
1. This code block ensures that [Giscus] renders with a dark theme when the
|
||||
palette is set to `slate`. Note that multiple dark themes are available,
|
||||
so you can change it to your liking.
|
||||
|
||||
Replace the highlighted line with the snippet you generated with the [Giscus]
|
||||
configuration tool in the previous step. If you copied the snippet from above,
|
||||
you can enable comments on a page by setting the `comments` front matter
|
||||
property to `true`:
|
||||
|
||||
``` yaml
|
||||
---
|
||||
comments: true
|
||||
---
|
||||
|
||||
# Page title
|
||||
...
|
||||
```
|
||||
|
||||
If you wish to enable comments for an entire folder, you can use the
|
||||
[built-in meta plugin].
|
||||
|
||||
[Giscus GitHub App]: https://github.com/apps/giscus
|
||||
[theme extension]: ../customization.md#extending-the-theme
|
||||
[comments]: https://github.com/squidfunk/mkdocs-material/blob/master/src/templates/partials/comments.html
|
||||
[overriding partials]: ../customization.md#overriding-partials
|
||||
[built-in meta plugin]: ../plugins/meta.md
|
||||
@@ -0,0 +1,354 @@
|
||||
# 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
|
||||
|
||||
<!-- md:version 0.1.0 -->
|
||||
<!-- md: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
|
||||
latest release tag[^1], as well as the number of stars and forks, are
|
||||
automatically requested and rendered.
|
||||
|
||||
[^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. For GitLab, although it is possible to get a [list of tags
|
||||
sorted by update time], the [equivalent API endpoint] is used. So, make sure
|
||||
you also [create a release for GitLab repositories].
|
||||
|
||||
[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
|
||||
[list of tags sorted by update time]: https://docs.gitlab.com/ee/api/tags.html#list-project-repository-tags
|
||||
[equivalent API endpoint]: https://docs.gitlab.com/ee/api/releases/#get-the-latest-release
|
||||
[create a release for GitLab repositories]: https://docs.gitlab.com/ee/user/project/releases/#create-a-release
|
||||
|
||||
#### Repository name
|
||||
|
||||
<!-- md:version 0.1.0 -->
|
||||
<!-- md: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]: https://www.mkdocs.org/user-guide/configuration/#repo_name
|
||||
|
||||
#### Repository icon
|
||||
|
||||
<!-- md:version 5.0.0 -->
|
||||
<!-- md:default computed -->
|
||||
|
||||
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-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`
|
||||
|
||||
[icon search]: ../reference/icons-emojis.md#search
|
||||
|
||||
#### Code actions
|
||||
|
||||
<!-- md:version 9.0.0 -->
|
||||
<!-- md:feature -->
|
||||
|
||||
If the [repository URL] points to a valid [GitHub], [GitLab] or [Bitbucket]
|
||||
repository, [MkDocs] provides a setting called [`edit_uri`][edit_uri], which
|
||||
resolves to the subfolder where your documentation is hosted.
|
||||
|
||||
If your default branch is called `main`, change the setting to:
|
||||
|
||||
``` yaml
|
||||
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:
|
||||
|
||||
``` yaml
|
||||
theme:
|
||||
icon:
|
||||
edit: material/pencil # (1)!
|
||||
view: material/eye
|
||||
```
|
||||
|
||||
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="material pencil" />
|
||||
<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>
|
||||
|
||||
[repository URL]: #repository
|
||||
[GitHub]: https://github.com/
|
||||
[GitLab]: https://about.gitlab.com/
|
||||
[Bitbucket]: https://bitbucket.org/
|
||||
[MkDocs]: https://www.mkdocs.org
|
||||
[edit_uri]: https://www.mkdocs.org/user-guide/configuration/#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.
|
||||
|
||||
[date of last update and creation]: #document-dates
|
||||
[contributors]: #document-contributors
|
||||
[authors]: #document-authors
|
||||
|
||||
#### Document dates
|
||||
|
||||
<!-- md:version 4.6.0 -->
|
||||
<!-- md: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-localized-plugin
|
||||
```
|
||||
|
||||
Then, add the following lines to `mkdocs.yml`:
|
||||
|
||||
``` yaml
|
||||
plugins:
|
||||
- git-revision-date-localized:
|
||||
enable_creation_date: true
|
||||
```
|
||||
|
||||
The following configuration options are supported:
|
||||
|
||||
<!-- md:option git-revision-date-localized.enabled -->
|
||||
|
||||
: <!-- md: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]:
|
||||
|
||||
``` yaml
|
||||
plugins:
|
||||
- git-revision-date-localized:
|
||||
enabled: !ENV [CI, false]
|
||||
```
|
||||
|
||||
<!-- md:option git-revision-date-localized.type -->
|
||||
|
||||
: <!-- md: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
|
||||
```
|
||||
|
||||
<!-- md:option git-revision-date-localized.enable_creation_date -->
|
||||
|
||||
: <!-- md: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
|
||||
```
|
||||
|
||||
!!! note "When using build environments"
|
||||
|
||||
If you are deploying through a CI system, you might need to adjust your
|
||||
CI settings when fetching the code. For more information, see
|
||||
[git-revision-date-localized].
|
||||
|
||||
<!-- md:option git-revision-date-localized.fallback_to_build_date -->
|
||||
|
||||
: <!-- md: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
|
||||
them at your own risk.
|
||||
|
||||
[git-revision-date-localized]: https://github.com/timvink/mkdocs-git-revision-date-localized-plugin
|
||||
|
||||
#### Document contributors
|
||||
|
||||
<!-- md:version 9.5.0 -->
|
||||
<!-- md:plugin [git-committers] -->
|
||||
<!-- md:flag 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
|
||||
branch: main
|
||||
```
|
||||
|
||||
The following configuration options are supported:
|
||||
|
||||
<!-- md:option git-committers.enabled -->
|
||||
|
||||
: <!-- md: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]:
|
||||
|
||||
``` yaml
|
||||
plugins:
|
||||
- git-committers:
|
||||
enabled: !ENV [CI, false]
|
||||
```
|
||||
|
||||
<!-- md:option git-committers.repository -->
|
||||
|
||||
: <!-- md:default none --> <!-- md:flag 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
|
||||
```
|
||||
|
||||
<!-- md:option git-committers.branch -->
|
||||
|
||||
: <!-- md:default `master` --> This property should be set to
|
||||
the branch of the repository from which to retrieve the contributors. To use the `main` branch:
|
||||
|
||||
``` yaml
|
||||
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.
|
||||
|
||||
[git-committers]: https://github.com/ojacques/mkdocs-git-committers-plugin-2
|
||||
[environment variable]: https://www.mkdocs.org/user-guide/configuration/#environment-variables
|
||||
[rate limits]: https://docs.github.com/en/rest/overview/resources-in-the-rest-api#rate-limiting
|
||||
|
||||
#### Document authors
|
||||
|
||||
<!-- md:version 9.5.0 -->
|
||||
<!-- md:plugin [git-authors] -->
|
||||
<!-- md:flag 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.
|
||||
|
||||
Material for MkDocs offers deep integration for [git-authors]. This means the
|
||||
[customized overrides](https://timvink.github.io/mkdocs-git-authors-plugin/usage.html#mkdocs-material-theme)
|
||||
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`:
|
||||
|
||||
``` yaml
|
||||
plugins:
|
||||
- git-authors
|
||||
```
|
||||
|
||||
[git-authors]: https://github.com/timvink/mkdocs-git-authors-plugin/
|
||||
@@ -0,0 +1,106 @@
|
||||
# Building an optimized site
|
||||
|
||||
Material for MkDocs, by default, allows to build optimized sites that rank great
|
||||
on search engines, load fast (even on slow networks), and work perfectly without
|
||||
JavaScript. Additionally, the [built-in optimize plugin] adds support for
|
||||
further useful automatic optimization techniques.
|
||||
|
||||
[built-in optimize plugin]: #built-in-optimize-plugin
|
||||
|
||||
## Configuration
|
||||
|
||||
### Built-in projects plugin
|
||||
|
||||
<!-- md:version 9.7.0 -->
|
||||
<!-- md:plugin [projects] – built-in -->
|
||||
<!-- md:flag experimental -->
|
||||
|
||||
The built-in projects plugin allows to split your documentation into multiple
|
||||
distinct MkDocs projects, __build them concurrently__ and
|
||||
__serve them together__. Add the following to `mkdocs.yml`:
|
||||
|
||||
``` yaml
|
||||
plugins:
|
||||
- projects
|
||||
```
|
||||
|
||||
For a list of all settings, please consult the [plugin documentation].
|
||||
|
||||
[projects]: ../plugins/projects.md
|
||||
[plugin documentation]: ../plugins/projects.md
|
||||
|
||||
??? info "Use cases for the projects plugin"
|
||||
|
||||
Ideal use cases for the projects plugin are:
|
||||
|
||||
- Building a multi-language site
|
||||
- Building a blog alongside your documentation
|
||||
- Splitting large code bases for better performance
|
||||
|
||||
Note that the plugin is currently experimental. We're releasing it early,
|
||||
so that we can improve it together with our users and make it even more
|
||||
powerful as we discover new use cases.
|
||||
|
||||
#### Scope
|
||||
|
||||
<!-- md:version 8.0.0 -->
|
||||
<!-- md:default none -->
|
||||
|
||||
There might be a use case, where you want to share user-level settings like
|
||||
the selected [color palette], or [cookie consent] across all projects. To do
|
||||
so, add the following lines to `mkdocs.yml`:
|
||||
|
||||
``` yaml
|
||||
extra:
|
||||
scope: /
|
||||
```
|
||||
|
||||
!!! example "How it works"
|
||||
|
||||
Suppose you have this site structure:
|
||||
```
|
||||
.
|
||||
└── /
|
||||
├── subsite-a/
|
||||
├── subsite-b/
|
||||
└── subsite-c/
|
||||
```
|
||||
By default, each site will have its own scope (`/subsite-a/`, `/subsite-b/`,
|
||||
`/subsite-c/`). To modify this behaviour, add the following lines to
|
||||
`mkdocs.yml`:
|
||||
|
||||
``` yaml
|
||||
extra:
|
||||
scope: /
|
||||
```
|
||||
|
||||
By setting it to `/`, it should allow you to share the following preferences
|
||||
across the main site and all subsites:
|
||||
|
||||
- [Cookie consent][cookie consent]
|
||||
- [Linking of content tabs, i.e. active tab]
|
||||
- [Color palette][color palette]
|
||||
|
||||
[Scope support]: https://github.com/squidfunk/mkdocs-material/releases/tag/8.0.0
|
||||
[cookie consent]: ../setup/ensuring-data-privacy.md#cookie-consent
|
||||
[Linking of content tabs, i.e. active tab]: ../reference/content-tabs.md
|
||||
[color palette]: ../setup/changing-the-colors.md#color-palette
|
||||
|
||||
### Built-in optimize plugin
|
||||
|
||||
<!-- md:version 9.7.0 -->
|
||||
<!-- md:plugin [optimize] – built-in -->
|
||||
<!-- md:flag experimental -->
|
||||
|
||||
The built-in optimize plugin automatically identifies and optimizes all media
|
||||
files as part of the build using compression and conversion techniques. Add
|
||||
the following lines to `mkdocs.yml`:
|
||||
|
||||
``` yaml
|
||||
plugins:
|
||||
- optimize
|
||||
```
|
||||
|
||||
For a list of all settings, please consult the [plugin documentation][optimize].
|
||||
|
||||
[optimize]: ../plugins/optimize.md
|
||||
@@ -0,0 +1,55 @@
|
||||
# Building for offline usage
|
||||
|
||||
If you want to ship your documentation together with your product, MkDocs has
|
||||
you covered – with support from themes, [MkDocs] supports building
|
||||
offline-capable documentation. Notably, Material for MkDocs offers offline
|
||||
support for many of its features.
|
||||
|
||||
[MkDocs]: https://www.mkdocs.org
|
||||
|
||||
## Configuration
|
||||
|
||||
### Built-in offline plugin
|
||||
|
||||
<!-- md:version 9.0.0 -->
|
||||
<!-- md:plugin [offline] – built-in -->
|
||||
|
||||
The built-in offline plugin makes sure that the [site search] works when you
|
||||
distribute the contents of your [site directory] as a download. Simply add
|
||||
the following lines to `mkdocs.yml`:
|
||||
|
||||
``` yaml
|
||||
plugins:
|
||||
- offline
|
||||
```
|
||||
|
||||
For a list of all settings, please consult the [plugin documentation].
|
||||
|
||||
[offline]: ../plugins/offline.md
|
||||
[plugin documentation]: ../plugins/offline.md
|
||||
|
||||
!!! tip "Automatically bundle all external assets"
|
||||
|
||||
The [built-in privacy plugin] makes it easy to use external assets
|
||||
while building documentation for offline usage, as it will automatically
|
||||
download all external assets to distribute them with your documentation.
|
||||
|
||||
[site search]: setting-up-site-search.md
|
||||
[site directory]: https://www.mkdocs.org/user-guide/configuration/#site_dir
|
||||
[built-in privacy plugin]:../plugins/privacy.md
|
||||
|
||||
#### Limitations
|
||||
|
||||
Material for MkDocs offers many interactive features, some of which will not
|
||||
work from the file system due to the restrictions of modern browsers: all
|
||||
features that use the `fetch` API will error.
|
||||
|
||||
Thus, when building for offline usage, make sure to disable the following
|
||||
configuration settings: [instant loading], [site analytics], [git repository],
|
||||
[versioning] and [comment systems].
|
||||
|
||||
[Instant loading]: setting-up-navigation.md#instant-loading
|
||||
[Site analytics]: setting-up-site-analytics.md
|
||||
[Versioning]: setting-up-versioning.md
|
||||
[Git repository]: adding-a-git-repository.md
|
||||
[Comment systems]: adding-a-comment-system.md
|
||||
@@ -0,0 +1,401 @@
|
||||
# Changing the colors
|
||||
|
||||
As any proper Material Design implementation, Material for MkDocs supports
|
||||
Google's original [color palette], which can be easily configured through
|
||||
`mkdocs.yml`. Furthermore, colors can be customized with a few lines of CSS to
|
||||
fit your brand's identity by using [CSS variables][custom colors].
|
||||
|
||||
[color palette]: http://www.materialui.co/colors
|
||||
[custom colors]: #custom-colors
|
||||
|
||||
## Configuration
|
||||
|
||||
### Color palette
|
||||
|
||||
#### Color scheme
|
||||
|
||||
<!-- md:version 5.2.0 -->
|
||||
<!-- md:default `default` -->
|
||||
|
||||
Material for MkDocs supports two color schemes: a __light mode__, which is just
|
||||
called `default`, and a __dark mode__, which is called `slate`. The color scheme
|
||||
can be set via `mkdocs.yml`:
|
||||
|
||||
``` yaml
|
||||
theme:
|
||||
palette:
|
||||
scheme: default
|
||||
```
|
||||
|
||||
Click on a tile to change the color scheme:
|
||||
|
||||
<div class="mdx-switch">
|
||||
<button data-md-color-scheme="default"><code>default</code></button>
|
||||
<button data-md-color-scheme="slate"><code>slate</code></button>
|
||||
</div>
|
||||
|
||||
<script>
|
||||
var buttons = document.querySelectorAll("button[data-md-color-scheme]")
|
||||
buttons.forEach(function(button) {
|
||||
button.addEventListener("click", function() {
|
||||
document.body.setAttribute("data-md-color-switching", "")
|
||||
var attr = this.getAttribute("data-md-color-scheme")
|
||||
document.body.setAttribute("data-md-color-scheme", attr)
|
||||
var name = document.querySelector("#__code_0 code span.l")
|
||||
name.textContent = attr
|
||||
setTimeout(function() {
|
||||
document.body.removeAttribute("data-md-color-switching")
|
||||
})
|
||||
})
|
||||
})
|
||||
</script>
|
||||
|
||||
#### Primary color
|
||||
|
||||
<!-- md:version 0.2.0 -->
|
||||
<!-- md:default `indigo` -->
|
||||
|
||||
The primary color is used for the header, the sidebar, text links and several
|
||||
other components. In order to change the primary color, set the following value
|
||||
in `mkdocs.yml` to a valid color name:
|
||||
|
||||
``` yaml
|
||||
theme:
|
||||
palette:
|
||||
primary: indigo
|
||||
```
|
||||
|
||||
Click on a tile to change the primary color:
|
||||
|
||||
<div class="mdx-switch">
|
||||
<button data-md-color-primary="red"><code>red</code></button>
|
||||
<button data-md-color-primary="pink"><code>pink</code></button>
|
||||
<button data-md-color-primary="purple"><code>purple</code></button>
|
||||
<button data-md-color-primary="deep-purple"><code>deep purple</code></button>
|
||||
<button data-md-color-primary="indigo"><code>indigo</code></button>
|
||||
<button data-md-color-primary="blue"><code>blue</code></button>
|
||||
<button data-md-color-primary="light-blue"><code>light blue</code></button>
|
||||
<button data-md-color-primary="cyan"><code>cyan</code></button>
|
||||
<button data-md-color-primary="teal"><code>teal</code></button>
|
||||
<button data-md-color-primary="green"><code>green</code></button>
|
||||
<button data-md-color-primary="light-green"><code>light green</code></button>
|
||||
<button data-md-color-primary="lime"><code>lime</code></button>
|
||||
<button data-md-color-primary="yellow"><code>yellow</code></button>
|
||||
<button data-md-color-primary="amber"><code>amber</code></button>
|
||||
<button data-md-color-primary="orange"><code>orange</code></button>
|
||||
<button data-md-color-primary="deep-orange"><code>deep orange</code></button>
|
||||
<button data-md-color-primary="brown"><code>brown</code></button>
|
||||
<button data-md-color-primary="grey"><code>grey</code></button>
|
||||
<button data-md-color-primary="blue-grey"><code>blue grey</code></button>
|
||||
<button data-md-color-primary="black"><code>black</code></button>
|
||||
<button data-md-color-primary="white"><code>white</code></button>
|
||||
</div>
|
||||
|
||||
<script>
|
||||
var buttons = document.querySelectorAll("button[data-md-color-primary]")
|
||||
buttons.forEach(function(button) {
|
||||
button.addEventListener("click", function() {
|
||||
var attr = this.getAttribute("data-md-color-primary")
|
||||
document.body.setAttribute("data-md-color-primary", attr)
|
||||
var name = document.querySelector("#__code_1 code span.l")
|
||||
name.textContent = attr.replace("-", " ")
|
||||
})
|
||||
})
|
||||
</script>
|
||||
|
||||
See our guide below to learn how to set [custom colors].
|
||||
|
||||
#### Accent color
|
||||
|
||||
<!-- md:version 0.2.0 -->
|
||||
<!-- md:default `indigo` -->
|
||||
|
||||
The accent color is used to denote elements that can be interacted with, e.g.
|
||||
hovered links, buttons and scrollbars. It can be changed in `mkdocs.yml` by
|
||||
choosing a valid color name:
|
||||
|
||||
``` yaml
|
||||
theme:
|
||||
palette:
|
||||
accent: indigo
|
||||
```
|
||||
|
||||
Click on a tile to change the accent color:
|
||||
|
||||
<style>
|
||||
.md-typeset button[data-md-color-accent] > code {
|
||||
background-color: var(--md-code-bg-color);
|
||||
color: var(--md-accent-fg-color);
|
||||
}
|
||||
</style>
|
||||
|
||||
<div class="mdx-switch">
|
||||
<button data-md-color-accent="red"><code>red</code></button>
|
||||
<button data-md-color-accent="pink"><code>pink</code></button>
|
||||
<button data-md-color-accent="purple"><code>purple</code></button>
|
||||
<button data-md-color-accent="deep-purple"><code>deep purple</code></button>
|
||||
<button data-md-color-accent="indigo"><code>indigo</code></button>
|
||||
<button data-md-color-accent="blue"><code>blue</code></button>
|
||||
<button data-md-color-accent="light-blue"><code>light blue</code></button>
|
||||
<button data-md-color-accent="cyan"><code>cyan</code></button>
|
||||
<button data-md-color-accent="teal"><code>teal</code></button>
|
||||
<button data-md-color-accent="green"><code>green</code></button>
|
||||
<button data-md-color-accent="light-green"><code>light green</code></button>
|
||||
<button data-md-color-accent="lime"><code>lime</code></button>
|
||||
<button data-md-color-accent="yellow"><code>yellow</code></button>
|
||||
<button data-md-color-accent="amber"><code>amber</code></button>
|
||||
<button data-md-color-accent="orange"><code>orange</code></button>
|
||||
<button data-md-color-accent="deep-orange"><code>deep orange</code></button>
|
||||
</div>
|
||||
|
||||
<script>
|
||||
var buttons = document.querySelectorAll("button[data-md-color-accent]")
|
||||
buttons.forEach(function(button) {
|
||||
button.addEventListener("click", function() {
|
||||
var attr = this.getAttribute("data-md-color-accent")
|
||||
document.body.setAttribute("data-md-color-accent", attr)
|
||||
var name = document.querySelector("#__code_2 code span.l")
|
||||
name.textContent = attr.replace("-", " ")
|
||||
})
|
||||
})
|
||||
</script>
|
||||
|
||||
See our guide below to learn how to set [custom colors].
|
||||
|
||||
### Color palette toggle
|
||||
|
||||
<!-- md:version 7.1.0 -->
|
||||
<!-- md:default none -->
|
||||
<!-- md:example color-palette-toggle -->
|
||||
|
||||
Offering a light _and_ dark color palette makes your documentation pleasant to
|
||||
read at different times of the day, so the user can choose accordingly. Add the
|
||||
following lines to `mkdocs.yml`:
|
||||
|
||||
``` yaml
|
||||
theme:
|
||||
palette: # (1)!
|
||||
|
||||
# Palette toggle for light mode
|
||||
- scheme: default
|
||||
toggle:
|
||||
icon: material/brightness-7 # (2)!
|
||||
name: Switch to dark mode
|
||||
|
||||
# Palette toggle for dark mode
|
||||
- scheme: slate
|
||||
toggle:
|
||||
icon: material/brightness-4
|
||||
name: Switch to light mode
|
||||
```
|
||||
|
||||
1. Note that the `theme.palette` setting is now defined as a list.
|
||||
|
||||
2. 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="brightness" />
|
||||
<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>
|
||||
|
||||
This configuration will render a color palette toggle next to the search bar.
|
||||
Note that you can also define separate settings for [`primary`][palette.primary]
|
||||
and [`accent`][palette.accent] per color palette.
|
||||
|
||||
The following properties must be set for each toggle:
|
||||
|
||||
<!-- md:option palette.toggle.icon -->
|
||||
|
||||
: <!-- md:default none --> <!-- md:flag required -->
|
||||
This property must point to a valid icon path referencing any icon bundled
|
||||
with the theme, or the build will not succeed. Some popular combinations:
|
||||
|
||||
* :material-brightness-7: + :material-brightness-4: – `material/brightness-7` + `material/brightness-4`
|
||||
* :material-toggle-switch: + :material-toggle-switch-off-outline: – `material/toggle-switch` + `material/toggle-switch-off-outline`
|
||||
* :material-weather-night: + :material-weather-sunny: – `material/weather-night` + `material/weather-sunny`
|
||||
* :material-eye: + :material-eye-outline: – `material/eye` + `material/eye-outline`
|
||||
* :material-lightbulb: + :material-lightbulb-outline: – `material/lightbulb` + `material/lightbulb-outline`
|
||||
|
||||
<!-- md:option palette.toggle.name -->
|
||||
|
||||
: <!-- md:default none --> <!-- md:flag required -->
|
||||
This property is used as the toggle's `title` attribute and should be set to
|
||||
a discernable name to improve accessibility. It's rendered as a [tooltip].
|
||||
|
||||
[palette.scheme]: #color-scheme
|
||||
[palette.primary]: #primary-color
|
||||
[palette.accent]: #accent-color
|
||||
[icon search]: ../reference/icons-emojis.md#search
|
||||
[tooltip]: ../reference/tooltips.md
|
||||
|
||||
### System preference
|
||||
|
||||
<!-- md:version 7.1.0 -->
|
||||
<!-- md:default none -->
|
||||
<!-- md:example color-palette-system-preference -->
|
||||
|
||||
Each color palette can be linked to the user's system preference for light and
|
||||
dark appearance by using a media query. Simply add a `media` property next to
|
||||
the `scheme` definition in `mkdocs.yml`:
|
||||
|
||||
``` yaml
|
||||
theme:
|
||||
palette:
|
||||
|
||||
# Palette toggle for light mode
|
||||
- media: "(prefers-color-scheme: light)"
|
||||
scheme: default
|
||||
toggle:
|
||||
icon: material/brightness-7
|
||||
name: Switch to dark mode
|
||||
|
||||
# Palette toggle for dark mode
|
||||
- media: "(prefers-color-scheme: dark)"
|
||||
scheme: slate
|
||||
toggle:
|
||||
icon: material/brightness-4
|
||||
name: Switch to light mode
|
||||
```
|
||||
|
||||
When the user first visits your site, the media queries are evaluated in the
|
||||
order of their definition. The first media query that matches selects the
|
||||
default color palette.
|
||||
|
||||
#### Automatic light / dark mode
|
||||
|
||||
<!-- md:version 9.5.0 -->
|
||||
<!-- md:flag experimental -->
|
||||
<!-- md:example color-palette-system-preference -->
|
||||
|
||||
Newer operating systems allow to automatically switch between light and dark
|
||||
appearance during day and night times. Material for MkDocs adds support for
|
||||
automatic light / dark mode, delegating color palette selection to the user's
|
||||
operating system. Add the following lines to `mkdocs.yml`:
|
||||
|
||||
``` yaml
|
||||
theme:
|
||||
palette:
|
||||
|
||||
# Palette toggle for automatic mode
|
||||
- media: "(prefers-color-scheme)"
|
||||
toggle:
|
||||
icon: material/brightness-auto
|
||||
name: Switch to light mode
|
||||
|
||||
# Palette toggle for light mode
|
||||
- media: "(prefers-color-scheme: light)"
|
||||
scheme: default # (1)!
|
||||
toggle:
|
||||
icon: material/brightness-7
|
||||
name: Switch to dark mode
|
||||
|
||||
# Palette toggle for dark mode
|
||||
- media: "(prefers-color-scheme: dark)"
|
||||
scheme: slate
|
||||
toggle:
|
||||
icon: material/brightness-4
|
||||
name: Switch to system preference
|
||||
```
|
||||
|
||||
1. You can also define separate settings for [`primary`][palette.primary] and
|
||||
[`accent`][palette.accent] per color palette, i.e. different colors for
|
||||
light and dark mode.
|
||||
|
||||
Material for MkDocs will now change the color palette each time the operating
|
||||
system switches between light and dark appearance, even when the user doesn't
|
||||
reload the site.
|
||||
|
||||
## Customization
|
||||
|
||||
### Custom colors
|
||||
|
||||
<!-- md:version 5.0.0 -->
|
||||
<!-- md:example custom-colors -->
|
||||
|
||||
Material for MkDocs implements colors using [CSS variables] (custom
|
||||
properties). If you want to customize the colors beyond the palette (e.g. to
|
||||
use your brand-specific colors), you can add an [additional style sheet] and
|
||||
tweak the values of the CSS variables.
|
||||
|
||||
First, set the [`primary`][palette.primary] or [`accent`][palette.accent] values
|
||||
in `mkdocs.yml` to `custom`, to signal to the theme that you want to define
|
||||
custom colors, e.g., when you want to override the `primary` color:
|
||||
|
||||
``` yaml
|
||||
theme:
|
||||
palette:
|
||||
primary: custom
|
||||
```
|
||||
|
||||
Let's say you're :fontawesome-brands-youtube:{ style="color: #EE0F0F" }
|
||||
__YouTube__, and want to set the primary color to your brand's palette. Just
|
||||
add:
|
||||
|
||||
=== ":octicons-file-code-16: `docs/stylesheets/extra.css`"
|
||||
|
||||
``` css
|
||||
:root > * {
|
||||
--md-primary-fg-color: #EE0F0F;
|
||||
--md-primary-fg-color--light: #ECB7B7;
|
||||
--md-primary-fg-color--dark: #90030C;
|
||||
}
|
||||
```
|
||||
|
||||
=== ":octicons-file-code-16: `mkdocs.yml`"
|
||||
|
||||
``` yaml
|
||||
extra_css:
|
||||
- stylesheets/extra.css
|
||||
```
|
||||
|
||||
See the file containing the [color definitions] for a list of all CSS variables.
|
||||
|
||||
[CSS variables]: https://developer.mozilla.org/en-US/docs/Web/CSS/Using_CSS_custom_properties
|
||||
[color definitions]: https://github.com/squidfunk/mkdocs-material/blob/master/src/templates/assets/stylesheets/main/_colors.scss
|
||||
[additional style sheet]: ../customization.md#additional-css
|
||||
|
||||
|
||||
### Custom color schemes
|
||||
|
||||
Besides overriding specific colors, you can create your own, named color scheme
|
||||
by wrapping the definitions in a `[data-md-color-scheme="..."]`
|
||||
[attribute selector], which you can then set via `mkdocs.yml` as described
|
||||
in the [color schemes][palette.scheme] section:
|
||||
|
||||
=== ":octicons-file-code-16: `docs/stylesheets/extra.css`"
|
||||
|
||||
``` css
|
||||
[data-md-color-scheme="youtube"] {
|
||||
--md-primary-fg-color: #EE0F0F;
|
||||
--md-primary-fg-color--light: #ECB7B7;
|
||||
--md-primary-fg-color--dark: #90030C;
|
||||
}
|
||||
```
|
||||
|
||||
=== ":octicons-file-code-16: `mkdocs.yml`"
|
||||
|
||||
``` yaml
|
||||
theme:
|
||||
palette:
|
||||
scheme: youtube
|
||||
extra_css:
|
||||
- stylesheets/extra.css
|
||||
```
|
||||
|
||||
Additionally, the `slate` color scheme defines all of it's colors via `hsla`
|
||||
color functions and deduces its colors from the `--md-hue` CSS variable. You
|
||||
can tune the `slate` theme with:
|
||||
|
||||
``` css
|
||||
[data-md-color-scheme="slate"] {
|
||||
--md-hue: 210; /* (1)! */
|
||||
}
|
||||
```
|
||||
|
||||
1. The `hue` value must be in the range of `[0, 360]`
|
||||
|
||||
[attribute selector]: https://www.w3.org/TR/selectors-4/#attribute-selectors
|
||||
@@ -0,0 +1,119 @@
|
||||
# Changing the fonts
|
||||
|
||||
Material for MkDocs makes it easy to change the typeface of your project
|
||||
documentation, as it directly integrates with [Google Fonts]. Alternatively,
|
||||
fonts can be custom-loaded if self-hosting is preferred for data privacy reasons
|
||||
or another destination should be used.
|
||||
|
||||
[Google Fonts]: https://fonts.google.com
|
||||
|
||||
## Configuration
|
||||
|
||||
### Regular font
|
||||
|
||||
<!-- md:version 0.1.2 -->
|
||||
<!-- md:default [`Roboto`][Roboto] -->
|
||||
|
||||
The regular font is used for all body copy, headlines, and essentially
|
||||
everything that does not need to be monospaced. It can be set to any
|
||||
valid [Google Font][Google Fonts] via `mkdocs.yml`:
|
||||
|
||||
``` yaml
|
||||
theme:
|
||||
font:
|
||||
text: Roboto
|
||||
```
|
||||
|
||||
The typeface will be loaded in 300, 400, _400i_ and __700__.
|
||||
|
||||
[Roboto]: https://fonts.google.com/specimen/Roboto
|
||||
|
||||
### Monospaced font
|
||||
|
||||
<!-- md:version 0.1.2 -->
|
||||
<!-- md:default [`Roboto Mono`][Roboto Mono] -->
|
||||
|
||||
The _monospaced font_ is used for code blocks and can be configured separately.
|
||||
Just like the regular font, it can be set to any valid [Google Font]
|
||||
[Google Fonts] via `mkdocs.yml`:
|
||||
|
||||
``` yaml
|
||||
theme:
|
||||
font:
|
||||
code: Roboto Mono
|
||||
```
|
||||
|
||||
The typeface will be loaded in 400.
|
||||
|
||||
[Roboto Mono]: https://fonts.google.com/specimen/Roboto+Mono
|
||||
|
||||
### Autoloading
|
||||
|
||||
<!-- md:version 1.0.0 -->
|
||||
<!-- md:default none -->
|
||||
|
||||
If you want to prevent typefaces from being loaded from [Google Fonts], e.g.
|
||||
to adhere to [data privacy] regulations, and fall back to system fonts, add the
|
||||
following lines to `mkdocs.yml`:
|
||||
|
||||
``` yaml
|
||||
theme:
|
||||
font: false
|
||||
```
|
||||
|
||||
!!! tip "Automatically bundle Google Fonts"
|
||||
|
||||
The [built-in privacy plugin] makes it easy to use Google Fonts
|
||||
while complying with the __General Data Protection Regulation__ (GDPR),
|
||||
by automatically downloading and self-hosting the web font files.
|
||||
|
||||
[data privacy]: https://developers.google.com/fonts/faq/privacy
|
||||
[built-in privacy plugin]:../plugins/privacy.md
|
||||
|
||||
## Customization
|
||||
|
||||
### Additional fonts
|
||||
|
||||
If you want to load an (additional) font from another destination or override
|
||||
the system font, you can use an [additional style sheet] to add the
|
||||
corresponding `@font-face` definition:
|
||||
|
||||
=== ":octicons-file-code-16: `docs/stylesheets/extra.css`"
|
||||
|
||||
``` css
|
||||
@font-face {
|
||||
font-family: "<font>";
|
||||
src: "...";
|
||||
}
|
||||
```
|
||||
|
||||
=== ":octicons-file-code-16: `mkdocs.yml`"
|
||||
|
||||
``` yaml
|
||||
extra_css:
|
||||
- stylesheets/extra.css
|
||||
```
|
||||
|
||||
The font can then be applied to specific elements, e.g. only headlines, or
|
||||
globally to be used as the site-wide regular or monospaced font:
|
||||
|
||||
=== "Regular font"
|
||||
|
||||
``` css
|
||||
:root {
|
||||
--md-text-font: "<font>"; /* (1)! */
|
||||
}
|
||||
```
|
||||
|
||||
1. Always define fonts through CSS variables and not `font-family`, as
|
||||
this would disable the system font fallback.
|
||||
|
||||
=== "Monospaced font"
|
||||
|
||||
``` css
|
||||
:root {
|
||||
--md-code-font: "<font>";
|
||||
}
|
||||
```
|
||||
|
||||
[additional style sheet]: ../customization.md#additional-css
|
||||
@@ -0,0 +1,184 @@
|
||||
# Changing the language
|
||||
|
||||
Material for MkDocs supports internationalization (i18n) and provides
|
||||
translations for template variables and labels in 60+ languages. Additionally,
|
||||
the site search can be configured to use a language-specific stemmer, if
|
||||
available.
|
||||
|
||||
## Configuration
|
||||
|
||||
### Site language
|
||||
|
||||
<!-- md:version 1.12.0 -->
|
||||
<!-- md:default `en` -->
|
||||
|
||||
You can set the site language in `mkdocs.yml` with:
|
||||
|
||||
``` yaml
|
||||
theme:
|
||||
language: en # (1)!
|
||||
```
|
||||
|
||||
1. HTML5 only allows to set a [single language per document], which is why
|
||||
Material for MkDocs only supports setting a canonical language for the
|
||||
entire project, i.e. one per `mkdocs.yml`.
|
||||
|
||||
The easiest way to build a multi-language documentation is to create one
|
||||
project in a subfolder per language, and then use the [language selector]
|
||||
to interlink those projects.
|
||||
|
||||
The following languages are supported:
|
||||
|
||||
<!-- hooks/translations.py -->
|
||||
|
||||
Note that some languages will produce unreadable anchor links due to the way
|
||||
the default slug function works. Consider using a [Unicode-aware slug function].
|
||||
|
||||
[single language per document]: https://www.w3.org/International/questions/qa-html-language-declarations.en#attributes
|
||||
[language selector]: #site-language-selector
|
||||
[Unicode-aware slug function]: extensions/python-markdown.md#+toc.slugify
|
||||
|
||||
### Site language selector
|
||||
|
||||
<!-- md:version 7.0.0 -->
|
||||
<!-- md:default none -->
|
||||
|
||||
If your documentation is available in multiple languages, a language selector
|
||||
pointing to those languages can be added to the header. Alternate languages
|
||||
can be defined via `mkdocs.yml`.
|
||||
|
||||
``` yaml
|
||||
extra:
|
||||
alternate:
|
||||
- name: English
|
||||
link: /en/ # (1)!
|
||||
lang: en
|
||||
- name: Deutsch
|
||||
link: /de/
|
||||
lang: de
|
||||
```
|
||||
|
||||
1. Note that this must be an absolute link. If it includes a domain part, it's
|
||||
used as defined. Otherwise the domain part of the [`site_url`][site_url] as
|
||||
set in `mkdocs.yml` is prepended to the link.
|
||||
|
||||
The following properties are available for each alternate language:
|
||||
|
||||
<!-- md:option alternate.name -->
|
||||
|
||||
: <!-- md:default none --> <!-- md:flag required -->
|
||||
This value of this property is used inside the language selector as the
|
||||
name of the language and must be set to a non-empty string.
|
||||
|
||||
<!-- md:option alternate.link -->
|
||||
|
||||
: <!-- md:default none --> <!-- md:flag required -->
|
||||
This property must be set to an absolute link, which might also point to
|
||||
another domain or subdomain not necessarily generated with MkDocs.
|
||||
|
||||
<!-- md:option alternate.lang -->
|
||||
|
||||
: <!-- md:default none --> <!-- md:flag required -->
|
||||
This property must contain an [ISO 639-1 language code] and is used for
|
||||
the `hreflang` attribute of the link, improving discoverability via search
|
||||
engines.
|
||||
|
||||
[![Language selector preview]][Language selector preview]
|
||||
|
||||
[site_url]: https://www.mkdocs.org/user-guide/configuration/#site_url
|
||||
[ISO 639-1 language code]: https://en.wikipedia.org/wiki/List_of_ISO_639-1_codes
|
||||
[Language selector preview]: ../assets/screenshots/language-selection.png
|
||||
|
||||
#### Stay on page
|
||||
|
||||
<!-- md:version 9.7.0 -->
|
||||
<!-- md:flag experimental -->
|
||||
|
||||
When switching between languages, e.g., if language `en` and `de` contain a page
|
||||
with the same path name, the user will stay on the current page:
|
||||
|
||||
```
|
||||
docs.example.com/en/ -> docs.example.com/de/
|
||||
docs.example.com/en/foo/ -> docs.example.com/de/foo/
|
||||
docs.example.com/en/bar/ -> docs.example.com/de/bar/
|
||||
```
|
||||
|
||||
No configuration is necessary.
|
||||
|
||||
### Directionality
|
||||
|
||||
<!-- md:version 2.5.0 -->
|
||||
<!-- md:default computed -->
|
||||
|
||||
While many languages are read `ltr` (left-to-right), Material for MkDocs also
|
||||
supports `rtl` (right-to-left) directionality which is deduced from the
|
||||
selected language, but can also be set with:
|
||||
|
||||
``` yaml
|
||||
theme:
|
||||
direction: ltr
|
||||
```
|
||||
|
||||
Click on a tile to change the directionality:
|
||||
|
||||
<div class="mdx-switch">
|
||||
<button data-md-dir="ltr"><code>ltr</code></button>
|
||||
<button data-md-dir="rtl"><code>rtl</code></button>
|
||||
</div>
|
||||
|
||||
<script>
|
||||
var buttons = document.querySelectorAll("button[data-md-dir]")
|
||||
buttons.forEach(function(button) {
|
||||
button.addEventListener("click", function() {
|
||||
var attr = this.getAttribute("data-md-dir")
|
||||
document.body.dir = attr
|
||||
var name = document.querySelector("#__code_2 code span.l")
|
||||
name.textContent = attr
|
||||
})
|
||||
})
|
||||
</script>
|
||||
|
||||
## Customization
|
||||
|
||||
### Custom translations
|
||||
|
||||
If you want to customize some of the translations for a language, just follow
|
||||
the guide on [theme extension] and create a new partial in the `overrides`
|
||||
folder. Then, import the [translations] of the language as a fallback and only
|
||||
adjust the ones you want to override:
|
||||
|
||||
=== ":octicons-file-code-16: `overrides/partials/languages/custom.html`"
|
||||
|
||||
``` html
|
||||
<!-- Import translations for language and fallback -->
|
||||
{% import "partials/languages/de.html" as language %}
|
||||
{% import "partials/languages/en.html" as fallback %} <!-- (1)! -->
|
||||
|
||||
<!-- Define custom translations -->
|
||||
{% macro override(key) %}{{ {
|
||||
"source.file.date.created": "Erstellt am", <!-- (2)! -->
|
||||
"source.file.date.updated": "Aktualisiert am"
|
||||
}[key] }}{% endmacro %}
|
||||
|
||||
<!-- Re-export translations -->
|
||||
{% macro t(key) %}{{
|
||||
override(key) or language.t(key) or fallback.t(key)
|
||||
}}{% endmacro %}
|
||||
```
|
||||
|
||||
1. Note that `en` must always be used as a fallback language, as it's the
|
||||
default theme language.
|
||||
|
||||
2. Check the [list of available languages], pick the translation you want
|
||||
to override for your language and add them here.
|
||||
|
||||
=== ":octicons-file-code-16: `mkdocs.yml`"
|
||||
|
||||
``` yaml
|
||||
theme:
|
||||
language: custom
|
||||
```
|
||||
|
||||
[theme extension]: ../customization.md#extending-the-theme
|
||||
[translations]: https://github.com/squidfunk/mkdocs-material/blob/master/src/templates/partials/languages/
|
||||
[list of available languages]: https://github.com/squidfunk/mkdocs-material/blob/master/src/templates/partials/languages/
|
||||
@@ -0,0 +1,166 @@
|
||||
# Changing the logo and icons
|
||||
|
||||
When installing Material for MkDocs, you immediately get access to _over 8,000
|
||||
icons_ ready to be used for customization of specific parts of the theme and/or
|
||||
when writing your documentation in Markdown. Not enough? You can also add
|
||||
[additional icons] with minimal effort.
|
||||
|
||||
[additional icons]: #additional-icons
|
||||
|
||||
## Configuration
|
||||
|
||||
### Logo
|
||||
|
||||
<!-- md:version 0.1.0 -->
|
||||
<!-- md:default `material/library` -->
|
||||
|
||||
The logo can be changed to a user-provided image (any type, incl. `*.png` and
|
||||
`*.svg`) located in the `docs` folder, or to any icon bundled with the theme.
|
||||
Add the following lines to `mkdocs.yml`:
|
||||
|
||||
=== ":octicons-image-16: Image"
|
||||
|
||||
``` yaml
|
||||
theme:
|
||||
logo: assets/logo.png
|
||||
```
|
||||
|
||||
=== ":octicons-package-16: Icon, bundled"
|
||||
|
||||
``` yaml
|
||||
theme:
|
||||
icon:
|
||||
logo: material/library # (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="material library" />
|
||||
<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>
|
||||
|
||||
[icon search]: ../reference/icons-emojis.md#search
|
||||
|
||||
Normally, the logo in the header and sidebar links to the homepage of the
|
||||
documentation, which is the same as `site_url`. This behavior can be changed
|
||||
with the following configuration:
|
||||
|
||||
``` yaml
|
||||
extra:
|
||||
homepage: https://example.com
|
||||
```
|
||||
|
||||
### Favicon
|
||||
|
||||
<!-- md:version 0.1.0 -->
|
||||
<!-- md:default [`assets/images/favicon.png`][Favicon default] -->
|
||||
|
||||
The favicon can be changed to a path pointing to a user-provided image, which
|
||||
must be located in the `docs` folder. Add the following lines to `mkdocs.yml`:
|
||||
|
||||
``` yaml
|
||||
theme:
|
||||
favicon: images/favicon.png
|
||||
```
|
||||
|
||||
[Favicon default]: https://github.com/squidfunk/mkdocs-material/blob/master/material/templates/assets/images/favicon.png
|
||||
|
||||
### Site icons
|
||||
|
||||
[:octicons-tag-24: 9.2.0][Site icon support]
|
||||
|
||||
Most icons you see on your site, such as navigation icons, can also be changed. For example,
|
||||
to change the navigation arrows in the footer, add the following lines to `mkdocs.yml`:
|
||||
|
||||
```yaml
|
||||
theme:
|
||||
icon:
|
||||
previous: fontawesome/solid/angle-left
|
||||
next: fontawesome/solid/angle-right
|
||||
```
|
||||
|
||||
The following is a complete list of customizable icons used by the theme:
|
||||
|
||||
| Icon name | Purpose |
|
||||
|:-------------|:------------------------------------------------------------------------------|
|
||||
| `logo` | See [Logo](#logo) |
|
||||
| `menu` | Open drawer |
|
||||
| `alternate` | Change language |
|
||||
| `search` | Search icon |
|
||||
| `share` | Share search |
|
||||
| `close` | Reset search, dismiss announcements |
|
||||
| `top` | Back-to-top button |
|
||||
| `edit` | Edit current page |
|
||||
| `view` | View page source |
|
||||
| `repo` | Repository icon |
|
||||
| `admonition` | See [Admonition icons](../reference/admonitions.md#admonition-icons) |
|
||||
| `tag` | See [Tag icons and identifiers](setting-up-tags.md#tag-icons-and-identifiers) |
|
||||
| `previous` | Previous page in footer, hide search on mobile |
|
||||
| `next` | Next page in footer |
|
||||
|
||||
[Site icon support]: https://github.com/squidfunk/mkdocs-material/releases/tag/9.2.0
|
||||
|
||||
## Customization
|
||||
|
||||
### Additional icons
|
||||
|
||||
In order to use custom icons, [extend the theme] and create a new folder named
|
||||
`.icons` in the [`custom_dir`][custom_dir] you want to use for overrides.
|
||||
Next, add your `*.svg` icons into a subfolder of the `.icons` folder. Let's say
|
||||
you downloaded and unpacked the [Bootstrap] icon set, and want to add it to
|
||||
your project documentation. The structure of your project should look like this:
|
||||
|
||||
``` { .sh .no-copy }
|
||||
.
|
||||
├─ overrides/
|
||||
│ └─ .icons/
|
||||
│ └─ bootstrap/
|
||||
│ └─ *.svg
|
||||
└─ mkdocs.yml
|
||||
```
|
||||
|
||||
Then, add the following lines to `mkdocs.yml`:
|
||||
|
||||
``` yaml
|
||||
markdown_extensions:
|
||||
- pymdownx.emoji:
|
||||
emoji_index: !!python/name:material.extensions.emoji.twemoji
|
||||
emoji_generator: !!python/name:material.extensions.emoji.to_svg
|
||||
options:
|
||||
custom_icons:
|
||||
- overrides/.icons
|
||||
```
|
||||
|
||||
You can now use all :fontawesome-brands-bootstrap: Bootstrap icons anywhere in
|
||||
Markdown files, as well as everywhere icons can be used in `mkdocs.yml`.
|
||||
However, note that the syntaxes are slightly different:
|
||||
|
||||
- __Using icons in configuration__: take the path of the `*.svg` icon file
|
||||
starting at the `.icons` folder and drop the file extension, e.g. for
|
||||
`.icons/bootstrap/envelope-paper.svg`, use:
|
||||
|
||||
``` yaml
|
||||
theme:
|
||||
icon:
|
||||
logo: bootstrap/envelope-paper
|
||||
```
|
||||
|
||||
- __Using icons in Markdown files__: additionally to taking the path from the
|
||||
`.icons` folder as noted above, replace all `/` with `-` and enclose the icon
|
||||
shortcode in two colons:
|
||||
|
||||
```
|
||||
:bootstrap-envelope-paper:
|
||||
```
|
||||
|
||||
For further notes on icon usage, please consult the [icon reference].
|
||||
|
||||
[extend the theme]: ../customization.md#extending-the-theme
|
||||
[custom_dir]: https://www.mkdocs.org/user-guide/configuration/#custom_dir
|
||||
[Bootstrap]: https://icons.getbootstrap.com/
|
||||
[icon reference]: ../reference/icons-emojis.md#using-icons
|
||||
@@ -0,0 +1,320 @@
|
||||
# Ensuring data privacy
|
||||
|
||||
Material for MkDocs makes compliance with data privacy regulations very easy,
|
||||
as it offers a native [cookie consent] solution to seek explicit consent from
|
||||
users before setting up [analytics]. Additionally, external assets can be
|
||||
automatically downloaded for [self-hosting].
|
||||
|
||||
[cookie consent]: #cookie-consent
|
||||
[analytics]: setting-up-site-analytics.md
|
||||
[self-hosting]: #built-in-privacy-plugin
|
||||
|
||||
## Configuration
|
||||
|
||||
### Cookie consent
|
||||
|
||||
<!-- md:version 8.4.0 -->
|
||||
<!-- md:default none -->
|
||||
<!-- md:flag experimental -->
|
||||
<!-- md:example cookie-consent -->
|
||||
|
||||
Material for MkDocs ships a native and extensible cookie consent form which
|
||||
asks the user for consent prior to sending requests to third parties. Add the
|
||||
following to `mkdocs.yml`:
|
||||
|
||||
``` yaml
|
||||
extra:
|
||||
consent:
|
||||
title: Cookie consent
|
||||
description: >- # (1)!
|
||||
We use cookies to recognize your repeated visits and preferences, as well
|
||||
as to measure the effectiveness of our documentation and whether users
|
||||
find what they're searching for. With your consent, you're helping us to
|
||||
make our documentation better.
|
||||
```
|
||||
|
||||
1. You can add arbitrary HTML tags in the `description`, e.g. to link to your
|
||||
terms of service or other parts of the site.
|
||||
|
||||
The following properties are available:
|
||||
|
||||
<!-- md:option consent.title -->
|
||||
|
||||
: <!-- md:default none --> <!-- md:flag required -->
|
||||
This property sets the title of the cookie consent, which is rendered at the
|
||||
top of the form and must be set to a non-empty string.
|
||||
|
||||
<!-- md:option consent.description -->
|
||||
|
||||
: <!-- md:default none --> <!-- md:flag required -->
|
||||
This property sets the description of the cookie consent, is rendered below
|
||||
the title, and may include raw HTML (e.g. a links to the terms of service).
|
||||
|
||||
<!-- md:option consent.cookies -->
|
||||
|
||||
: <!-- md:default none --> This property allows to add custom
|
||||
cookies or change the initial `checked` state and name of built-in cookies.
|
||||
Currently, the following cookies are built-in:
|
||||
|
||||
- __Google Analytics__ – `analytics` (enabled by default)
|
||||
- __GitHub__ – `github` (enabled by default)
|
||||
|
||||
Each cookie must receive a unique identifier which is used as a key in the
|
||||
`cookies` map, and can be either set to a string, or to a map defining
|
||||
`name` and `checked` state:
|
||||
|
||||
=== "Custom cookie name"
|
||||
|
||||
``` yaml
|
||||
extra:
|
||||
consent:
|
||||
cookies:
|
||||
analytics: Custom name
|
||||
```
|
||||
|
||||
=== "Custom initial state"
|
||||
|
||||
``` yaml
|
||||
extra:
|
||||
consent:
|
||||
cookies:
|
||||
analytics:
|
||||
name: Google Analytics
|
||||
checked: false
|
||||
```
|
||||
|
||||
=== "Custom cookie"
|
||||
|
||||
``` yaml
|
||||
extra:
|
||||
consent:
|
||||
cookies:
|
||||
analytics: Google Analytics # (1)!
|
||||
custom: Custom cookie
|
||||
```
|
||||
|
||||
1. If you define a custom cookie as part of the `cookies` property,
|
||||
the `analytics` cookie must be added back explicitly, or analytics
|
||||
won't be triggered.
|
||||
|
||||
If Google Analytics was configured via `mkdocs.yml`, the cookie consent will
|
||||
automatically include a setting for the user to disable it. [Custom cookies]
|
||||
can be used from JavaScript.
|
||||
|
||||
<!-- md:option consent.actions -->
|
||||
|
||||
: <!-- md:default `[accept, manage]` --> This property defines
|
||||
which buttons are shown and in which order, e.g. to allow the user to accept
|
||||
cookies and manage settings:
|
||||
|
||||
``` yaml
|
||||
extra:
|
||||
consent:
|
||||
actions:
|
||||
- accept
|
||||
- manage # (1)!
|
||||
```
|
||||
|
||||
1. If the `manage` settings button is omitted from the `actions` property,
|
||||
the settings are always shown.
|
||||
|
||||
The cookie consent form includes three types of buttons:
|
||||
|
||||
- `accept` – Button to accept selected cookies
|
||||
- `reject` – Button to reject all cookies
|
||||
- `manage` – Button to manage settings
|
||||
|
||||
When a user first visits your site, a cookie consent form is rendered:
|
||||
|
||||
[![Cookie consent enabled]][Cookie consent enabled]
|
||||
|
||||
[Custom cookies]: #custom-cookies
|
||||
[Cookie consent enabled]: ../assets/screenshots/consent.png
|
||||
|
||||
#### Change cookie settings
|
||||
|
||||
In order to comply with GDPR, users must be able to change their cookie settings
|
||||
at any time. This can be done by adding a simple link to your [copyright notice]
|
||||
in `mkdocs.yml`:
|
||||
|
||||
``` yaml
|
||||
copyright: >
|
||||
Copyright © 2016 - 2024 Martin Donath –
|
||||
<a href="#__consent">Change cookie settings</a>
|
||||
```
|
||||
|
||||
[copyright notice]: setting-up-the-footer.md#copyright-notice
|
||||
|
||||
### Built-in privacy plugin
|
||||
|
||||
<!-- md:version 9.5.0 -->
|
||||
<!-- md:plugin [privacy][built-in privacy plugin] -->
|
||||
<!-- md:flag experimental -->
|
||||
|
||||
The built-in privacy plugin automatically identifies external assets as part
|
||||
of the build process and downloads all assets for very simple self-hosting. Add
|
||||
the following lines to `mkdocs.yml`:
|
||||
|
||||
``` yaml
|
||||
plugins:
|
||||
- privacy
|
||||
```
|
||||
|
||||
For a list of all settings, please consult the [plugin documentation].
|
||||
|
||||
[plugin documentation]: ../plugins/privacy.md
|
||||
|
||||
!!! tip "Hosting images externally and optimizing them automatically"
|
||||
|
||||
This option makes the [built-in privacy plugin] an excellent choice for
|
||||
when you want to host assets like images outside of your git repository
|
||||
in another location to keep them fresh and your repository lean.
|
||||
|
||||
Additionally, as of <!-- md:version 9.7.0 -->, the
|
||||
built-in privacy plugin was entirely rewritten and now works perfectly
|
||||
with the [built-in optimize plugin], which means that external assets
|
||||
can be passed through the same optimization pipeline as the rest of your
|
||||
documentation. This means you can store and edit unoptimized files
|
||||
outside of your repository, and let both plugins built a highly
|
||||
optimized site for you.
|
||||
|
||||
If you want to implement separate pipelines, i.e., optimize some images
|
||||
differently from others or exclude some images from downloading, you can
|
||||
use multiple instances of the [built-in privacy plugin].
|
||||
|
||||
!!! question "Why can't Material for MkDocs bundle all assets by design?"
|
||||
|
||||
The primary reason why Material for MkDocs can't just bundle all of its own
|
||||
assets is the integration with [Google Fonts], which offers over a thousand
|
||||
different fonts that can be used to render your documentation. Most of the
|
||||
fonts include several weights and are split up into different character sets
|
||||
to keep the download size small, so the browser only downloads what is
|
||||
really needed. For Roboto, our default [regular font], this results in [42
|
||||
`*.woff2` files in total][example].
|
||||
|
||||
If Material for MkDocs would bundle all font files, the download size would
|
||||
be in the hundreds of megabytes, slowing down automated builds. Furthermore,
|
||||
authors might add external assets like third-party scripts or style sheets
|
||||
that would need to be remembered to be defined as further local assets.
|
||||
|
||||
This is the very reason the [built-in privacy plugin] exists — it automates
|
||||
the process of downloading all external assets manually to ensure compliance
|
||||
with GDPR with some some [technical limitations].
|
||||
|
||||
[Google Fonts]: changing-the-fonts.md
|
||||
[regular font]: changing-the-fonts.md#regular-font
|
||||
[example]: #example
|
||||
[built-in optimize plugin]: ../plugins/optimize.md
|
||||
[technical limitations]: ../plugins/privacy.md#limitations
|
||||
|
||||
??? example "Expand to inspect example"
|
||||
|
||||
For the official documentation, the [built-in privacy plugin] downloads the
|
||||
following resources:
|
||||
|
||||
``` { .sh .no-copy #example }
|
||||
.
|
||||
└─ assets/external/
|
||||
├─ unpkg.com/tablesort@5.3.0/dist/tablesort.min.js
|
||||
├─ fonts.googleapis.com/css
|
||||
└─ fonts.gstatic.com/s/
|
||||
├─ roboto/v29/
|
||||
│ ├─ KFOjCnqEu92Fr1Mu51TjASc-CsTKlA.woff2
|
||||
│ ├─ KFOjCnqEu92Fr1Mu51TjASc0CsTKlA.woff2
|
||||
│ ├─ KFOjCnqEu92Fr1Mu51TjASc1CsTKlA.woff2
|
||||
│ ├─ KFOjCnqEu92Fr1Mu51TjASc2CsTKlA.woff2
|
||||
│ ├─ KFOjCnqEu92Fr1Mu51TjASc3CsTKlA.woff2
|
||||
│ ├─ KFOjCnqEu92Fr1Mu51TjASc5CsTKlA.woff2
|
||||
│ ├─ KFOjCnqEu92Fr1Mu51TjASc6CsQ.woff2
|
||||
│ ├─ KFOjCnqEu92Fr1Mu51TzBic-CsTKlA.woff2
|
||||
│ ├─ KFOjCnqEu92Fr1Mu51TzBic0CsTKlA.woff2
|
||||
│ ├─ KFOjCnqEu92Fr1Mu51TzBic1CsTKlA.woff2
|
||||
│ ├─ KFOjCnqEu92Fr1Mu51TzBic2CsTKlA.woff2
|
||||
│ ├─ KFOjCnqEu92Fr1Mu51TzBic3CsTKlA.woff2
|
||||
│ ├─ KFOjCnqEu92Fr1Mu51TzBic5CsTKlA.woff2
|
||||
│ ├─ KFOjCnqEu92Fr1Mu51TzBic6CsQ.woff2
|
||||
│ ├─ KFOkCnqEu92Fr1Mu51xEIzIFKw.woff2
|
||||
│ ├─ KFOkCnqEu92Fr1Mu51xFIzIFKw.woff2
|
||||
│ ├─ KFOkCnqEu92Fr1Mu51xGIzIFKw.woff2
|
||||
│ ├─ KFOkCnqEu92Fr1Mu51xHIzIFKw.woff2
|
||||
│ ├─ KFOkCnqEu92Fr1Mu51xIIzI.woff2
|
||||
│ ├─ KFOkCnqEu92Fr1Mu51xLIzIFKw.woff2
|
||||
│ ├─ KFOkCnqEu92Fr1Mu51xMIzIFKw.woff2
|
||||
│ ├─ KFOlCnqEu92Fr1MmSU5fABc4EsA.woff2
|
||||
│ ├─ KFOlCnqEu92Fr1MmSU5fBBc4.woff2
|
||||
│ ├─ KFOlCnqEu92Fr1MmSU5fBxc4EsA.woff2
|
||||
│ ├─ KFOlCnqEu92Fr1MmSU5fCBc4EsA.woff2
|
||||
│ ├─ KFOlCnqEu92Fr1MmSU5fCRc4EsA.woff2
|
||||
│ ├─ KFOlCnqEu92Fr1MmSU5fChc4EsA.woff2
|
||||
│ ├─ KFOlCnqEu92Fr1MmSU5fCxc4EsA.woff2
|
||||
│ ├─ KFOlCnqEu92Fr1MmWUlfABc4EsA.woff2
|
||||
│ ├─ KFOlCnqEu92Fr1MmWUlfBBc4.woff2
|
||||
│ ├─ KFOlCnqEu92Fr1MmWUlfBxc4EsA.woff2
|
||||
│ ├─ KFOlCnqEu92Fr1MmWUlfCBc4EsA.woff2
|
||||
│ ├─ KFOlCnqEu92Fr1MmWUlfCRc4EsA.woff2
|
||||
│ ├─ KFOlCnqEu92Fr1MmWUlfChc4EsA.woff2
|
||||
│ ├─ KFOlCnqEu92Fr1MmWUlfCxc4EsA.woff2
|
||||
│ ├─ KFOmCnqEu92Fr1Mu4WxKOzY.woff2
|
||||
│ ├─ KFOmCnqEu92Fr1Mu4mxK.woff2
|
||||
│ ├─ KFOmCnqEu92Fr1Mu5mxKOzY.woff2
|
||||
│ ├─ KFOmCnqEu92Fr1Mu72xKOzY.woff2
|
||||
│ ├─ KFOmCnqEu92Fr1Mu7GxKOzY.woff2
|
||||
│ ├─ KFOmCnqEu92Fr1Mu7WxKOzY.woff2
|
||||
│ └─ KFOmCnqEu92Fr1Mu7mxKOzY.woff2
|
||||
└─ robotomono/v13/
|
||||
├─ L0xTDF4xlVMF-BfR8bXMIhJHg45mwgGEFl0_3vrtSM1J-gEPT5Ese6hmHSV0mf0h.woff2
|
||||
├─ L0xTDF4xlVMF-BfR8bXMIhJHg45mwgGEFl0_3vrtSM1J-gEPT5Ese6hmHSZ0mf0h.woff2
|
||||
├─ L0xTDF4xlVMF-BfR8bXMIhJHg45mwgGEFl0_3vrtSM1J-gEPT5Ese6hmHSd0mf0h.woff2
|
||||
├─ L0xTDF4xlVMF-BfR8bXMIhJHg45mwgGEFl0_3vrtSM1J-gEPT5Ese6hmHSh0mQ.woff2
|
||||
├─ L0xTDF4xlVMF-BfR8bXMIhJHg45mwgGEFl0_3vrtSM1J-gEPT5Ese6hmHSt0mf0h.woff2
|
||||
├─ L0xTDF4xlVMF-BfR8bXMIhJHg45mwgGEFl0_3vrtSM1J-gEPT5Ese6hmHSx0mf0h.woff2
|
||||
├─ L0xdDF4xlVMF-BfR8bXMIjhOsXG-q2oeuFoqFrlnAIe2Imhk1T8rbociImtElOUlYIw.woff2
|
||||
├─ L0xdDF4xlVMF-BfR8bXMIjhOsXG-q2oeuFoqFrlnAIe2Imhk1T8rbociImtEleUlYIw.woff2
|
||||
├─ L0xdDF4xlVMF-BfR8bXMIjhOsXG-q2oeuFoqFrlnAIe2Imhk1T8rbociImtEluUlYIw.woff2
|
||||
├─ L0xdDF4xlVMF-BfR8bXMIjhOsXG-q2oeuFoqFrlnAIe2Imhk1T8rbociImtEm-Ul.woff2
|
||||
├─ L0xdDF4xlVMF-BfR8bXMIjhOsXG-q2oeuFoqFrlnAIe2Imhk1T8rbociImtEmOUlYIw.woff2
|
||||
└─ L0xdDF4xlVMF-BfR8bXMIjhOsXG-q2oeuFoqFrlnAIe2Imhk1T8rbociImtEn-UlYIw.woff2
|
||||
```
|
||||
|
||||
[built-in privacy plugin]: ../plugins/privacy.md
|
||||
[preconnect]: https://developer.mozilla.org/en-US/docs/Web/Performance/dns-prefetch
|
||||
|
||||
## Customization
|
||||
|
||||
### Custom cookies
|
||||
|
||||
<!-- md:version 8.4.0 -->
|
||||
<!-- md:example custom-cookies -->
|
||||
|
||||
If you've customized the [cookie consent] and added a `custom` cookie, the user
|
||||
will be prompted to accept or reject your custom cookie. Once the user accepts
|
||||
or rejects the cookie consent, or [changes the settings], the page reloads[^1].
|
||||
Use [additional JavaScript] to query the result:
|
||||
|
||||
[^1]:
|
||||
We reload the page to make interop with custom cookies simpler. If Material
|
||||
for MkDocs would implement a callback-based approach, the author would need
|
||||
to make sure to correctly update all scripts that use cookies. Additionally,
|
||||
the cookie consent is only answered initially, which is why we consider this
|
||||
to be a good trade-off of DX and UX.
|
||||
|
||||
=== ":octicons-file-code-16: `docs/javascripts/consent.js`"
|
||||
|
||||
``` js
|
||||
var consent = __md_get("__consent")
|
||||
if (consent && consent.custom) {
|
||||
/* The user accepted the cookie */
|
||||
} else {
|
||||
/* The user rejected the cookie */
|
||||
}
|
||||
```
|
||||
|
||||
=== ":octicons-file-code-16: `mkdocs.yml`"
|
||||
|
||||
``` yaml
|
||||
extra_javascript:
|
||||
- javascripts/consent.js
|
||||
```
|
||||
|
||||
[additional JavaScript]: ../customization.md#additional-javascript
|
||||
[changes the settings]: #change-cookie-settings
|
||||
@@ -0,0 +1,137 @@
|
||||
---
|
||||
title: Extensions
|
||||
---
|
||||
|
||||
# Extensions
|
||||
|
||||
Markdown is a very small language with a kind-of reference implementation called
|
||||
[John Gruber's Markdown]. [Python Markdown] and [Python Markdown Extensions]
|
||||
are two packages that enhance the Markdown writing experience, adding useful
|
||||
syntax extensions for technical writing.
|
||||
|
||||
[John Gruber's Markdown]: https://daringfireball.net/projects/markdown/
|
||||
[Python Markdown]: python-markdown.md
|
||||
[Python Markdown Extensions]: python-markdown-extensions.md
|
||||
|
||||
## Supported extensions
|
||||
|
||||
The following extensions are all supported by Material for MkDocs and therefore
|
||||
strongly recommended. Click on each extension to learn about its purpose and
|
||||
configuration:
|
||||
|
||||
<div class="mdx-columns" markdown>
|
||||
|
||||
- [Abbreviations]
|
||||
- [Admonition]
|
||||
- [Arithmatex]
|
||||
- [Attribute Lists]
|
||||
- [BetterEm]
|
||||
- [Caret, Mark & Tilde]
|
||||
- [Critic]
|
||||
- [Definition Lists]
|
||||
- [Details]
|
||||
- [Emoji]
|
||||
- [Footnotes]
|
||||
- [Highlight]
|
||||
- [Keys]
|
||||
- [Markdown in HTML]
|
||||
- [SmartSymbols]
|
||||
- [Snippets]
|
||||
- [SuperFences]
|
||||
- [Tabbed]
|
||||
- [Table of Contents]
|
||||
- [Tables]
|
||||
- [Tasklist]
|
||||
|
||||
</div>
|
||||
|
||||
[Abbreviations]: python-markdown.md#abbreviations
|
||||
[Admonition]: python-markdown.md#admonition
|
||||
[Arithmatex]: python-markdown-extensions.md#arithmatex
|
||||
[Attribute Lists]: python-markdown.md#attribute-lists
|
||||
[BetterEm]: python-markdown-extensions.md#betterem
|
||||
[Caret, Mark & Tilde]: python-markdown-extensions.md#caret-mark-tilde
|
||||
[Critic]: python-markdown-extensions.md#critic
|
||||
[Definition Lists]: python-markdown.md#definition-lists
|
||||
[Details]: python-markdown-extensions.md#details
|
||||
[Emoji]: python-markdown-extensions.md#emoji
|
||||
[Footnotes]: python-markdown.md#footnotes
|
||||
[Highlight]: python-markdown-extensions.md#highlight
|
||||
[Keys]: python-markdown-extensions.md#keys
|
||||
[Markdown in HTML]: python-markdown.md#markdown-in-html
|
||||
[SmartSymbols]: python-markdown-extensions.md#smartsymbols
|
||||
[Snippets]: python-markdown-extensions.md#snippets
|
||||
[SuperFences]: python-markdown-extensions.md#superfences
|
||||
[Tabbed]: python-markdown-extensions.md#tabbed
|
||||
[Table of Contents]: python-markdown.md#table-of-contents
|
||||
[Tables]: python-markdown.md#tables
|
||||
[Tasklist]: python-markdown-extensions.md#tasklist
|
||||
|
||||
## Configuration
|
||||
|
||||
Extensions are configured as part of `mkdocs.yml` – the MkDocs configuration
|
||||
file. The following sections contain two example configurations to bootstrap
|
||||
your documentation project.
|
||||
|
||||
[overview]: #advanced-configuration
|
||||
|
||||
### Minimal configuration
|
||||
|
||||
This configuration is a good starting point for when you're using Material for
|
||||
MkDocs for the first time. The best idea is to explore the [reference], and
|
||||
gradually add what you want to use:
|
||||
|
||||
``` yaml
|
||||
markdown_extensions:
|
||||
|
||||
# Python Markdown
|
||||
- toc:
|
||||
permalink: true
|
||||
|
||||
# Python Markdown Extensions
|
||||
- pymdownx.highlight
|
||||
- pymdownx.superfences
|
||||
```
|
||||
|
||||
[reference]: ../../reference/index.md
|
||||
|
||||
### Recommended configuration
|
||||
|
||||
This configuration enables all Markdown-related features of Material for MkDocs
|
||||
and is great for experienced users bootstrapping a new documentation project:
|
||||
|
||||
``` yaml
|
||||
markdown_extensions:
|
||||
|
||||
# Python Markdown
|
||||
- abbr
|
||||
- admonition
|
||||
- attr_list
|
||||
- def_list
|
||||
- footnotes
|
||||
- md_in_html
|
||||
- toc:
|
||||
permalink: true
|
||||
|
||||
# Python Markdown Extensions
|
||||
- pymdownx.arithmatex:
|
||||
generic: true
|
||||
- pymdownx.betterem:
|
||||
smart_enable: all
|
||||
- pymdownx.caret
|
||||
- pymdownx.details
|
||||
- pymdownx.emoji:
|
||||
emoji_index: !!python/name:material.extensions.emoji.twemoji
|
||||
emoji_generator: !!python/name:material.extensions.emoji.to_svg
|
||||
- pymdownx.highlight
|
||||
- pymdownx.inlinehilite
|
||||
- pymdownx.keys
|
||||
- pymdownx.mark
|
||||
- pymdownx.smartsymbols
|
||||
- pymdownx.superfences
|
||||
- pymdownx.tabbed:
|
||||
alternate_style: true
|
||||
- pymdownx.tasklist:
|
||||
custom_checkbox: true
|
||||
- pymdownx.tilde
|
||||
```
|
||||
@@ -0,0 +1,801 @@
|
||||
# Python Markdown Extensions
|
||||
|
||||
The [Python Markdown Extensions] package is an excellent collection of
|
||||
additional extensions perfectly suited for advanced technical writing. Material
|
||||
for MkDocs lists this package as an explicit dependency, so it's automatically
|
||||
installed with a supported version.
|
||||
|
||||
[Python Markdown Extensions]: https://facelessuser.github.io/pymdown-extensions/
|
||||
|
||||
## Supported extensions
|
||||
|
||||
In general, all extensions that are part of [Python Markdown Extensions] should
|
||||
work with Material for MkDocs. The following list includes all extensions that
|
||||
are natively supported, meaning they work without any further adjustments.
|
||||
|
||||
### Arithmatex
|
||||
|
||||
<!-- md:version 1.0.0 -->
|
||||
<!-- md:extension [pymdownx.arithmatex][Arithmatex] -->
|
||||
|
||||
The [Arithmatex] extension allows for rendering of block and inline block
|
||||
equations and integrates seamlessly with [MathJax][^1] – a library for
|
||||
mathematical typesetting. Enable it via `mkdocs.yml`:
|
||||
|
||||
[^1]:
|
||||
Other libraries like [KaTeX] are also supported and can be integrated with
|
||||
some additional effort. See the [Arithmatex documentation on KaTeX] for
|
||||
further guidance, as this is beyond the scope of Material for MkDocs.
|
||||
|
||||
``` yaml
|
||||
markdown_extensions:
|
||||
- pymdownx.arithmatex:
|
||||
generic: true
|
||||
```
|
||||
|
||||
Besides enabling the extension in `mkdocs.yml`, a MathJax configuration and
|
||||
the JavaScript runtime need to be included, which can be done with a few lines
|
||||
of [additional JavaScript]:
|
||||
|
||||
=== ":octicons-file-code-16: `docs/javascripts/mathjax.js`"
|
||||
|
||||
``` js
|
||||
window.MathJax = {
|
||||
tex: {
|
||||
inlineMath: [["\\(", "\\)"]],
|
||||
displayMath: [["\\[", "\\]"]],
|
||||
processEscapes: true,
|
||||
processEnvironments: true
|
||||
},
|
||||
options: {
|
||||
ignoreHtmlClass: ".*|",
|
||||
processHtmlClass: "arithmatex"
|
||||
}
|
||||
};
|
||||
|
||||
document$.subscribe(() => { // (1)!
|
||||
MathJax.startup.output.clearCache()
|
||||
MathJax.typesetClear()
|
||||
MathJax.texReset()
|
||||
MathJax.typesetPromise()
|
||||
})
|
||||
```
|
||||
|
||||
1. This integrates MathJax with [instant loading]
|
||||
|
||||
|
||||
=== ":octicons-file-code-16: `mkdocs.yml`"
|
||||
|
||||
``` yaml
|
||||
extra_javascript:
|
||||
- javascripts/mathjax.js
|
||||
- https://unpkg.com/mathjax@3/es5/tex-mml-chtml.js
|
||||
```
|
||||
|
||||
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.
|
||||
|
||||
See reference for usage:
|
||||
|
||||
- [Using block syntax]
|
||||
- [Using inline block syntax]
|
||||
|
||||
[Arithmatex]: https://facelessuser.github.io/pymdown-extensions/extensions/arithmatex/
|
||||
[Arithmatex documentation on KaTeX]: https://facelessuser.github.io/pymdown-extensions/extensions/arithmatex/#loading-katex
|
||||
[MathJax]: https://www.mathjax.org/
|
||||
[KaTeX]: https://github.com/Khan/KaTeX
|
||||
[additional JavaScript]: ../../customization.md#additional-javascript
|
||||
[instant loading]: ../setting-up-navigation.md#instant-loading
|
||||
[Using block syntax]: ../../reference/math.md#using-block-syntax
|
||||
[Using inline block syntax]: ../../reference/math.md#using-inline-block-syntax
|
||||
|
||||
### BetterEm
|
||||
|
||||
<!-- md:version 0.1.0 -->
|
||||
<!-- md:extension [pymdownx.betterem][BetterEm] -->
|
||||
|
||||
The [BetterEm] extension improves the detection of Markup to emphasize text
|
||||
in Markdown using special characters, i.e. for `**bold**` and `_italic_`
|
||||
formatting. Enable it via `mkdocs.yml`:
|
||||
|
||||
``` yaml
|
||||
markdown_extensions:
|
||||
- pymdownx.betterem
|
||||
```
|
||||
|
||||
The configuration options of this extension are not specific to Material for
|
||||
MkDocs, as they only impact the Markdown parsing stage. See the [BetterEm
|
||||
documentation][BetterEm] for more information.
|
||||
|
||||
[BetterEm]: https://facelessuser.github.io/pymdown-extensions/extensions/betterem/
|
||||
|
||||
### Caption
|
||||
|
||||
<!-- md:version 1.0.0 -->
|
||||
<!-- md:extension [pymdownx.blocks.caption][Caption] -->
|
||||
|
||||
The [Caption] extension adds the ability to add captions to any Markdown block,
|
||||
including images, tables, and code blocks. Enable it via `mkdocs.yml`:
|
||||
|
||||
``` yaml
|
||||
markdown_extensions:
|
||||
- pymdownx.blocks.caption
|
||||
```
|
||||
|
||||
The configuration options of this extension are not specific to Material for
|
||||
MkDocs, as they only impact the Markdown parsing stage. See the [Caption
|
||||
documentation][Caption] for more information.
|
||||
|
||||
[Caption]: https://facelessuser.github.io/pymdown-extensions/extensions/blocks/plugins/caption/
|
||||
|
||||
### Caret, Mark & Tilde
|
||||
|
||||
<!-- md:version 1.0.0 -->
|
||||
<!-- md:extension [pymdownx.caret][Caret] -->
|
||||
|
||||
The [Caret], [Mark] and [Tilde] extensions add the ability to highlight text
|
||||
and define sub- and superscript using a simple syntax. Enable them together
|
||||
via `mkdocs.yml`:
|
||||
|
||||
``` yaml
|
||||
markdown_extensions:
|
||||
- pymdownx.caret
|
||||
- pymdownx.mark
|
||||
- pymdownx.tilde
|
||||
```
|
||||
|
||||
The configuration options of this extension are not specific to Material for
|
||||
MkDocs, as they only impact the Markdown parsing stage. See the [Caret], [Mark]
|
||||
and [Tilde documentation][Tilde] for guidance.
|
||||
|
||||
See reference for usage:
|
||||
|
||||
- [Highlighting text]
|
||||
- [Sub- and superscripts]
|
||||
|
||||
[Caret]: https://facelessuser.github.io/pymdown-extensions/extensions/caret/
|
||||
[Mark]: https://facelessuser.github.io/pymdown-extensions/extensions/mark/
|
||||
[Tilde]: https://facelessuser.github.io/pymdown-extensions/extensions/tilde/
|
||||
[Highlighting text]: ../../reference/formatting.md#highlighting-text
|
||||
[Sub- and superscripts]: ../../reference/formatting.md#sub-and-superscripts
|
||||
|
||||
### Critic
|
||||
|
||||
<!-- md:version 1.0.0 -->
|
||||
<!-- md:extension [pymdownx.critic][Critic] -->
|
||||
|
||||
The [Critic] extension allows for the usage of [Critic Markup] to highlight
|
||||
added, deleted or updated sections in a document, i.e. for tracking changes in
|
||||
Markdown syntax. Enable it via `mkdocs.yml`:
|
||||
|
||||
``` yaml
|
||||
markdown_extensions:
|
||||
- pymdownx.critic
|
||||
```
|
||||
|
||||
The following configuration options are supported:
|
||||
|
||||
<!-- md:option pymdownx.critic.mode -->
|
||||
|
||||
: <!-- md:default `view` --> This option defines how the markup
|
||||
should be parsed, i.e. whether to just `view` all suggested changes, or
|
||||
alternatively `accept` or `reject` them:
|
||||
|
||||
=== "View changes"
|
||||
|
||||
``` yaml
|
||||
markdown_extensions:
|
||||
- pymdownx.critic:
|
||||
mode: view
|
||||
```
|
||||
|
||||
=== "Accept changes"
|
||||
|
||||
``` yaml
|
||||
markdown_extensions:
|
||||
- pymdownx.critic:
|
||||
mode: accept
|
||||
```
|
||||
|
||||
=== "Reject changes"
|
||||
|
||||
``` yaml
|
||||
markdown_extensions:
|
||||
- pymdownx.critic:
|
||||
mode: reject
|
||||
```
|
||||
|
||||
See reference for usage:
|
||||
|
||||
- [Highlighting changes]
|
||||
|
||||
[Critic]: https://facelessuser.github.io/pymdown-extensions/extensions/critic/
|
||||
[Critic Markup]: https://github.com/CriticMarkup/CriticMarkup-toolkit
|
||||
[Highlighting changes]: ../../reference/formatting.md#highlighting-changes
|
||||
|
||||
### Details
|
||||
|
||||
<!-- md:version 1.9.0 -->
|
||||
<!-- md:extension [pymdownx.details][Details] -->
|
||||
|
||||
The [Details] extension supercharges the [Admonition] extension, making the
|
||||
resulting _call-outs_ collapsible, allowing them to be opened and closed by the
|
||||
user. Enable it via `mkdocs.yml`:
|
||||
|
||||
``` yaml
|
||||
markdown_extensions:
|
||||
- pymdownx.details
|
||||
```
|
||||
|
||||
No configuration options are available. See reference for usage:
|
||||
|
||||
- [Collapsible blocks]
|
||||
|
||||
[Details]: https://facelessuser.github.io/pymdown-extensions/extensions/details/
|
||||
[Admonition]: python-markdown.md#admonition
|
||||
[Collapsible blocks]: ../../reference/admonitions.md#collapsible-blocks
|
||||
|
||||
### Emoji
|
||||
|
||||
<!-- md:version 1.0.0 -->
|
||||
<!-- md:extension [pymdownx.emoji][Emoji] -->
|
||||
|
||||
The [Emoji] extension automatically inlines bundled and custom icons and emojis
|
||||
in `*.svg` file format into the resulting HTML page. Enable it via `mkdocs.yml`:
|
||||
|
||||
``` yaml
|
||||
markdown_extensions:
|
||||
- pymdownx.emoji:
|
||||
emoji_index: !!python/name:material.extensions.emoji.twemoji # (1)!
|
||||
emoji_generator: !!python/name:material.extensions.emoji.to_svg
|
||||
```
|
||||
|
||||
1. [Python Markdown Extensions] uses the `pymdownx` namespace, but in order to
|
||||
support the inlining of icons, the `materialx` namespace must be used, as it
|
||||
extends the functionality of `pymdownx`.
|
||||
|
||||
The following configuration options are supported:
|
||||
|
||||
<!-- md:option pymdownx.emoji.emoji_index -->
|
||||
|
||||
: <!-- md:default `emojione` --> This option defines which set
|
||||
of emojis is used for rendering. Note that the use of `emojione` is not
|
||||
recommended due to [restrictions in licensing][Emoji index]:
|
||||
|
||||
``` yaml
|
||||
markdown_extensions:
|
||||
- pymdownx.emoji:
|
||||
emoji_index: !!python/name:material.extensions.emoji.twemoji
|
||||
```
|
||||
|
||||
<!-- md:option pymdownx.emoji.emoji_generator -->
|
||||
|
||||
: <!-- md:default `to_png` --> This option defines how the
|
||||
resolved emoji or icon shortcode is render. Note that icons can only be
|
||||
used together with the `to_svg` configuration:
|
||||
|
||||
``` yaml
|
||||
markdown_extensions:
|
||||
- pymdownx.emoji:
|
||||
emoji_generator: !!python/name:material.extensions.emoji.to_svg
|
||||
```
|
||||
|
||||
<!-- md:option pymdownx.emoji.options.custom_icons -->
|
||||
|
||||
: <!-- md:default none --> This option allows to list folders
|
||||
with additional icon sets to be used in Markdown or `mkdocs.yml`, which is
|
||||
explained in more detail in the [icon customization guide]:
|
||||
|
||||
``` yaml
|
||||
markdown_extensions:
|
||||
- pymdownx.emoji:
|
||||
emoji_index: !!python/name:material.extensions.emoji.twemoji
|
||||
emoji_generator: !!python/name:material.extensions.emoji.to_svg
|
||||
options:
|
||||
custom_icons:
|
||||
- overrides/.icons
|
||||
```
|
||||
|
||||
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.
|
||||
|
||||
See reference for usage:
|
||||
|
||||
- [Using emojis]
|
||||
- [Using icons]
|
||||
- [Using icons in templates]
|
||||
|
||||
[Emoji]: https://facelessuser.github.io/pymdown-extensions/extensions/emoji/
|
||||
[Emoji index]: https://facelessuser.github.io/pymdown-extensions/extensions/emoji/#default-emoji-indexes
|
||||
[icon customization guide]: ../changing-the-logo-and-icons.md#additional-icons
|
||||
[Using emojis]: ../../reference/icons-emojis.md#using-emojis
|
||||
[Using icons]: ../../reference/icons-emojis.md#using-icons
|
||||
[Using icons in templates]: ../../reference/icons-emojis.md#using-icons-in-templates
|
||||
|
||||
### Highlight
|
||||
|
||||
<!-- md:version 5.0.0 -->
|
||||
<!-- md:extension [pymdownx.highlight][Highlight] -->
|
||||
|
||||
The [Highlight] extension adds support for syntax highlighting of code blocks
|
||||
(with the help of [SuperFences][pymdownx.superfences]) and inline code blocks
|
||||
(with the help of [InlineHilite][pymdownx.inlinehilite]). Enable it via
|
||||
`mkdocs.yml`:
|
||||
|
||||
``` yaml
|
||||
markdown_extensions:
|
||||
- pymdownx.highlight:
|
||||
anchor_linenums: true
|
||||
- pymdownx.superfences # (1)!
|
||||
```
|
||||
|
||||
1. [Highlight] is used by the [SuperFences][pymdownx.superfences] extension to
|
||||
perform syntax highlighting on code blocks, not the other way round, which
|
||||
is why this extension also needs to be enabled.
|
||||
|
||||
The following configuration options are supported:
|
||||
|
||||
<!-- md:option pymdownx.highlight.use_pygments -->
|
||||
|
||||
: <!-- md:default `true` --> This option allows to control
|
||||
whether highlighting should be carried out during build time using
|
||||
[Pygments] or in the browser with a JavaScript syntax highlighter:
|
||||
|
||||
=== "Pygments"
|
||||
|
||||
``` yaml
|
||||
markdown_extensions:
|
||||
- pymdownx.highlight:
|
||||
use_pygments: true
|
||||
- pymdownx.superfences
|
||||
```
|
||||
|
||||
=== "JavaScript"
|
||||
|
||||
``` yaml
|
||||
markdown_extensions:
|
||||
- pymdownx.highlight:
|
||||
use_pygments: false
|
||||
```
|
||||
|
||||
As an example, [Highlight.js], a JavaScript syntax highlighter, can be
|
||||
integrated with some [additional JavaScript] and an [additional style
|
||||
sheet] in `mkdocs.yml`:
|
||||
|
||||
=== ":octicons-file-code-16: `docs/javascripts/highlight.js`"
|
||||
|
||||
``` js
|
||||
document$.subscribe(() => {
|
||||
hljs.highlightAll()
|
||||
})
|
||||
```
|
||||
|
||||
=== ":octicons-file-code-16: `mkdocs.yml`"
|
||||
|
||||
``` yaml
|
||||
extra_javascript:
|
||||
- https://cdnjs.cloudflare.com/ajax/libs/highlight.js/10.7.2/highlight.min.js
|
||||
- javascripts/highlight.js
|
||||
extra_css:
|
||||
- https://cdnjs.cloudflare.com/ajax/libs/highlight.js/10.7.2/styles/default.min.css
|
||||
```
|
||||
|
||||
Note that [Highlight.js] has no affiliation with the
|
||||
[Highlight][pymdownx.highlight] extension.
|
||||
|
||||
All following configuration options are only compatible with build-time
|
||||
syntax highlighting using [Pygments], so they don't apply if `use_pygments`
|
||||
is set to `false`.
|
||||
|
||||
<!-- md:option pymdownx.highlight.pygments_lang_class -->
|
||||
|
||||
: <!-- md:default `false` --> This option instructs [Pygments]
|
||||
to add a CSS class to identify the language of the code block, which is
|
||||
essential for custom annotation markers to function:
|
||||
|
||||
``` yaml
|
||||
markdown_extensions:
|
||||
- pymdownx.highlight:
|
||||
pygments_lang_class: true
|
||||
```
|
||||
|
||||
<!-- md:option pymdownx.highlight.auto_title -->
|
||||
|
||||
: <!-- md:default `false` --> This option will automatically
|
||||
add a [title] to all code blocks that shows the name of the language being
|
||||
used, e.g. `Python` is printed for a `py` block:
|
||||
|
||||
``` yaml
|
||||
markdown_extensions:
|
||||
- pymdownx.highlight:
|
||||
auto_title: true
|
||||
```
|
||||
|
||||
<!-- md:option pymdownx.highlight.linenums -->
|
||||
|
||||
: <!-- md:default `false` --> This option will add line numbers
|
||||
to _all_ code blocks. If you wish to add line numbers to _some_, but not all
|
||||
code blocks, consult the section on [adding line numbers][Adding line
|
||||
numbers] in the code block reference, which also contains some tips on
|
||||
working with line numbers:
|
||||
|
||||
``` yaml
|
||||
markdown_extensions:
|
||||
- pymdownx.highlight:
|
||||
linenums: true
|
||||
```
|
||||
|
||||
<!-- md:option pymdownx.highlight.linenums_style -->
|
||||
|
||||
: <!-- md:default `table` --> The [Highlight] extension
|
||||
provides three ways to add line numbers, two of which are supported by
|
||||
Material for MkDocs. While `table` wraps a code block in a `<table>`
|
||||
element, `pymdownx-inline` renders line numbers as part of the line itself:
|
||||
|
||||
``` yaml
|
||||
markdown_extensions:
|
||||
- pymdownx.highlight:
|
||||
linenums_style: pymdownx-inline
|
||||
```
|
||||
|
||||
Note that `inline` will put line numbers next to the actual code, which
|
||||
means that they will be included when selecting text with the cursor or
|
||||
copying a code block to the clipboard. Thus, the usage of either `table`
|
||||
or `pymdownx-inline` is recommended.
|
||||
|
||||
<!-- md:option pymdownx.highlight.anchor_linenums -->
|
||||
|
||||
: <!-- md:version 8.1.0 --> :octicons-milestone-24:
|
||||
Default: `false` – If a code blocks contains line numbers, enabling this
|
||||
setting will wrap them with anchor links, so they can be hyperlinked and
|
||||
shared more easily:
|
||||
|
||||
``` yaml
|
||||
markdown_extensions:
|
||||
- pymdownx.highlight:
|
||||
anchor_linenums: true
|
||||
```
|
||||
|
||||
<!-- md:option pymdownx.highlight.line_spans -->
|
||||
|
||||
: <!-- md:default none --> When this option is set, each
|
||||
line of a code block is wrapped in a `span`, which is essential for features
|
||||
like line highlighting to work correctly:
|
||||
|
||||
``` yaml
|
||||
markdown_extensions:
|
||||
- pymdownx.highlight:
|
||||
line_spans: __span
|
||||
```
|
||||
|
||||
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.
|
||||
|
||||
See reference for usage:
|
||||
|
||||
- [Using code blocks]
|
||||
- [Adding a title]
|
||||
- [Adding line numbers]
|
||||
- [Highlighting specific lines]
|
||||
- [Custom syntax theme]
|
||||
|
||||
[Highlight]: https://facelessuser.github.io/pymdown-extensions/extensions/highlight/
|
||||
[CodeHilite]: python-markdown.md#codehilite
|
||||
[pymdownx.superfences]: #superfences
|
||||
[pymdownx.inlinehilite]: #inlinehilite
|
||||
[Pygments]: https://pygments.org
|
||||
[additional style sheet]: ../../customization.md#additional-css
|
||||
[Highlight.js]: https://highlightjs.org/
|
||||
[title]: ../../reference/code-blocks.md#adding-a-title
|
||||
[Adding line numbers]: ../../reference/code-blocks.md#adding-line-numbers
|
||||
[Using code blocks]: ../../reference/code-blocks.md#usage
|
||||
[Adding a title]: ../../reference/code-blocks.md#adding-a-title
|
||||
[Highlighting specific lines]: ../../reference/code-blocks.md#highlighting-specific-lines
|
||||
[Custom syntax theme]: ../../reference/code-blocks.md#custom-syntax-theme
|
||||
|
||||
### InlineHilite
|
||||
|
||||
<!-- md:version 5.0.0 -->
|
||||
<!-- md:extension [pymdownx.inlinehilite][InlineHilite] -->
|
||||
|
||||
The [InlineHilite] extension add support for syntax highlighting of inline code
|
||||
blocks. It's built on top of the [Highlight][pymdownx.highlight] extension, from
|
||||
which it sources its configuration. Enable it via `mkdocs.yml`:
|
||||
|
||||
``` yaml
|
||||
markdown_extensions:
|
||||
- pymdownx.highlight
|
||||
- pymdownx.inlinehilite
|
||||
```
|
||||
|
||||
The configuration options of this extension are not specific to Material for
|
||||
MkDocs, as they only impact the Markdown parsing stage. The only exception is
|
||||
the [`css_class`][InlineHilite options] option, which must not be changed. See the
|
||||
[InlineHilite documentation][InlineHilite] for guidance.
|
||||
|
||||
See reference for usage:
|
||||
|
||||
- [Highlighting inline code blocks]
|
||||
|
||||
[InlineHilite]: https://facelessuser.github.io/pymdown-extensions/extensions/inlinehilite/
|
||||
[InlineHilite options]: https://facelessuser.github.io/pymdown-extensions/extensions/inlinehilite/#options
|
||||
[pymdownx.highlight]: #highlight
|
||||
[Highlighting inline code blocks]: ../../reference/code-blocks.md#highlighting-inline-code-blocks
|
||||
|
||||
### Keys
|
||||
|
||||
<!-- md:version 1.0.0 -->
|
||||
<!-- md:extension [pymdownx.keys][Keys] -->
|
||||
|
||||
The [Keys] extension adds a simple syntax to allow for the rendering of keyboard
|
||||
keys and combinations, e.g. ++ctrl+alt+del++. Enable it via `mkdocs.yml`:
|
||||
|
||||
``` yaml
|
||||
markdown_extensions:
|
||||
- pymdownx.keys
|
||||
```
|
||||
|
||||
The configuration options of this extension are not specific to Material for
|
||||
MkDocs, as they only impact the Markdown parsing stage. The only exception is
|
||||
the [`class`][Keys options] option, which must not be changed. See the
|
||||
[Keys documentation][Keys] for more information.
|
||||
|
||||
See reference for usage:
|
||||
|
||||
- [Adding keyboard keys]
|
||||
|
||||
[Keys]: https://facelessuser.github.io/pymdown-extensions/extensions/keys/
|
||||
[Keys options]: https://facelessuser.github.io/pymdown-extensions/extensions/keys/#options
|
||||
[Adding keyboard keys]: ../../reference/formatting.md#adding-keyboard-keys
|
||||
|
||||
### SmartSymbols
|
||||
|
||||
<!-- md:version 0.1.0 -->
|
||||
<!-- md:extension [pymdownx.smartsymbols][SmartSymbols] -->
|
||||
|
||||
The [SmartSymbols] extension converts some sequences of characters into their
|
||||
corresponding symbols, e.g. copyright symbols or fractions. Enable it via
|
||||
`mkdocs.yml`:
|
||||
|
||||
``` yaml
|
||||
markdown_extensions:
|
||||
- pymdownx.smartsymbols
|
||||
```
|
||||
|
||||
The configuration options of this extension are not specific to Material for
|
||||
MkDocs, as they only impact the Markdown parsing stage. See the [SmartSymbols
|
||||
documentation][SmartSymbols] for guidance.
|
||||
|
||||
[SmartSymbols]: https://facelessuser.github.io/pymdown-extensions/extensions/smartsymbols/
|
||||
|
||||
### Snippets
|
||||
|
||||
<!-- md:version 0.1.0 -->
|
||||
<!-- md:extension [pymdownx.snippets][Snippets] -->
|
||||
|
||||
The [Snippets] extension adds the ability to embed content from arbitrary files
|
||||
into a document, including other documents or source files, by using a simple
|
||||
syntax. Enable it via `mkdocs.yml`:
|
||||
|
||||
``` yaml
|
||||
markdown_extensions:
|
||||
- pymdownx.snippets
|
||||
```
|
||||
|
||||
The configuration options of this extension are not specific to Material for
|
||||
MkDocs, as they only impact the Markdown parsing stage. See the [Snippets
|
||||
documentation][Snippets] for more information.
|
||||
|
||||
See reference for usage:
|
||||
|
||||
- [Adding a glossary]
|
||||
- [Embedding external files]
|
||||
|
||||
[Snippets]: https://facelessuser.github.io/pymdown-extensions/extensions/snippets/
|
||||
[Adding a glossary]: ../../reference/tooltips.md#adding-a-glossary
|
||||
[Embedding external files]: ../../reference/code-blocks.md#embedding-external-files
|
||||
|
||||
### SuperFences
|
||||
|
||||
<!-- md:version 0.1.0 -->
|
||||
<!-- md:extension [pymdownx.superfences][SuperFences] -->
|
||||
|
||||
The [SuperFences] extension allows for arbitrary nesting of code and content
|
||||
blocks inside each other, including admonitions, tabs, lists and all other
|
||||
elements. Enable it via `mkdocs.yml`:
|
||||
|
||||
``` yaml
|
||||
markdown_extensions:
|
||||
- pymdownx.superfences
|
||||
```
|
||||
|
||||
The following configuration options are supported:
|
||||
|
||||
<!-- md:option pymdownx.superfences.custom_fences -->
|
||||
|
||||
: <!-- md:default none --> This option allows to define a
|
||||
handler for custom fences, e.g. to preserve the definitions of [Mermaid.js]
|
||||
diagrams to be interpreted in the browser:
|
||||
|
||||
``` yaml
|
||||
markdown_extensions:
|
||||
- pymdownx.superfences:
|
||||
custom_fences:
|
||||
- name: mermaid
|
||||
class: mermaid
|
||||
format: !!python/name:pymdownx.superfences.fence_code_format
|
||||
```
|
||||
|
||||
Note that this will primarily prevent syntax highlighting from being
|
||||
applied. See the reference on [diagrams] to learn how Mermaid.js is
|
||||
integrated with Material for MkDocs.
|
||||
|
||||
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.
|
||||
|
||||
See reference for usage:
|
||||
|
||||
- [Using annotations]
|
||||
- [Using code blocks]
|
||||
- [Using content tabs]
|
||||
- [Using flowcharts]
|
||||
- [Using sequence diagrams]
|
||||
- [Using state diagrams]
|
||||
- [Using class diagrams]
|
||||
- [Using entity-relationship diagrams]
|
||||
|
||||
[SuperFences]: https://facelessuser.github.io/pymdown-extensions/extensions/superfences/
|
||||
[Fenced Code Blocks]: python-markdown.md#fenced-code-blocks
|
||||
[Mermaid.js]: https://mermaid-js.github.io/mermaid/
|
||||
[diagrams]: ../../reference/diagrams.md
|
||||
[Using annotations]: ../../reference/annotations.md#usage
|
||||
[Using content tabs]: ../../reference/content-tabs.md#usage
|
||||
[Using flowcharts]: ../../reference/diagrams.md#using-flowcharts
|
||||
[Using sequence diagrams]: ../../reference/diagrams.md#using-sequence-diagrams
|
||||
[Using state diagrams]: ../../reference/diagrams.md#using-state-diagrams
|
||||
[Using class diagrams]: ../../reference/diagrams.md#using-class-diagrams
|
||||
[Using entity-relationship diagrams]: ../../reference/diagrams.md#using-entity-relationship-diagrams
|
||||
|
||||
### Tabbed
|
||||
|
||||
<!-- md:version 5.0.0 -->
|
||||
<!-- md:extension [pymdownx.tabbed][Tabbed] -->
|
||||
|
||||
The [Tabbed] extension allows the usage of content tabs, a simple way to group
|
||||
related content and code blocks under accessible tabs. Enable it via
|
||||
`mkdocs.yml`:
|
||||
|
||||
``` yaml
|
||||
markdown_extensions:
|
||||
- pymdownx.tabbed:
|
||||
alternate_style: true
|
||||
```
|
||||
|
||||
The following configuration options are supported:
|
||||
|
||||
<!-- md:option pymdownx.tabbed.alternate_style -->
|
||||
|
||||
: <!-- md:version 7.3.1 --> <!-- md:default `false` -->
|
||||
<!-- md:flag required --> This option enables the content tabs
|
||||
[alternate style], which has [better behavior on mobile viewports], and is
|
||||
the only supported style:
|
||||
|
||||
``` yaml
|
||||
markdown_extensions:
|
||||
- pymdownx.tabbed:
|
||||
alternate_style: true
|
||||
```
|
||||
|
||||
<!-- md:option pymdownx.tabbed.combine_header_slug -->
|
||||
|
||||
: <!-- md:default `false` --> This option enables the content tabs'
|
||||
[`combine_header_slug` style] flag, which prepends the id of the header to
|
||||
the id of the tab:
|
||||
|
||||
``` yaml
|
||||
markdown_extensions:
|
||||
- pymdownx.tabbed:
|
||||
combine_header_slug: true
|
||||
```
|
||||
|
||||
<!-- md:option pymdownx.tabbed.slugify -->
|
||||
|
||||
: <!-- md:default `None` --> This option allows for
|
||||
customization of the slug function. For some languages, the default may not
|
||||
produce good and readable identifiers – consider using another slug function
|
||||
like for example those from [Python Markdown Extensions][Slugs]:
|
||||
|
||||
=== "Unicode"
|
||||
|
||||
``` yaml
|
||||
markdown_extensions:
|
||||
- pymdownx.tabbed:
|
||||
slugify: !!python/object/apply:pymdownx.slugs.slugify
|
||||
kwds:
|
||||
case: lower
|
||||
```
|
||||
|
||||
=== "Unicode, case-sensitive"
|
||||
|
||||
``` yaml
|
||||
markdown_extensions:
|
||||
- pymdownx.tabbed:
|
||||
slugify: !!python/object/apply:pymdownx.slugs.slugify {}
|
||||
```
|
||||
|
||||
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.
|
||||
|
||||
See reference for usage:
|
||||
|
||||
- [Grouping code blocks]
|
||||
- [Grouping other content]
|
||||
- [Embedded content]
|
||||
|
||||
[Tabbed]: https://facelessuser.github.io/pymdown-extensions/extensions/tabbed/
|
||||
[alternate style]: https://facelessuser.github.io/pymdown-extensions/extensions/tabbed/#alternate-style
|
||||
[combine_header_slug style]: https://facelessuser.github.io/pymdown-extensions/extensions/tabbed/#tab-ids
|
||||
[better behavior on mobile viewports]: https://x.com/squidfunk/status/1424740370596958214
|
||||
[Grouping code blocks]: ../../reference/content-tabs.md#grouping-code-blocks
|
||||
[Grouping other content]: ../../reference/content-tabs.md#grouping-other-content
|
||||
[Embedded content]: ../../reference/content-tabs.md#embedded-content
|
||||
[Slugs]: https://facelessuser.github.io/pymdown-extensions/extras/slugs/
|
||||
|
||||
### Tasklist
|
||||
|
||||
<!-- md:version 1.0.0 -->
|
||||
<!-- md:extension [pymdownx.tasklist][Tasklist] -->
|
||||
|
||||
The [Tasklist] extension allows for the usage of [GitHub Flavored Markdown]
|
||||
inspired [task lists][Tasklist specification], following the same syntactical
|
||||
conventions. Enable it via `mkdocs.yml`:
|
||||
|
||||
``` yaml
|
||||
markdown_extensions:
|
||||
- pymdownx.tasklist:
|
||||
custom_checkbox: true
|
||||
```
|
||||
|
||||
The following configuration options are supported:
|
||||
|
||||
<!-- md:option pymdownx.tasklist.custom_checkbox -->
|
||||
|
||||
: <!-- md:default `false` --> This option toggles the rendering
|
||||
style of checkboxes, replacing native checkbox styles with beautiful icons,
|
||||
and is therefore recommended:
|
||||
|
||||
``` yaml
|
||||
markdown_extensions:
|
||||
- pymdownx.tasklist:
|
||||
custom_checkbox: true
|
||||
```
|
||||
|
||||
<!-- md:option pymdownx.tasklist.clickable_checkbox -->
|
||||
|
||||
: <!-- md:default `false` --> This option toggles whether
|
||||
checkboxes are clickable. As the state is not persisted, the use of this
|
||||
option is _rather discouraged_ from a user experience perspective:
|
||||
|
||||
``` yaml
|
||||
markdown_extensions:
|
||||
- pymdownx.tasklist:
|
||||
clickable_checkbox: 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.
|
||||
|
||||
See reference for usage:
|
||||
|
||||
- [Using task lists]
|
||||
|
||||
[Tasklist]: https://facelessuser.github.io/pymdown-extensions/extensions/tasklist/
|
||||
[GitHub Flavored Markdown]: https://github.github.com/gfm/
|
||||
[Tasklist specification]: https://github.github.com/gfm/#task-list-items-extension-
|
||||
[Using task lists]: ../../reference/lists.md#using-task-lists
|
||||
@@ -0,0 +1,347 @@
|
||||
# Python Markdown
|
||||
|
||||
Material for MkDocs supports a large number of [Python Markdown] extensions,
|
||||
which is part of what makes it so attractive for technical writing. Following
|
||||
is a list of all supported extensions, linking to the relevant sections of the
|
||||
reference for which features they need to be enabled.
|
||||
|
||||
[Python Markdown]: https://python-markdown.github.io/
|
||||
|
||||
## Supported extensions
|
||||
|
||||
### Abbreviations
|
||||
|
||||
<!-- md:version 1.0.0 -->
|
||||
<!-- md:extension [abbr][Abbreviations] -->
|
||||
|
||||
The [Abbreviations] extension adds the ability to add a small tooltip to an
|
||||
element, by wrapping it with an `abbr` tag. Only plain text (no markup) is
|
||||
supported. Enable it via `mkdocs.yml`:
|
||||
|
||||
``` yaml
|
||||
markdown_extensions:
|
||||
- abbr
|
||||
```
|
||||
|
||||
No configuration options are available. See reference for usage:
|
||||
|
||||
- [Adding abbreviations]
|
||||
- [Adding a glossary]
|
||||
|
||||
[Abbreviations]: https://python-markdown.github.io/extensions/abbreviations/
|
||||
[Adding abbreviations]: ../../reference/tooltips.md#adding-abbreviations
|
||||
[Adding a glossary]: ../../reference/tooltips.md#adding-a-glossary
|
||||
|
||||
### Admonition
|
||||
|
||||
<!-- md:version 0.1.0 -->
|
||||
<!-- md:extension [admonition][Admonition] -->
|
||||
|
||||
The [Admonition] extension adds support for admonitions, more commonly known as
|
||||
_call-outs_, which can be defined in Markdown by using a simple syntax. Enable
|
||||
it via `mkdocs.yml`:
|
||||
|
||||
``` yaml
|
||||
markdown_extensions:
|
||||
- admonition
|
||||
```
|
||||
|
||||
No configuration options are available. See reference for usage:
|
||||
|
||||
- [Adding admonitions]
|
||||
- [Changing the title]
|
||||
- [Removing the title]
|
||||
- [Supported types]
|
||||
|
||||
[Admonition]: https://python-markdown.github.io/extensions/admonition/
|
||||
[Adding admonitions]: ../../reference/admonitions.md#usage
|
||||
[Changing the title]: ../../reference/admonitions.md#changing-the-title
|
||||
[Removing the title]: ../../reference/admonitions.md#removing-the-title
|
||||
[Supported types]: ../../reference/admonitions.md#supported-types
|
||||
|
||||
### Attribute Lists
|
||||
|
||||
<!-- md:version 0.1.0 -->
|
||||
<!-- md:extension [attr_list][Attribute Lists] -->
|
||||
|
||||
The [Attribute Lists] extension allows to add HTML attributes and CSS classes
|
||||
to [almost every][Attribute Lists limitations] Markdown inline- and block-level
|
||||
element with a special syntax. Enable it via `mkdocs.yml`:
|
||||
|
||||
``` yaml
|
||||
markdown_extensions:
|
||||
- attr_list
|
||||
```
|
||||
|
||||
No configuration options are available. See reference for usage:
|
||||
|
||||
- [Using annotations]
|
||||
- [Using grids]
|
||||
- [Adding buttons]
|
||||
- [Adding tooltips]
|
||||
- [Using icons with colors]
|
||||
- [Using icons with animations]
|
||||
- [Image alignment]
|
||||
- [Image lazy-loading]
|
||||
|
||||
[Attribute Lists]: https://python-markdown.github.io/extensions/attr_list/
|
||||
[Attribute Lists limitations]: https://python-markdown.github.io/extensions/attr_list/#limitations
|
||||
[Using grids]: ../../reference/grids.md#using-grids
|
||||
[Adding buttons]: ../../reference/buttons.md#adding-buttons
|
||||
[Adding tooltips]: ../../reference/tooltips.md#adding-tooltips
|
||||
[Using icons with colors]: ../../reference/icons-emojis.md#with-colors
|
||||
[Using icons with animations]: ../../reference/icons-emojis.md#with-animations
|
||||
[Image alignment]: ../../reference/images.md#image-alignment
|
||||
[Image lazy-loading]: ../../reference/images.md#image-lazy-loading
|
||||
|
||||
### Definition Lists
|
||||
|
||||
<!-- md:version 1.1.0 -->
|
||||
<!-- md:extension [def_list][Definition Lists] -->
|
||||
|
||||
The [Definition Lists] extension adds the ability to add definition lists (more
|
||||
commonly known as [description lists] – `dl` in HTML) via Markdown to a
|
||||
document. Enable it via `mkdocs.yml`:
|
||||
|
||||
``` yaml
|
||||
markdown_extensions:
|
||||
- def_list
|
||||
```
|
||||
|
||||
No configuration options are available. See reference for usage:
|
||||
|
||||
- [Using definition lists]
|
||||
|
||||
[Definition Lists]: https://python-markdown.github.io/extensions/definition_lists/
|
||||
[description lists]: https://developer.mozilla.org/en-US/docs/Web/HTML/Element/dl
|
||||
[Using definition lists]: ../../reference/lists.md#using-definition-lists
|
||||
|
||||
### Footnotes
|
||||
|
||||
<!-- md:version 1.0.0 -->
|
||||
<!-- md:extension [footnotes][Footnotes] -->
|
||||
|
||||
The [Footnotes] extension allows to define inline footnotes, which are then
|
||||
rendered below all Markdown content of a document. Enable it via `mkdocs.yml`:
|
||||
|
||||
``` yaml
|
||||
markdown_extensions:
|
||||
- footnotes
|
||||
```
|
||||
|
||||
No configuration options are supported. See reference for usage:
|
||||
|
||||
- [Adding footnote references]
|
||||
- [Adding footnote content]
|
||||
|
||||
[Footnotes]: https://python-markdown.github.io/extensions/footnotes/
|
||||
[Adding footnote references]: ../../reference/footnotes.md#adding-footnote-references
|
||||
[Adding footnote content]: ../../reference/footnotes.md#adding-footnote-content
|
||||
|
||||
### Markdown in HTML
|
||||
|
||||
<!-- md:version 0.1.0 -->
|
||||
<!-- md:extension [md_in_html][Markdown in HTML] -->
|
||||
|
||||
The [Markdown in HTML] extension allows for writing Markdown inside of HTML,
|
||||
which is useful for wrapping Markdown content with custom elements. Enable it
|
||||
via `mkdocs.yml`:
|
||||
|
||||
``` yaml
|
||||
markdown_extensions:
|
||||
- md_in_html
|
||||
```
|
||||
|
||||
> By default, Markdown ignores any content within a raw HTML block-level
|
||||
> element. With the `md_in_html` extension enabled, the content of a raw HTML
|
||||
> block-level element can be parsed as Markdown by including a `markdown`
|
||||
> attribute on the opening tag. The `markdown` attribute will be stripped from
|
||||
> the output, while all other attributes will be preserved.
|
||||
|
||||
No configuration options are available. See reference for usage:
|
||||
|
||||
- [Using annotations]
|
||||
- [Using grids]
|
||||
- [Image captions]
|
||||
|
||||
[Markdown in HTML]: https://python-markdown.github.io/extensions/md_in_html/
|
||||
[Using annotations]: ../../reference/annotations.md#usage
|
||||
[Using grids]: ../../reference/grids.md#usage
|
||||
[Image captions]: ../../reference/images.md#image-captions
|
||||
|
||||
### Table of Contents
|
||||
|
||||
<!-- md:version 0.1.0 -->
|
||||
<!-- md:extension [toc][Table of Contents] -->
|
||||
|
||||
The [Table of Contents] extension automatically generates a table of contents
|
||||
from a document, which Material for MkDocs will render as part of the resulting
|
||||
page. Enable it via `mkdocs.yml`:
|
||||
|
||||
``` yaml
|
||||
markdown_extensions:
|
||||
- toc:
|
||||
permalink: true
|
||||
```
|
||||
|
||||
The following configuration options are supported:
|
||||
|
||||
<!-- md:option toc.title -->
|
||||
|
||||
: <!-- md:version 7.3.5 --> <!-- md:default computed --> –
|
||||
This option sets the title of the table of contents in the right navigation
|
||||
sidebar, which is normally automatically sourced from the translations for
|
||||
the [site language] as set in `mkdocs.yml`:
|
||||
|
||||
``` yaml
|
||||
markdown_extensions:
|
||||
- toc:
|
||||
title: On this page
|
||||
```
|
||||
|
||||
<!-- md:option toc.permalink -->
|
||||
|
||||
: <!-- md:default `false` --> This option adds an anchor link
|
||||
containing the paragraph symbol `¶` or another custom symbol at the end of
|
||||
each headline, exactly like on the page you're currently viewing, which
|
||||
Material for MkDocs will make appear on hover:
|
||||
|
||||
=== "¶"
|
||||
|
||||
``` yaml
|
||||
markdown_extensions:
|
||||
- toc:
|
||||
permalink: true
|
||||
```
|
||||
|
||||
=== "⚓︎"
|
||||
|
||||
``` yaml
|
||||
markdown_extensions:
|
||||
- toc:
|
||||
permalink: ⚓︎
|
||||
```
|
||||
|
||||
<!-- md:option toc.permalink_title -->
|
||||
|
||||
: <!-- md:default `Permanent link` --> This option sets the
|
||||
title of the anchor link which is shown on hover and read by screen readers.
|
||||
For accessibility reasons, it might be beneficial to change it to a more
|
||||
discernable name, stating that the anchor links to the section itself:
|
||||
|
||||
``` yaml
|
||||
markdown_extensions:
|
||||
- toc:
|
||||
permalink_title: Anchor link to this section for reference
|
||||
```
|
||||
|
||||
<!-- md:option toc.slugify -->
|
||||
|
||||
: <!-- md:default `toc.slugify` --> This option allows for
|
||||
customization of the slug function. For some languages, the default may not
|
||||
produce good and readable identifiers – consider using another slug function
|
||||
like for example those from [Python Markdown Extensions][Slugs]:
|
||||
|
||||
=== "Unicode"
|
||||
|
||||
``` yaml
|
||||
markdown_extensions:
|
||||
- toc:
|
||||
slugify: !!python/object/apply:pymdownx.slugs.slugify
|
||||
kwds:
|
||||
case: lower
|
||||
```
|
||||
|
||||
=== "Unicode, case-sensitive"
|
||||
|
||||
``` yaml
|
||||
markdown_extensions:
|
||||
- toc:
|
||||
slugify: !!python/object/apply:pymdownx.slugs.slugify {}
|
||||
```
|
||||
|
||||
<!-- md:option toc.toc_depth -->
|
||||
|
||||
: <!-- md:default `6` --> Define the range of levels to be
|
||||
included in the table of contents. This may be useful for project
|
||||
documentation with deeply structured headings to decrease the length of the
|
||||
table of contents, or to remove the table of contents altogether:
|
||||
|
||||
=== "Hide levels 4-6"
|
||||
|
||||
``` yaml
|
||||
markdown_extensions:
|
||||
- toc:
|
||||
toc_depth: 3
|
||||
```
|
||||
|
||||
=== "Hide table of contents"
|
||||
|
||||
``` yaml
|
||||
markdown_extensions:
|
||||
- toc:
|
||||
toc_depth: 0
|
||||
```
|
||||
|
||||
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.
|
||||
|
||||
[Table of Contents]: https://python-markdown.github.io/extensions/toc/
|
||||
[site language]: ../changing-the-language.md#site-language
|
||||
[Slugs]: https://facelessuser.github.io/pymdown-extensions/extras/slugs/
|
||||
|
||||
### Tables
|
||||
|
||||
<!-- md:version 0.1.0 -->
|
||||
<!-- md:extension [tables][Tables] -->
|
||||
|
||||
The [Tables] extension adds the ability to create tables in Markdown by using a
|
||||
simple syntax. Enable it via `mkdocs.yml` (albeit it should be enabled by
|
||||
default):
|
||||
|
||||
``` yaml
|
||||
markdown_extensions:
|
||||
- tables
|
||||
```
|
||||
|
||||
No configuration options are available. See reference for usage:
|
||||
|
||||
- [Using data tables]
|
||||
- [Column alignment]
|
||||
|
||||
[Tables]: https://python-markdown.github.io/extensions/tables/
|
||||
[Using data tables]: ../../reference/data-tables.md#usage
|
||||
[Column alignment]: ../../reference/data-tables.md#column-alignment
|
||||
|
||||
## Superseded extensions
|
||||
|
||||
The following [Python Markdown] extensions are not (or might not be) supported
|
||||
anymore, and are therefore not recommended for use. Instead, the alternatives
|
||||
should be considered.
|
||||
|
||||
### Fenced Code Blocks
|
||||
|
||||
<!-- md:version 0.1.0 -->
|
||||
<!-- md:extension [fenced_code_blocks][Fenced Code Blocks] -->
|
||||
|
||||
Superseded by [SuperFences]. This extension might still work, but the
|
||||
[SuperFences] extension is superior in many ways, as it allows for arbitrary
|
||||
nesting, and is therefore recommended.
|
||||
|
||||
[Fenced Code Blocks]: https://python-markdown.github.io/extensions/fenced_code_blocks/
|
||||
[SuperFences]: https://facelessuser.github.io/pymdown-extensions/extensions/superfences/
|
||||
|
||||
### CodeHilite
|
||||
|
||||
<!-- md:version 0.1.0 -->
|
||||
<!-- md:extension [codehilite][CodeHilite] -->
|
||||
|
||||
Superseded by [Highlight]. Support for CodeHilite was dropped in
|
||||
<!-- md:version 6.0.0 -->, as [Highlight] has a better integration with other
|
||||
essential extensions like [SuperFences] and [InlineHilite].
|
||||
|
||||
[CodeHilite]: https://python-markdown.github.io/extensions/code_hilite/
|
||||
[CodeHilite support]: https://github.com/squidfunk/mkdocs-material/releases/tag/0.1.0
|
||||
[Highlight]: https://facelessuser.github.io/pymdown-extensions/extensions/highlight/
|
||||
[InlineHilite]: https://facelessuser.github.io/pymdown-extensions/extensions/inlinehilite/
|
||||
@@ -0,0 +1,90 @@
|
||||
# Setup
|
||||
|
||||
Material for MkDocs offers a wide range of options for customizing your
|
||||
documentation. In this section, we will explain how you can create a meaningful
|
||||
structure for your site, change the look and feel, add a blog and comment system,
|
||||
and build a highly optimized site.
|
||||
|
||||
## Site structure
|
||||
|
||||
Set up and customize the structure of your documentation by configuring the
|
||||
header and footer to your taste, choosing among many modes of navigation,
|
||||
setting up site search, and more.
|
||||
|
||||
<div class="grid cards" markdown>
|
||||
|
||||
- :fontawesome-solid-earth-americas: __[Language]__ – Choose out of the 60+ supported languages or add a new one
|
||||
- :material-page-layout-sidebar-left: __[Navigation]__ – Create a clear, concise, and comprehensive navigation structure
|
||||
- :material-page-layout-header: __[Header]__ – Customize the behavior of the header, add an announcement bar
|
||||
- :material-page-layout-footer: __[Footer]__ – Add links to your social media profiles or websites in the footer
|
||||
- :material-tab-search: __[Search]__ – Set up and configure search, running entirely in the user's browser
|
||||
- :material-tag-plus-outline: __[Tags]__ – Categorize your pages with tags and group related pages
|
||||
|
||||
</div>
|
||||
|
||||
[Language]: changing-the-language.md
|
||||
[Navigation]: setting-up-navigation.md
|
||||
[Header]: setting-up-the-header.md
|
||||
[Footer]: setting-up-the-footer.md
|
||||
[Search]: setting-up-site-search.md
|
||||
[Tags]: setting-up-tags.md
|
||||
|
||||
|
||||
## Appearance
|
||||
|
||||
Match your brand's colors, fonts, icons, logo, and more with a few lines of
|
||||
configuration – Material for MkDocs makes it easy to extend the basic
|
||||
configuration or alter the appearance.
|
||||
|
||||
<div class="grid cards" markdown>
|
||||
|
||||
- :material-brush-variant: __[Colors]__ – Change colors with an existing color palette or customize with CSS
|
||||
- :material-format-font: __[Fonts]__ – Choose among 1,000 Google Fonts or load self-hosted fonts
|
||||
- :material-google-downasaur: __[Logo & Icons]__ – Change the logo, use any of the 8,000+ icons, or add new ones
|
||||
- :material-cards-variant: __[Social Cards]__ – Automatically create social media previews when sharing links
|
||||
|
||||
</div>
|
||||
|
||||
[Colors]: changing-the-colors.md
|
||||
[Fonts]: changing-the-fonts.md
|
||||
[Logo & Icons]: changing-the-logo-and-icons.md
|
||||
[Social Cards]: setting-up-social-cards.md
|
||||
|
||||
## Content
|
||||
|
||||
Create a blog, integrate a comment system, connect a git repository, and set up
|
||||
versioned documentation that matches your project's versioning methodology.
|
||||
|
||||
<div class="grid cards" markdown>
|
||||
|
||||
- :material-book-open-outline: __[Blog]__ – Set up a standalone blog or host it alongside your documentation
|
||||
- :material-comment-text-outline: __[Comment System]__ – Add a third-party comment system on any page or footer
|
||||
- :octicons-versions-16: __[Versioning]__ – Deploy multiple versions by integrating with external utilities
|
||||
- :octicons-repo-16: __[Repository]__ – Connect your documentation to your git repository
|
||||
|
||||
</div>
|
||||
|
||||
[Blog]: setting-up-a-blog.md
|
||||
[Comment System]: adding-a-comment-system.md
|
||||
[Versioning]: setting-up-versioning.md
|
||||
[Repository]: adding-a-git-repository.md
|
||||
|
||||
## Optimization
|
||||
|
||||
Add site analytics and build an optimized site by adding automatic image
|
||||
compression, complying with GDPR data privacy regulations, and making it
|
||||
offline-capable.
|
||||
|
||||
<div class="grid cards" markdown>
|
||||
|
||||
- :material-google-analytics: __[Site analytics]__ – Learn how your users experience your documentation
|
||||
- :material-screwdriver: __[Optimized site]__ – Create optimized sites that rank great on search engines
|
||||
- :octicons-lock-16: __[Data Privacy]__ – Ensure compliance with data privacy regulations
|
||||
- :octicons-cloud-offline-16: __[Offline usage]__ – Build an online and offline-capable documentation
|
||||
|
||||
</div>
|
||||
|
||||
[Site analytics]: setting-up-site-analytics.md
|
||||
[Optimized site]: building-an-optimized-site.md
|
||||
[Data Privacy]: ensuring-data-privacy.md
|
||||
[Offline usage]: building-for-offline-usage.md
|
||||
@@ -0,0 +1,677 @@
|
||||
# Setting up a blog
|
||||
|
||||
Material for MkDocs makes it very easy to build a blog, either as a sidecar to
|
||||
your documentation or standalone. Focus on your content while the engine does
|
||||
all the heavy lifting, automatically generating [archive] and [category]
|
||||
indexes, [post slugs], configurable [pagination] and more.
|
||||
|
||||
---
|
||||
|
||||
__Check out our [blog], which is created with the new [built-in blog plugin]!__
|
||||
|
||||
[archive]: ../plugins/blog.md#archive
|
||||
[category]: ../plugins/blog.md#categories
|
||||
[post slugs]: ../plugins/blog.md#config.post_url_format
|
||||
[pagination]: ../plugins/blog.md#pagination
|
||||
[blog]: ../blog/index.md
|
||||
|
||||
## Configuration
|
||||
|
||||
### Built-in blog plugin
|
||||
|
||||
<!-- md:version 9.2.0 -->
|
||||
<!-- md:plugin -->
|
||||
<!-- md:flag experimental -->
|
||||
<!-- md:demo create-blog -->
|
||||
|
||||
The built-in blog plugin adds support for building a blog from a folder of
|
||||
posts, which are annotated with dates and other structured data. First, add the
|
||||
following lines to `mkdocs.yml`:
|
||||
|
||||
``` yaml
|
||||
plugins:
|
||||
- blog
|
||||
```
|
||||
|
||||
If you do not have a navigation (`nav`) definition in your `mkdocs.yml` then
|
||||
there is nothing else to do there as the blog plugin will add navigation
|
||||
automatically. If you do have a navigation defined then you need to add *the
|
||||
blog index page only* to it. You need not and should not add the individual
|
||||
blog posts. For example:
|
||||
|
||||
```yaml
|
||||
nav:
|
||||
- index.md
|
||||
- Blog:
|
||||
- blog/index.md
|
||||
```
|
||||
|
||||
For a list of all settings, please consult the [plugin documentation].
|
||||
|
||||
[plugin documentation]: ../plugins/blog.md
|
||||
[built-in blog plugin]: ../plugins/blog.md
|
||||
|
||||
### RSS
|
||||
|
||||
<!-- md:version 9.2.0 -->
|
||||
<!-- md:plugin [rss] -->
|
||||
|
||||
The [built-in blog plugin] integrates seamlessly with the [RSS plugin][rss],
|
||||
which provides a simple way to add an RSS feed to your blog (or to your whole
|
||||
documentation). Install it with `pip`:
|
||||
|
||||
```
|
||||
pip install mkdocs-rss-plugin
|
||||
```
|
||||
|
||||
Then, add the following lines to `mkdocs.yml`:
|
||||
|
||||
``` yaml
|
||||
plugins:
|
||||
- rss:
|
||||
match_path: blog/posts/.* # (1)!
|
||||
date_from_meta:
|
||||
as_creation: date
|
||||
categories:
|
||||
- categories
|
||||
- tags # (2)!
|
||||
```
|
||||
|
||||
1. The RSS plugin allows to filter for URLs to be included in the feed. In
|
||||
this example, only blog posts will be part of the feed.
|
||||
|
||||
2. If you want to include a post's categories as well as its tags in the feed,
|
||||
add both `categories` and `tags` here.
|
||||
|
||||
The following configuration options are supported:
|
||||
|
||||
<!-- md:option rss.enabled -->
|
||||
|
||||
: <!-- md:default `true` --> This option specifies whether
|
||||
the plugin is enabled when building your project. If you want to speed up
|
||||
local builds, you can use an [environment variable][mkdocs.env]:
|
||||
|
||||
``` yaml
|
||||
plugins:
|
||||
- rss:
|
||||
enabled: !ENV [CI, false]
|
||||
```
|
||||
|
||||
<!-- md:option rss.match_path -->
|
||||
|
||||
: <!-- md:default `.*` --> This option specifies which
|
||||
pages should be included in the feed. For example, to only include blog
|
||||
posts in the feed, use the following regular expression:
|
||||
|
||||
``` yaml
|
||||
plugins:
|
||||
- rss:
|
||||
match_path: blog/posts/.*
|
||||
```
|
||||
|
||||
<!-- md:option rss.date_from_meta -->
|
||||
|
||||
: <!-- md:default none --> This option specifies which
|
||||
front matter property should be used as a creation date of a page in the
|
||||
feed. It's recommended to use the `date` property:
|
||||
|
||||
``` yaml
|
||||
plugins:
|
||||
- rss:
|
||||
date_from_meta:
|
||||
as_creation: date
|
||||
```
|
||||
|
||||
<!-- md:option rss.categories -->
|
||||
|
||||
: <!-- md:default none --> This option specifies which
|
||||
front matter properties are used as categories as part of the feed. If you
|
||||
use [categories] and [tags], add both with the following lines:
|
||||
|
||||
``` yaml
|
||||
plugins:
|
||||
- rss:
|
||||
categories:
|
||||
- categories
|
||||
- tags
|
||||
```
|
||||
|
||||
<!-- md:option rss.comments_path -->
|
||||
|
||||
: <!-- md:default none --> This option specifies the anchor
|
||||
at which comments for a post or page can be found. If you've integrated a
|
||||
[comment system], add the following lines:
|
||||
|
||||
``` yaml
|
||||
plugins:
|
||||
- rss:
|
||||
comments_path: "#__comments"
|
||||
```
|
||||
|
||||
Material for MkDocs will automatically add the [necessary metadata] to your site
|
||||
which will make the RSS feed discoverable by browsers and feed readers.
|
||||
|
||||
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.
|
||||
|
||||
[rss]: https://guts.github.io/mkdocs-rss-plugin/
|
||||
[categories]: ../plugins/blog.md#categories
|
||||
[tags]: setting-up-tags.md#built-in-tags-plugin
|
||||
[comment system]: adding-a-comment-system.md
|
||||
[necessary metadata]: https://guts.github.io/mkdocs-rss-plugin/configuration/#integration
|
||||
[theme extension]: ../customization.md
|
||||
|
||||
### Blog only
|
||||
|
||||
You might need to build a pure blog without any documentation.
|
||||
In this case, you can create a folder tree like this:
|
||||
|
||||
``` { .sh .no-copy }
|
||||
.
|
||||
├─ docs/
|
||||
│ ├─ posts/ # (1)!
|
||||
│ ├─ .authors.yml
|
||||
│ └─ index.md
|
||||
└─ mkdocs.yml
|
||||
```
|
||||
|
||||
1. Notice that the `posts` directory is in the root of `docs` without
|
||||
intermediate `blog` directory.
|
||||
|
||||
And add the following lines to `mkdocs.yml`:
|
||||
|
||||
``` yaml
|
||||
plugins:
|
||||
- blog:
|
||||
blog_dir: . # (1)!
|
||||
```
|
||||
|
||||
1. Please see the [plugin documentation] for more information about the
|
||||
[`blog_dir`][blog_dir] setting.
|
||||
|
||||
With this configuration, the url of the blog post will be `/<post_slug>`
|
||||
instead of `/blog/<post_slug>`.
|
||||
|
||||
## Usage
|
||||
|
||||
### Writing your first post
|
||||
|
||||
After you've successfully set up the [built-in blog plugin], it's time to write
|
||||
your first post. The plugin doesn't assume any specific directory structure, so
|
||||
you're completely free in how you organize your posts, as long as they are all
|
||||
located inside the `posts` directory:
|
||||
|
||||
``` { .sh .no-copy }
|
||||
.
|
||||
├─ docs/
|
||||
│ └─ blog/
|
||||
│ ├─ posts/
|
||||
│ │ └─ hello-world.md # (1)!
|
||||
│ └─ index.md
|
||||
└─ mkdocs.yml
|
||||
```
|
||||
|
||||
1. If you'd like to arrange posts differently, you're free to do so. The URLs
|
||||
are built from the format specified in [`post_url_format`][post slugs] and
|
||||
the titles and dates of posts, no matter how they are organized
|
||||
inside the `posts` directory.
|
||||
|
||||
Create a new file called `hello-world.md` and add the following lines:
|
||||
|
||||
``` yaml
|
||||
---
|
||||
draft: true # (1)!
|
||||
date: 2024-01-31 # (2)!
|
||||
categories:
|
||||
- Hello
|
||||
- World
|
||||
---
|
||||
|
||||
# Hello world!
|
||||
...
|
||||
```
|
||||
|
||||
1. If you mark a post as a [draft], a red marker appears next to the post date
|
||||
on index pages. When the site is built, drafts are not included in the
|
||||
output. [This behavior can be changed], e.g. for rendering drafts when
|
||||
building deploy previews.
|
||||
|
||||
2. If you wish to provide multiple dates, you can use the following syntax,
|
||||
allowing you to define a date when you last updated the blog post +
|
||||
further custom dates you can add to the template:
|
||||
|
||||
``` yaml
|
||||
---
|
||||
date:
|
||||
created: 2022-01-31
|
||||
updated: 2022-02-02
|
||||
---
|
||||
|
||||
# Hello world!
|
||||
```
|
||||
|
||||
Note that the creation date __must__ be set under `date.created`, as each
|
||||
blog post must have a creation date set.
|
||||
|
||||
When you spin up the [live preview server], you should be greeted by your first
|
||||
post! You'll also realize, that [archive] and [category] indexes have been
|
||||
automatically generated for you.
|
||||
|
||||
[draft]: ../plugins/blog.md#drafts
|
||||
[This behavior can be changed]: ../plugins/blog.md#config.draft
|
||||
[live preview server]: ../creating-your-site.md#previewing-as-you-write
|
||||
|
||||
#### Adding an excerpt
|
||||
|
||||
The blog index, as well as [archive] and [category] indexes can either list the
|
||||
entire content of each post, or excerpts of posts. An excerpt can be created by
|
||||
adding a `<!-- more -->` separator after the first few paragraphs of a post:
|
||||
|
||||
``` py
|
||||
# Hello world!
|
||||
|
||||
Lorem ipsum dolor sit amet, consectetur adipiscing elit. Nulla et euismod
|
||||
nulla. Curabitur feugiat, tortor non consequat finibus, justo purus auctor
|
||||
massa, nec semper lorem quam in massa.
|
||||
|
||||
<!-- more -->
|
||||
...
|
||||
```
|
||||
|
||||
When the [built-in blog plugin] generates all indexes, the content before the
|
||||
[excerpt separator] is automatically extracted, allowing the user to start
|
||||
reading a post before deciding to jump in.
|
||||
|
||||
[excerpt separator]: ../plugins/blog.md#config.post_excerpt_separator
|
||||
|
||||
#### Adding authors
|
||||
|
||||
In order to add a little more personality to your posts, you can associate each
|
||||
post with one or multiple [authors]. First, create the
|
||||
[`.authors.yml`][authors_file] file in your blog directory, and add an author:
|
||||
|
||||
``` yaml
|
||||
authors:
|
||||
squidfunk:
|
||||
name: Martin Donath
|
||||
description: Creator
|
||||
avatar: https://github.com/squidfunk.png
|
||||
```
|
||||
|
||||
The [`.authors.yml`][authors_file] file associates each author with an
|
||||
identifier (in this example `squidfunk`), which can then be used in posts.
|
||||
Different attributes can be configured. For a list of all possible attributes,
|
||||
please consult the [`authors_file`][authors_file] documentation.
|
||||
|
||||
Now, you can assign one or more authors to a post by referencing their
|
||||
identifiers in the front matter of the Markdown file under the `authors`
|
||||
property. For each author, a small profile is rendered in the left sidebar of
|
||||
each post, as well as in post excerpts on index pages:
|
||||
|
||||
``` yaml
|
||||
---
|
||||
date: 2024-01-31
|
||||
authors:
|
||||
- squidfunk
|
||||
...
|
||||
---
|
||||
|
||||
# Hello world!
|
||||
...
|
||||
```
|
||||
|
||||
[authors]: ../plugins/blog.md#authors
|
||||
[authors_file]: ../plugins/blog.md#config.authors_file
|
||||
|
||||
#### Adding author profiles
|
||||
|
||||
<!-- md:version 9.7.0 -->
|
||||
<!-- md:flag experimental -->
|
||||
|
||||
If you wish to add a dedicated page for each author, you can enable author
|
||||
profiles by setting the [`authors_profiles`][authors_profiles] configuration
|
||||
option to `true`. Just add the following lines to `mkdocs.yml`:
|
||||
|
||||
``` yaml
|
||||
plugins:
|
||||
- blog:
|
||||
authors_profiles: true
|
||||
```
|
||||
|
||||
If you combine this with [custom index pages], you can create a dedicated page
|
||||
for each author with a short description, social media links, etc. – basically
|
||||
anything you can write in Markdown. The list of posts is then appended after
|
||||
the content of the page.
|
||||
|
||||
[authors_profiles]: ../plugins/blog.md#config.authors_profiles
|
||||
[custom index pages]: #custom-index-pages
|
||||
|
||||
#### Adding categories
|
||||
|
||||
Categories are an excellent way for grouping your posts thematically on
|
||||
dedicated index pages. This way, a user interested in a specific topic can
|
||||
explore all of your posts on this topic. Make sure [categories] are enabled and
|
||||
add them to the front matter `categories` property:
|
||||
|
||||
``` yaml
|
||||
---
|
||||
date: 2024-01-31
|
||||
categories:
|
||||
- Hello
|
||||
- World
|
||||
---
|
||||
|
||||
# Hello world!
|
||||
...
|
||||
```
|
||||
|
||||
If you want to save yourself from typos when typing out categories, you can
|
||||
define your desired categories in `mkdocs.yml` as part of the
|
||||
[`categories_allowed`][categories_allowed] configuration option. The
|
||||
[built-in blog plugin] will stop the build if a category is not found within
|
||||
the list.
|
||||
|
||||
[categories_allowed]: ../plugins/blog.md#config.categories_allowed
|
||||
|
||||
#### Adding tags
|
||||
|
||||
Besides [categories], the [built-in blog plugin] also integrates with the
|
||||
[built-in tags plugin]. If you add tags in the front matter `tags` property as
|
||||
part of a post, the post is linked from the [tags index]:
|
||||
|
||||
``` yaml
|
||||
---
|
||||
date: 2024-01-31
|
||||
tags:
|
||||
- Foo
|
||||
- Bar
|
||||
---
|
||||
|
||||
# Hello world!
|
||||
...
|
||||
```
|
||||
|
||||
As usual, the tags are rendered above the main headline and posts are linked
|
||||
on the tags index page, if configured. Note that posts are, as pages, only
|
||||
linked with their titles.
|
||||
|
||||
[built-in tags plugin]: ../plugins/tags.md
|
||||
[tags index]: setting-up-tags.md#adding-a-tags-index
|
||||
|
||||
#### Changing the slug
|
||||
|
||||
Slugs are the shortened description of your post used in the URL. They are automatically generated, but you can specify a custom slug for a page:
|
||||
|
||||
``` yaml
|
||||
---
|
||||
slug: hello-world
|
||||
---
|
||||
|
||||
# Hello there world!
|
||||
...
|
||||
```
|
||||
|
||||
#### Adding related links
|
||||
|
||||
<!-- md:version 9.6.0 -->
|
||||
<!-- md:flag experimental -->
|
||||
|
||||
Related links offer the perfect way to prominently add a _further reading_
|
||||
section to your post that is included in the left sidebar, guiding the user to
|
||||
other destinations of your documentation. Use the front matter `links` property
|
||||
to add related links to a post:
|
||||
|
||||
``` yaml
|
||||
---
|
||||
date: 2024-01-31
|
||||
links:
|
||||
- plugins/search.md
|
||||
- insiders/how-to-sponsor.md
|
||||
---
|
||||
|
||||
# Hello world!
|
||||
...
|
||||
```
|
||||
|
||||
You can use the exact same syntax as for the [`nav`][mkdocs.nav] section in
|
||||
`mkdocs.yml`, which means you can set explicit titles for links, add external
|
||||
links and even use nesting:
|
||||
|
||||
``` yaml
|
||||
---
|
||||
date: 2024-01-31
|
||||
links:
|
||||
- plugins/search.md
|
||||
- insiders/how-to-sponsor.md
|
||||
- Nested section:
|
||||
- External link: https://example.com
|
||||
- setup/setting-up-site-search.md
|
||||
---
|
||||
|
||||
# Hello world!
|
||||
...
|
||||
```
|
||||
|
||||
If you look closely, you'll realize that you can even use an anchor to link to
|
||||
a specific section of a document, extending the possibilities of the
|
||||
[`nav`][mkdocs.nav] syntax in `mkdocs.yml`. The [built-in blog plugin] resolves
|
||||
the anchor and sets the title of the anchor as a [subtitle] of the related link.
|
||||
|
||||
Note that all links must be relative to [`docs_dir`][mkdocs.docs_dir], as is
|
||||
also the case for the [`nav`][mkdocs.nav] setting.
|
||||
|
||||
[subtitle]: ../reference/index.md#setting-the-page-subtitle
|
||||
|
||||
#### Linking from and to posts
|
||||
|
||||
While [post URLs][post slugs] are dynamically computed, the [built-in blog
|
||||
plugin] ensures that all links from and to posts and a post's assets are
|
||||
correct. If you want to link to a post, just use the path to the Markdown file
|
||||
as a link reference (links must be relative):
|
||||
|
||||
``` markdown
|
||||
[Hello World!](blog/posts/hello-world.md)
|
||||
```
|
||||
|
||||
Linking from a post to a page, e.g. the index, follows the same method:
|
||||
|
||||
``` markdown
|
||||
[Blog](../index.md)
|
||||
```
|
||||
|
||||
All assets inside the `posts` directory are copied to the `blog/assets` folder
|
||||
when the site is being built. Of course, you can also reference assets from
|
||||
posts outside of the `posts` directory. The [built-in blog plugin] ensures that
|
||||
all links are correct.
|
||||
|
||||
#### Pinning a post
|
||||
|
||||
<!-- md:version 9.7.0 -->
|
||||
<!-- md:flag experimental -->
|
||||
|
||||
If you want to pin a post to the top of the index page, as well as the archive
|
||||
and category indexes it is part of, you can use the front matter `pin` property:
|
||||
|
||||
``` yaml
|
||||
---
|
||||
date: 2024-01-31
|
||||
pin: true
|
||||
---
|
||||
|
||||
# Hello world!
|
||||
...
|
||||
```
|
||||
|
||||
If multiple posts are pinned, they are sorted by their creation date, with the
|
||||
most recent pinned post being shown first, followed by the other pinned posts in
|
||||
descending order.
|
||||
|
||||
#### Setting the reading time
|
||||
|
||||
When [enabled], the reading the expected reading time of each post is computed,
|
||||
which is rendered as part of the post and post excerpt. Nowadays, many blogs
|
||||
show reading times, which is why the [built-in blog plugin] offers this
|
||||
capability as well.
|
||||
|
||||
Sometimes, however, the computed reading time might not feel accurate, or
|
||||
result in odd and unpleasant numbers. For this reason, reading time can be
|
||||
overridden and explicitly set with the front matter `readtime` property for a
|
||||
post:
|
||||
|
||||
``` yaml
|
||||
---
|
||||
date: 2024-01-31
|
||||
readtime: 15
|
||||
---
|
||||
|
||||
# Hello world!
|
||||
...
|
||||
```
|
||||
|
||||
This will disable automatic reading time computation.
|
||||
|
||||
!!! warning "Chinese, Japanese and Korean characters"
|
||||
|
||||
Reading time computation currently does not take segmentation of Chinese,
|
||||
Japanese and Korean characters into account. This means that the reading
|
||||
time for posts in these languages may be inaccurate. We're planning on
|
||||
adding support in the future. In the meantime, please use the `readtime`
|
||||
front matter property to set the reading time.
|
||||
|
||||
[enabled]: ../plugins/blog.md#config.post_readtime
|
||||
|
||||
#### Setting defaults
|
||||
|
||||
<!-- md:version 9.6.0 -->
|
||||
<!-- md:plugin [meta][built-in meta plugin] – built-in -->
|
||||
<!-- md:flag experimental -->
|
||||
|
||||
If you have a lot of posts, it might feel redundant to define all of the above
|
||||
for each post. Luckily, the [built-in meta plugin] allows to set default front
|
||||
matter properties per folder. You can group your posts by categories, or
|
||||
authors, and add a `.meta.yml` file to set common properties:
|
||||
|
||||
``` { .sh .no-copy }
|
||||
.
|
||||
├─ docs/
|
||||
│ └─ blog/
|
||||
│ ├─ posts/
|
||||
│ ├─ .meta.yml # (1)!
|
||||
│ └─ index.md
|
||||
└─ mkdocs.yml
|
||||
```
|
||||
|
||||
1. As already noted, you can also place a `.meta.yml` file in nested folders
|
||||
of the `posts` directory. This file then can define all front matter
|
||||
properties that are valid in posts, e.g.:
|
||||
|
||||
``` yaml
|
||||
authors:
|
||||
- squidfunk
|
||||
categories:
|
||||
- Hello
|
||||
- World
|
||||
```
|
||||
|
||||
Note that order matters – the [built-in meta plugin] must be defined before the
|
||||
blog plugin in `mkdocs.yml`, so that all set defaults are correctly picked up
|
||||
by the [built-in blog plugin]:
|
||||
|
||||
``` yaml
|
||||
plugins:
|
||||
- meta
|
||||
- blog
|
||||
```
|
||||
|
||||
Lists and dictionaries in `.meta.yml` files are merged and deduplicated with the
|
||||
values defined for a post, which means you can define common properties in
|
||||
`.meta.yml` and then add specific properties or overrides for each post.
|
||||
|
||||
[built-in meta plugin]: ../plugins/meta.md
|
||||
|
||||
### Adding pages
|
||||
|
||||
Besides posts, it's also possible to add static pages to your blog by listing
|
||||
the pages in the [`nav`][mkdocs.nav] section of `mkdocs.yml`. All generated
|
||||
indexes are included after the last specified page. For example, to add a page
|
||||
on the authors of the blog, add the following to `mkdocs.yml`:
|
||||
|
||||
``` yaml
|
||||
nav:
|
||||
- Blog:
|
||||
- blog/index.md
|
||||
- blog/authors.md
|
||||
...
|
||||
```
|
||||
|
||||
## Customization
|
||||
|
||||
### Custom index pages
|
||||
|
||||
<!-- md:version 9.6.0 -->
|
||||
<!-- md:flag experimental -->
|
||||
|
||||
If you want to add custom content to automatically generated [archive] and
|
||||
[category] indexes, e.g. to add a category description prior to the list of
|
||||
posts, you can manually create the category page in the same location where
|
||||
the [built-in blog plugin] would create it:
|
||||
|
||||
``` { .sh .no-copy }
|
||||
.
|
||||
├─ docs/
|
||||
│ └─ blog/
|
||||
│ ├─ category/
|
||||
│ │ └─ hello.md # (1)!
|
||||
│ ├─ posts/
|
||||
│ └─ index.md
|
||||
└─ mkdocs.yml
|
||||
```
|
||||
|
||||
1. The easiest way is to first [add the category] to the blog post, then take
|
||||
the URL generated by the [built-in blog plugin] and create the file at the
|
||||
corresponding location in the [`blog_dir`][blog_dir] folder.
|
||||
|
||||
Note that the shown directory listing is based on the default configuration.
|
||||
If you specify different values for the following options, be sure to adjust
|
||||
the path accordingly:
|
||||
|
||||
- [`blog_dir`][blog_dir]
|
||||
- [`categories_url_format`][categories_url_format]
|
||||
- [`categories_slugify`][categories_slugify]
|
||||
|
||||
You can now add arbitrary content to the newly created file, or set specific
|
||||
front matter properties for this page, e.g. to change the [page description]:
|
||||
|
||||
``` yaml
|
||||
---
|
||||
description: Nullam urna elit, malesuada eget finibus ut, ac tortor.
|
||||
---
|
||||
|
||||
# Hello
|
||||
...
|
||||
```
|
||||
|
||||
All post excerpts belonging to the category are automatically appended.
|
||||
|
||||
[add the category]: #adding-categories
|
||||
[page description]: ../reference/index.md#setting-the-page-description
|
||||
[categories_url_format]: ../plugins/blog.md#config.categories_url_format
|
||||
[categories_slugify]: ../plugins/blog.md#config.categories_slugify
|
||||
[blog_dir]: ../plugins/blog.md#config.blog_dir
|
||||
|
||||
### Overriding templates
|
||||
|
||||
The [built-in blog plugin] is built on the same basis as Material for MkDocs,
|
||||
which means you can override all templates used for the blog by using
|
||||
[theme extension] as usual.
|
||||
|
||||
The following templates are added by the [built-in blog plugin]:
|
||||
|
||||
- [`blog.html`][blog.html] – Template for blog, archive and category index
|
||||
- [`blog-post.html`][blog-post.html] – Template for blog post
|
||||
|
||||
[theme extension]: ../customization.md#extending-the-theme
|
||||
|
||||
[blog.html]: https://github.com/squidfunk/mkdocs-material/blob/master/src/templates/blog.html
|
||||
[blog-post.html]: https://github.com/squidfunk/mkdocs-material/blob/master/src/templates/blog-post.html
|
||||
@@ -0,0 +1,649 @@
|
||||
# Setting up navigation
|
||||
|
||||
A clear and concise navigation structure is an important aspect of good project
|
||||
documentation. Material for MkDocs provides a multitude of options to configure
|
||||
the behavior of navigational elements, including [tabs] and [sections], and one
|
||||
of its flagship features: [instant loading].
|
||||
|
||||
[tabs]: #navigation-tabs
|
||||
[sections]: #navigation-sections
|
||||
[instant loading]: #instant-loading
|
||||
|
||||
Additional navigation can be configured [in the footer] as well as with the
|
||||
[tags plugin]. The [blog plugin] also sets up additional navigation.
|
||||
|
||||
[in the footer]: setting-up-the-footer.md#navigation
|
||||
[tags plugin]: ../plugins/tags.md
|
||||
[blog plugin]: ../plugins/blog.md
|
||||
|
||||
## Configuration
|
||||
|
||||
### Instant loading
|
||||
|
||||
<!-- md:version 5.0.0 -->
|
||||
<!-- md:feature -->
|
||||
|
||||
When instant loading is enabled, clicks on all internal links will be
|
||||
intercepted and dispatched via [XHR] without fully reloading the page. Add
|
||||
the following lines to `mkdocs.yml`:
|
||||
|
||||
``` yaml
|
||||
theme:
|
||||
features:
|
||||
- navigation.instant
|
||||
```
|
||||
|
||||
The resulting page is parsed and injected and all event handlers and components
|
||||
are rebound automatically, i.e., __Material for MkDocs now behaves like a Single
|
||||
Page Application__. Now, the search index survives navigation, which is
|
||||
especially useful for large documentation sites.
|
||||
|
||||
!!! info "The [`site_url`][mkdocs.site_url] setting must be set"
|
||||
|
||||
Note that you must set [`site_url`][mkdocs.site_url] when using instant
|
||||
navigation, as instant navigation relies on the generated `sitemap.xml`
|
||||
which will be empty if this setting is omitted. Example:
|
||||
|
||||
``` yaml
|
||||
site_url: https://example.com
|
||||
```
|
||||
|
||||
[XHR]: https://developer.mozilla.org/en-US/docs/Web/API/XMLHttpRequest
|
||||
|
||||
#### Instant prefetching
|
||||
|
||||
<!-- md:version 9.7.0 -->
|
||||
<!-- md:feature -->
|
||||
<!-- md:flag experimental -->
|
||||
|
||||
Instant prefetching is a new experimental feature that will start to fetch a
|
||||
page once the user hovers over a link. This will reduce the perceived loading
|
||||
time for the user, especially on slow connections, as the page will be available
|
||||
immediately upon navigation. Enable it with:
|
||||
|
||||
``` yaml
|
||||
theme:
|
||||
features:
|
||||
- navigation.instant
|
||||
- navigation.instant.prefetch
|
||||
```
|
||||
|
||||
#### Progress indicator
|
||||
|
||||
<!-- md:version 9.4.3 -->
|
||||
<!-- md:feature -->
|
||||
<!-- md:flag experimental -->
|
||||
|
||||
In order to provide a better user experience on slow connections when using
|
||||
instant navigation, a progress indicator can be enabled. It will be shown at
|
||||
the top of the page and will be hidden once the page has fully loaded. You can
|
||||
enable it in `mkdocs.yml` with:
|
||||
|
||||
``` yaml
|
||||
theme:
|
||||
features:
|
||||
- navigation.instant
|
||||
- navigation.instant.progress
|
||||
```
|
||||
|
||||
The progress indicator will only show if the page hasn't finished loading after
|
||||
400ms, so that fast connections will never show it for a better instant
|
||||
experience.
|
||||
|
||||
### Instant previews
|
||||
|
||||
<!-- md:version 9.7.0 -->
|
||||
<!-- md:feature -->
|
||||
<!-- md:flag experimental -->
|
||||
|
||||
Instant previews are a brand new feature that allow the user to preview another
|
||||
site of your documentation without navigating to it. They can be very helpful to
|
||||
keep the user in context. Instant previews can be enabled on any header link
|
||||
with the `data-preview` attribute:
|
||||
|
||||
```` markdown title="Link with instant preview"
|
||||
``` markdown
|
||||
[Attribute Lists](#){ data-preview }
|
||||
```
|
||||
````
|
||||
|
||||
<div class="result" markdown>
|
||||
|
||||
[Attribute Lists](extensions/python-markdown.md#attribute-lists){ data-preview }
|
||||
|
||||
</div>
|
||||
|
||||
!!! info "Limitations"
|
||||
|
||||
Instant previews are still an experimental feature and currently limited to
|
||||
headerlinks. This means, you can use them on any internal link that points
|
||||
to a header on another page, but not other elements with `id` attributes.
|
||||
After we have gathered enough feedback, we will consider extending this
|
||||
feature to other, and possibly arbitrary elements.
|
||||
|
||||
#### Automatic previews
|
||||
|
||||
<!-- md:version 9.7.0 -->
|
||||
<!-- md:extension -->
|
||||
<!-- md:flag experimental -->
|
||||
|
||||
The recommended way to work with instant previews is to use the Markdown
|
||||
extension that is included with Material for MkDocs, as it allows you to enable
|
||||
instant previews on a per-page or per-section level for your documentation:
|
||||
|
||||
``` yaml
|
||||
markdown_extensions:
|
||||
- material.extensions.preview:
|
||||
configurations:
|
||||
- targets:
|
||||
include:
|
||||
- changelog/index.md
|
||||
- customization.md
|
||||
- insiders/changelog/*
|
||||
- setup/extensions/*
|
||||
```
|
||||
|
||||
The above configuration is what we use for our documentation. We've enabled
|
||||
instant previews for our changelogs, customization guide, and Insiders sections,
|
||||
as well as for all Markdown extensions that we support.
|
||||
|
||||
!!! info "Full configuration example"
|
||||
|
||||
``` yaml
|
||||
markdown_extensions:
|
||||
- material.extensions.preview:
|
||||
configurations:
|
||||
- sources: # (1)!
|
||||
include:
|
||||
- ...
|
||||
exclude:
|
||||
- ...
|
||||
targets: # (2)!
|
||||
include:
|
||||
- ...
|
||||
exclude:
|
||||
- ...
|
||||
```
|
||||
|
||||
1. Sources specify the pages _on_ which instant previews should be enabled.
|
||||
If this setting is omitted, instant previews will be enabled on all
|
||||
pages. You can use patterns to include or exclude pages. Exclusion is
|
||||
evaluated on top of inclusion, so if a page is matched by both, it will
|
||||
be excluded.
|
||||
|
||||
Note that you can define multiple items under the `configurations`
|
||||
setting, which allows to precisely control where instant previews are
|
||||
shown.
|
||||
|
||||
2. Targets specify the pages _to_ which instant previews should be enabled.
|
||||
This is the recommended way to enable instant previews.
|
||||
---
|
||||
|
||||
Instant previews can also be enabled globally by adding the following lines to
|
||||
`mkdocs.yml`, which will enable instant previews for all header links,
|
||||
alleviating the need to add data attributes:
|
||||
|
||||
``` yaml
|
||||
theme:
|
||||
features:
|
||||
- navigation.instant.preview
|
||||
```
|
||||
|
||||
!!! info "The [`site_url`][mkdocs.site_url] setting must be set"
|
||||
|
||||
Note that you must set [`site_url`][mkdocs.site_url] when using instant
|
||||
previews, as instant previews rely on the generated `sitemap.xml`
|
||||
which will be empty if this setting is omitted. Example:
|
||||
|
||||
``` yaml
|
||||
site_url: https://example.com
|
||||
```
|
||||
|
||||
### Anchor tracking
|
||||
|
||||
<!-- md:version 8.0.0 -->
|
||||
<!-- md:feature -->
|
||||
|
||||
When anchor tracking is enabled, the URL in the address bar is automatically
|
||||
updated with the active anchor as highlighted in the table of contents. Add the
|
||||
following lines to `mkdocs.yml`:
|
||||
|
||||
``` yaml
|
||||
theme:
|
||||
features:
|
||||
- navigation.tracking
|
||||
```
|
||||
|
||||
### Navigation tabs
|
||||
|
||||
<!-- md:version 1.1.0 -->
|
||||
<!-- md:feature -->
|
||||
|
||||
When tabs are enabled, top-level sections are rendered in a menu layer below
|
||||
the header for viewports above `1220px`, but remain as-is on mobile.[^1] Add
|
||||
the following lines to `mkdocs.yml`:
|
||||
|
||||
[^1]:
|
||||
Prior to <!-- md:version 6.2.0 -->, navigation tabs had a slightly different
|
||||
behavior. All top-level pages (i.e. all top-level entries directly
|
||||
referring to a `*.md` file) defined inside the `nav` entry of `mkdocs.yml`
|
||||
were grouped under the first tab which received the title of the first page.
|
||||
This made it impossible to include a top-level page (or external link) as a
|
||||
tab item, as was reported in #1884 and #2072. From <!-- md:version 6.2.0 -->
|
||||
on, navigation tabs include all top-level pages and sections.
|
||||
|
||||
``` yaml
|
||||
theme:
|
||||
features:
|
||||
- navigation.tabs
|
||||
```
|
||||
|
||||
=== "With tabs"
|
||||
|
||||
[![Navigation tabs enabled]][Navigation tabs enabled]
|
||||
|
||||
=== "Without"
|
||||
|
||||
[![Navigation tabs disabled]][Navigation tabs disabled]
|
||||
|
||||
[Navigation tabs enabled]: ../assets/screenshots/navigation-tabs.png
|
||||
[Navigation tabs disabled]: ../assets/screenshots/navigation.png
|
||||
|
||||
#### Sticky navigation tabs
|
||||
|
||||
<!-- md:version 7.3.0 -->
|
||||
<!-- md:feature -->
|
||||
|
||||
When sticky tabs are enabled, navigation tabs will lock below the header and
|
||||
always remain visible when scrolling down. Just add the following two feature
|
||||
flags to `mkdocs.yml`:
|
||||
|
||||
``` yaml
|
||||
theme:
|
||||
features:
|
||||
- navigation.tabs
|
||||
- navigation.tabs.sticky
|
||||
```
|
||||
|
||||
=== "With sticky tabs"
|
||||
|
||||
[![Sticky navigation tabs enabled]][Sticky navigation tabs enabled]
|
||||
|
||||
=== "Without"
|
||||
|
||||
[![Sticky navigation tabs disabled]][Sticky navigation tabs disabled]
|
||||
|
||||
[Sticky navigation tabs enabled]: ../assets/screenshots/navigation-tabs-sticky.png
|
||||
[Sticky navigation tabs disabled]: ../assets/screenshots/navigation-tabs-collapsed.png
|
||||
|
||||
### Navigation sections
|
||||
|
||||
<!-- md:version 6.2.0 -->
|
||||
<!-- md:feature -->
|
||||
|
||||
When sections are enabled, top-level sections are rendered as groups in the
|
||||
sidebar for viewports above `1220px`, but remain as-is on mobile. Add the
|
||||
following lines to `mkdocs.yml`:
|
||||
|
||||
``` yaml
|
||||
theme:
|
||||
features:
|
||||
- navigation.sections
|
||||
```
|
||||
|
||||
=== "With sections"
|
||||
|
||||
[![Navigation sections enabled]][Navigation sections enabled]
|
||||
|
||||
=== "Without"
|
||||
|
||||
[![Navigation sections disabled]][Navigation sections disabled]
|
||||
|
||||
[Navigation sections enabled]: ../assets/screenshots/navigation-sections.png
|
||||
[Navigation sections disabled]: ../assets/screenshots/navigation.png
|
||||
|
||||
Both feature flags, [`navigation.tabs`][tabs] and
|
||||
[`navigation.sections`][sections], can be combined with each other. If both
|
||||
feature flags are enabled, sections are rendered for level 2 navigation items.
|
||||
|
||||
### Navigation expansion
|
||||
|
||||
<!-- md:version 6.2.0 -->
|
||||
<!-- md:feature -->
|
||||
|
||||
When expansion is enabled, the left sidebar will expand all collapsible
|
||||
subsections by default, so the user doesn't have to open subsections manually.
|
||||
Add the following lines to `mkdocs.yml`:
|
||||
|
||||
``` yaml
|
||||
theme:
|
||||
features:
|
||||
- navigation.expand
|
||||
```
|
||||
|
||||
=== "With expansion"
|
||||
|
||||
[![Navigation expansion enabled]][Navigation expansion enabled]
|
||||
|
||||
=== "Without"
|
||||
|
||||
[![Navigation expansion disabled]][Navigation expansion disabled]
|
||||
|
||||
[Navigation expansion enabled]: ../assets/screenshots/navigation-expand.png
|
||||
[Navigation expansion disabled]: ../assets/screenshots/navigation.png
|
||||
|
||||
### Navigation path <small>Breadcrumbs</small> { id=navigation-path }
|
||||
|
||||
<!-- md:version 9.7.0 -->
|
||||
<!-- md:feature -->
|
||||
<!-- md:flag experimental -->
|
||||
|
||||
When navigation paths are activated, a breadcrumb navigation is rendered above
|
||||
the title of each page, which might make orientation easier for users visiting your
|
||||
documentation on devices with smaller screens. Add the following lines to
|
||||
`mkdocs.yml`:
|
||||
|
||||
``` yaml
|
||||
theme:
|
||||
features:
|
||||
- navigation.path
|
||||
```
|
||||
|
||||
=== "With navigation path"
|
||||
|
||||
[![Navigation path enabled]][Navigation path enabled]
|
||||
|
||||
=== "Without"
|
||||
|
||||
[![Navigation path disabled]][Navigation path disabled]
|
||||
|
||||
[Navigation path enabled]: ../assets/screenshots/navigation-path-on.png
|
||||
[Navigation path disabled]: ../assets/screenshots/navigation-path-off.png
|
||||
|
||||
### Navigation pruning
|
||||
|
||||
<!-- md:version 9.2.0 -->
|
||||
<!-- md:feature -->
|
||||
<!-- md:flag experimental -->
|
||||
|
||||
When pruning is enabled, only the visible navigation items are included in the
|
||||
rendered HTML, __reducing the size of the built site by 33% or more__. Add the
|
||||
following lines to `mkdocs.yml`:
|
||||
|
||||
``` yaml
|
||||
theme:
|
||||
features:
|
||||
- navigation.prune # (1)!
|
||||
```
|
||||
|
||||
1. This feature flag is not compatible with
|
||||
[`navigation.expand`][navigation.expand], as navigation expansion requires
|
||||
the complete navigation structure.
|
||||
|
||||
This feature flag is especially useful for documentation sites with 100+ or even
|
||||
1,000+ of pages, as the navigation makes up a significant fraction of the HTML.
|
||||
Navigation pruning will replace all expandable sections with links to the first
|
||||
page in that section (or the section index page).
|
||||
|
||||
[navigation.expand]: #navigation-expansion
|
||||
|
||||
### Section index pages
|
||||
|
||||
<!-- md:version 7.3.0 -->
|
||||
<!-- md:feature -->
|
||||
|
||||
When section index pages are enabled, documents can be directly attached to
|
||||
sections, which is particularly useful for providing overview pages. Add the
|
||||
following lines to `mkdocs.yml`:
|
||||
|
||||
``` yaml
|
||||
theme:
|
||||
features:
|
||||
- navigation.indexes # (1)!
|
||||
```
|
||||
|
||||
1. This feature flag is not compatible with [`toc.integrate`][toc.integrate],
|
||||
as sections cannot host the table of contents due to missing space.
|
||||
|
||||
=== "With section index pages"
|
||||
|
||||
[![Section index pages enabled]][Section index pages enabled]
|
||||
|
||||
=== "Without"
|
||||
|
||||
[![Section index pages disabled]][Section index pages disabled]
|
||||
|
||||
In order to link a page to a section, create a new document with the name
|
||||
`index.md` in the respective folder, and add it to the beginning of your
|
||||
navigation section:
|
||||
|
||||
``` yaml
|
||||
nav:
|
||||
- Section:
|
||||
- section/index.md # (1)!
|
||||
- Page 1: section/page-1.md
|
||||
...
|
||||
- Page n: section/page-n.md
|
||||
```
|
||||
|
||||
1. MkDocs also considers files called `README.md` as [index pages].
|
||||
|
||||
[Section index pages enabled]: ../assets/screenshots/navigation-index-on.png
|
||||
[Section index pages disabled]: ../assets/screenshots/navigation-index-off.png
|
||||
[toc.integrate]: #navigation-integration
|
||||
[index pages]: https://www.mkdocs.org/user-guide/writing-your-docs/#index-pages
|
||||
|
||||
### Table of contents
|
||||
|
||||
#### Anchor following
|
||||
|
||||
<!-- md:version 8.5.0 -->
|
||||
<!-- md:feature -->
|
||||
<!-- md:flag experimental -->
|
||||
|
||||
When anchor following for the [table of contents] is enabled, the sidebar is
|
||||
automatically scrolled so that the active anchor is always visible. Add the
|
||||
following lines to `mkdocs.yml`:
|
||||
|
||||
``` yaml
|
||||
theme:
|
||||
features:
|
||||
- toc.follow
|
||||
```
|
||||
|
||||
#### Navigation integration
|
||||
|
||||
<!-- md:version 6.2.0 -->
|
||||
<!-- md:feature -->
|
||||
|
||||
When navigation integration for the [table of contents] is enabled, it is always
|
||||
rendered as part of the navigation sidebar on the left. Add the following lines
|
||||
to `mkdocs.yml`:
|
||||
|
||||
``` yaml
|
||||
theme:
|
||||
features:
|
||||
- toc.integrate # (1)!
|
||||
```
|
||||
|
||||
1. This feature flag is not compatible with
|
||||
[`navigation.indexes`][navigation.indexes], as sections cannot host the
|
||||
table of contents due to missing space.
|
||||
|
||||
=== "With navigation integration"
|
||||
|
||||
[![Navigation integration enabled]][Navigation integration enabled]
|
||||
|
||||
=== "Without"
|
||||
|
||||
[![Navigation integration disabled]][Navigation integration disabled]
|
||||
|
||||
[table of contents]: extensions/python-markdown.md#table-of-contents
|
||||
[Navigation integration enabled]: ../assets/screenshots/toc-integrate.png
|
||||
[Navigation integration disabled]: ../assets/screenshots/navigation-tabs.png
|
||||
[navigation.indexes]: #section-index-pages
|
||||
|
||||
### Back-to-top button
|
||||
|
||||
<!-- md:version 7.1.0 -->
|
||||
<!-- md:feature -->
|
||||
|
||||
A back-to-top button can be shown when the user, after scrolling down, starts
|
||||
to scroll up again. It's rendered centered and just below the header. Add the
|
||||
following lines to `mkdocs.yml`:
|
||||
|
||||
``` yaml
|
||||
theme:
|
||||
features:
|
||||
- navigation.top
|
||||
```
|
||||
|
||||
## Usage
|
||||
|
||||
### Hiding the sidebars
|
||||
|
||||
<!-- md:version 6.2.0 -->
|
||||
<!-- md:flag metadata -->
|
||||
|
||||
The navigation and/or table of contents sidebars can be hidden for a document
|
||||
with the front matter `hide` property. Add the following lines at the top of a
|
||||
Markdown file:
|
||||
|
||||
``` yaml
|
||||
---
|
||||
hide:
|
||||
- navigation
|
||||
- toc
|
||||
---
|
||||
|
||||
# Page title
|
||||
...
|
||||
```
|
||||
|
||||
=== "Hide navigation"
|
||||
|
||||
[![Hide navigation enabled]][Hide navigation enabled]
|
||||
|
||||
=== "Hide table of contents"
|
||||
|
||||
[![Hide table of contents enabled]][Hide table of contents enabled]
|
||||
|
||||
=== "Hide both"
|
||||
|
||||
[![Hide both enabled]][Hide both enabled]
|
||||
|
||||
[Hide navigation enabled]: ../assets/screenshots/hide-navigation.png
|
||||
[Hide table of contents enabled]: ../assets/screenshots/hide-toc.png
|
||||
[Hide both enabled]: ../assets/screenshots/hide-navigation-toc.png
|
||||
|
||||
### Hiding the navigation path
|
||||
|
||||
<!-- md:version 9.7.0 -->
|
||||
<!-- md:flag metadata -->
|
||||
|
||||
While the [navigation path] is rendered above the main headline, sometimes, it
|
||||
might be desirable to hide it for a specific page, which can be achieved with
|
||||
the front matter `hide` property:
|
||||
|
||||
``` yaml
|
||||
---
|
||||
hide:
|
||||
- path
|
||||
---
|
||||
|
||||
# Page title
|
||||
...
|
||||
```
|
||||
|
||||
[navigation path]: #navigation-path
|
||||
|
||||
## Customization
|
||||
|
||||
### Keyboard shortcuts
|
||||
|
||||
Material for MkDocs includes several keyboard shortcuts that make it possible
|
||||
to navigate your project documentation via keyboard. There are two modes:
|
||||
|
||||
<!-- md:option mode:search -->
|
||||
|
||||
: This mode is active when the _search is focused_. It provides several key
|
||||
bindings to make search accessible and navigable via keyboard:
|
||||
|
||||
* ++arrow-down++ , ++arrow-up++ : select next / previous result
|
||||
* ++esc++ , ++tab++ : close search dialog
|
||||
* ++enter++ : follow selected result
|
||||
|
||||
<!-- md:option mode:global -->
|
||||
|
||||
: This mode is active when _search is not focussed_ and when there's no other
|
||||
focussed element that is susceptible to keyboard input. The following keys
|
||||
are bound:
|
||||
|
||||
* ++f++ , ++s++ , ++slash++ : open search dialog
|
||||
* ++p++ , ++comma++ : go to previous page
|
||||
* ++n++ , ++period++ : go to next page
|
||||
|
||||
Let's say you want to bind some action to the ++x++ key. By using [additional
|
||||
JavaScript], you can subscribe to the `keyboard$` observable and attach
|
||||
your custom event listener:
|
||||
|
||||
=== ":octicons-file-code-16: `docs/javascripts/shortcuts.js`"
|
||||
|
||||
``` js
|
||||
keyboard$.subscribe(function(key) {
|
||||
if (key.mode === "global" && key.type === "x") {
|
||||
/* Add custom keyboard handler here */
|
||||
key.claim() // (1)!
|
||||
}
|
||||
})
|
||||
```
|
||||
|
||||
1. The call to `key.claim()` will execute `preventDefault()` on the
|
||||
underlying event, so the keypress will not propagate further and
|
||||
touch other event listeners.
|
||||
|
||||
=== ":octicons-file-code-16: `mkdocs.yml`"
|
||||
|
||||
``` yaml
|
||||
extra_javascript:
|
||||
- javascripts/shortcuts.js
|
||||
```
|
||||
|
||||
[additional JavaScript]: ../customization.md#additional-javascript
|
||||
|
||||
### Content area width
|
||||
|
||||
The width of the content area is set so the length of each line doesn't exceed
|
||||
80-100 characters, depending on the width of the characters. While this
|
||||
is a reasonable default, as longer lines tend to be harder to read, it may be
|
||||
desirable to increase the overall width of the content area, or even make it
|
||||
stretch to the entire available space.
|
||||
|
||||
This can easily be achieved with an [additional style sheet] and a few lines
|
||||
of CSS:
|
||||
|
||||
=== ":octicons-file-code-16: `docs/stylesheets/extra.css`"
|
||||
|
||||
``` css
|
||||
.md-grid {
|
||||
max-width: 1440px; /* (1)! */
|
||||
}
|
||||
```
|
||||
|
||||
1. If you want the content area to always stretch to the available screen
|
||||
space, reset `max-width` with the following CSS:
|
||||
|
||||
``` css
|
||||
.md-grid {
|
||||
max-width: initial;
|
||||
}
|
||||
```
|
||||
|
||||
=== ":octicons-file-code-16: `mkdocs.yml`"
|
||||
|
||||
``` yaml
|
||||
extra_css:
|
||||
- stylesheets/extra.css
|
||||
```
|
||||
|
||||
[additional style sheet]: ../customization.md#additional-css
|
||||
@@ -0,0 +1,324 @@
|
||||
# Setting up site analytics
|
||||
|
||||
As with any other service offered on the web, understanding how your project
|
||||
documentation is actually used can be an essential success factor. Material for
|
||||
MkDocs natively integrates with [Google Analytics] and offers a customizable
|
||||
[cookie consent] and a [feedback widget].
|
||||
|
||||
[Google Analytics]: https://developers.google.com/analytics
|
||||
[cookie consent]: ensuring-data-privacy.md#cookie-consent
|
||||
[feedback widget]: #was-this-page-helpful
|
||||
|
||||
## Configuration
|
||||
|
||||
### Google Analytics
|
||||
|
||||
<!-- md:version 7.1.8 -->
|
||||
<!-- md:default none -->
|
||||
|
||||
Material for MkDocs integrates natively with Google Analytics 4[^1]. If you
|
||||
already set up Google Analytics and have a property, enable it by adding the
|
||||
following lines to `mkdocs.yml`:
|
||||
|
||||
[^1]:
|
||||
Prior to Material for MkDocs 9.2.0, Universal Analytics was supported as
|
||||
well. However, since Universal Analytics has been sunset, this integration
|
||||
was removed in 9.2.0.
|
||||
|
||||
``` yaml
|
||||
extra:
|
||||
analytics:
|
||||
provider: google
|
||||
property: G-XXXXXXXXXX
|
||||
```
|
||||
|
||||
??? question "How to measure site search usage?"
|
||||
|
||||
Besides page views and events, [site search] can be tracked to better
|
||||
understand how people use your documentation and what they expect to find.
|
||||
In order to enable site search tracking, the following steps are required:
|
||||
|
||||
1. Go to your Google Analytics __admin settings__
|
||||
2. Select the property for the respective tracking code
|
||||
3. Select the __data streams__ tab and click the corresponding URL
|
||||
4. Click the gear icon within the __enhanced measurement__ section
|
||||
5. Ensure that __site search__ is enabled
|
||||
|
||||
[site search]: setting-up-site-search.md
|
||||
|
||||
### Was this page helpful?
|
||||
|
||||
<!-- md:version 8.4.0 -->
|
||||
<!-- md:default none -->
|
||||
|
||||
A simple [feedback widget] can be included at the bottom of each page,
|
||||
encouraging users to give instant feedback whether a page was helpful or not.
|
||||
Add the following lines to `mkdocs.yml`:
|
||||
|
||||
``` yaml
|
||||
extra:
|
||||
analytics: # (1)!
|
||||
feedback:
|
||||
title: Was this page helpful?
|
||||
ratings:
|
||||
- icon: material/emoticon-happy-outline
|
||||
name: This page was helpful
|
||||
data: 1
|
||||
note: >-
|
||||
Thanks for your feedback!
|
||||
- icon: material/emoticon-sad-outline
|
||||
name: This page could be improved
|
||||
data: 0
|
||||
note: >- # (2)!
|
||||
Thanks for your feedback! Help us improve this page by
|
||||
using our <a href="..." target="_blank" rel="noopener">feedback form</a>.
|
||||
```
|
||||
|
||||
1. This feature is natively integrated with [Google Analytics][analytics],
|
||||
which is why `provider` and `property` are also required. However, it's also
|
||||
possible to provide a [custom feedback integration].
|
||||
|
||||
2. You can add arbitrary HTML tags to the note which is shown after the user
|
||||
submitted the feedback, e.g. to link to a feedback form.
|
||||
|
||||
Both properties, `title` and `ratings`, are required. Note that it's allowed to
|
||||
define more than two ratings, e.g. to implement a 1-5 star rating. Since the
|
||||
feedback widget sends data to a third-party service, it is, of course, natively
|
||||
integrated with the [cookie consent] feature[^2].
|
||||
|
||||
[^2]:
|
||||
If the user doesn't accept the `analytics` cookie, the feedback widget is
|
||||
not shown.
|
||||
|
||||
??? question "How to visualize the collected feedback ratings?"
|
||||
|
||||
To visualize feedback ratings you'll need to create a custom report with
|
||||
[Google Analytics] that will quickly show you the worst- and best-rated
|
||||
pages of your project documentation.
|
||||
|
||||
1. Go to your Google Analytics __dashboard__
|
||||
|
||||
2. Go to the __Admin__ page on the left hand menu (at the bottom), then select
|
||||
__custom definitions__ on the __Data display__ card
|
||||
|
||||
3. Click the __custom metrics__ tab and then __create custom metrics__,
|
||||
enter the following values:
|
||||
|
||||
* Metric name: Page helpful
|
||||
* Description: Was this page helpful?
|
||||
* Event parameter: `data`
|
||||
* Unit of measurement: Standard
|
||||
|
||||
4. Go to the __explore__ page on the left hand menu, create a new
|
||||
__blank exploration__
|
||||
|
||||
5. Configure the report as follows:
|
||||
|
||||
* Dimensions: Add `Event name` and `Page location`
|
||||
* Metrics: Add `Event count` and `Page helpful`
|
||||
(the custom metric created in step 3)
|
||||
* Rows: `Page location`
|
||||
* Values: Drag in both `Event count` and `Page helpful`
|
||||
* Filters: Add a new filter for
|
||||
`Event name / exactly matches / feedback`
|
||||
|
||||
!!! warning "Delay in data availability"
|
||||
|
||||
The report may take 24 hours or longer to begin displaying data
|
||||
|
||||
Now, after you've saved the report and collected some feedback ratings,
|
||||
you'll have a list of all pages with the total number of ratings, and an
|
||||
average rating per page. This should help you identify pages that need to
|
||||
be improved:
|
||||
|
||||
!!! danger "Google Analytics 4 does not support average values"
|
||||
|
||||
To our knowledge, Google Analytics 4 has currently no feature that
|
||||
allows to define a custom calculated metric to compute the average
|
||||
rating of a page. See #5740.
|
||||
|
||||
[![feedback report]][feedback report]
|
||||
|
||||
The following properties are available for each rating:
|
||||
|
||||
<!-- md:option analytics.feedback.ratings.icon -->
|
||||
|
||||
: <!-- md:default none --> <!-- md:flag required -->
|
||||
This property must point to a valid icon path referencing [any icon bundled
|
||||
with the theme][custom icons], or the build will not succeed. Some popular
|
||||
combinations:
|
||||
|
||||
* :material-emoticon-happy-outline: + :material-emoticon-sad-outline: – `material/emoticon-happy-outline` + `material/emoticon-sad-outline`
|
||||
* :material-thumb-up-outline: + :material-thumb-down-outline: – `material/thumb-up-outline` + `material/thumb-down-outline`
|
||||
* :material-heart: + :material-heart-broken: – `material/heart` + `material/heart-broken`
|
||||
|
||||
<!-- md:option analytics.feedback.ratings.name -->
|
||||
|
||||
: <!-- md:default none --> <!-- md:flag required -->
|
||||
The value of this property is shown on user interaction (i.e. keyboard focus
|
||||
or mouse hover), explaining the meaning of the rating behind the icon.
|
||||
|
||||
<!-- md:option analytics.feedback.ratings.data -->
|
||||
|
||||
: <!-- md:default none --> <!-- md:flag required -->
|
||||
The value of this property is sent as a data value with the custom event
|
||||
that is transmitted to Google Analytics[^3] (or any custom integration).
|
||||
|
||||
[^3]:
|
||||
Note that for Google Analytics, the data value must be an integer.
|
||||
|
||||
<!-- md:option analytics.feedback.ratings.note -->
|
||||
|
||||
: <!-- md:default none --> <!-- md:flag required -->
|
||||
The value of this property is shown after the user selected the rating.
|
||||
It may contain arbitrary HTML tags, which is especially useful to ask the
|
||||
user to provide more detailed feedback for the current page through a form.
|
||||
It's also possible to pre-fill forms with the URL and title of the current
|
||||
page by using the following placeholders:
|
||||
|
||||
- `{url}` – Page URL
|
||||
- `{title}` – Page title
|
||||
|
||||
```
|
||||
https://github.com/.../issues/new/?title=[Feedback]+{title}+-+{url}
|
||||
```
|
||||
|
||||
In this example, when clicking the link, the user is redirected to the "new
|
||||
issue" form of your repository, with a pre-filled title including the path
|
||||
of the current document, e.g.:
|
||||
|
||||
```
|
||||
[Feedback] Setting up site analytics – /setup/setting-up-site-analytics/
|
||||
```
|
||||
|
||||
An alternative to GitHub issues is [Google Forms].
|
||||
|
||||
[feedback widget]: #feedback
|
||||
[analytics]: #google-analytics
|
||||
[feedback report]: ../assets/screenshots/feedback-report.png
|
||||
[custom feedback integration]: #custom-site-feedback
|
||||
[custom icons]: https://github.com/squidfunk/mkdocs-material/tree/master/material/templates/.icons
|
||||
[Google Forms]: https://www.google.com/forms/about/
|
||||
|
||||
## Usage
|
||||
|
||||
### Hiding the feedback widget
|
||||
|
||||
The [feedback widget] can be hidden for a document with the front matter `hide`
|
||||
property. Add the following lines at the top of a Markdown file:
|
||||
|
||||
``` yaml
|
||||
---
|
||||
hide:
|
||||
- feedback
|
||||
---
|
||||
|
||||
# Page title
|
||||
...
|
||||
```
|
||||
|
||||
## Customization
|
||||
|
||||
### Custom site analytics
|
||||
|
||||
In order to integrate another analytics service provider offering a
|
||||
JavaScript-based tracking solution, just follow the guide on [theme extension]
|
||||
and create a new partial in the `overrides` folder. The name of the partial is
|
||||
used to configure the custom integration via `mkdocs.yml`:
|
||||
|
||||
=== ":octicons-file-code-16: `overrides/partials/integrations/analytics/custom.html`"
|
||||
|
||||
``` html
|
||||
<script>
|
||||
/* Add custom analytics integration here, e.g. */
|
||||
var property = "{{ config.extra.analytics.property }}" // (1)!
|
||||
|
||||
/* Wait for page to load and application to mount */
|
||||
document.addEventListener("DOMContentLoaded", function() {
|
||||
location$.subscribe(function(url) {
|
||||
/* Add custom page event tracking here */ // (2)!
|
||||
})
|
||||
})
|
||||
</script>
|
||||
```
|
||||
|
||||
1. As an example, this variable receives the value set in `mkdocs.yml`,
|
||||
which is `"foobar"` for `property`.
|
||||
2. If you're using [instant loading], you can use the `location$`
|
||||
observable to listen for navigation events, which always emits the
|
||||
current `URL`.
|
||||
|
||||
=== ":octicons-file-code-16: `mkdocs.yml`"
|
||||
|
||||
``` yaml
|
||||
extra:
|
||||
analytics:
|
||||
provider: custom
|
||||
property: foobar # (1)!
|
||||
```
|
||||
|
||||
1. You can add arbitrary key-value combinations to configure your
|
||||
custom integration. This is especially useful if you're sharing the
|
||||
custom integration across multiple repositories.
|
||||
|
||||
[theme extension]: ../customization.md#extending-the-theme
|
||||
[instant loading]: setting-up-navigation.md#instant-loading
|
||||
|
||||
### Custom site feedback
|
||||
|
||||
A custom feedback widget integration just needs to process the events that are
|
||||
generated by users interacting with the feedback widget with the help of some
|
||||
[additional JavaScript]:
|
||||
|
||||
=== ":octicons-file-code-16: `docs/javascripts/feedback.js`"
|
||||
|
||||
``` js
|
||||
document$.subscribe(function() {
|
||||
var feedback = document.forms.feedback
|
||||
if (typeof feedback === "undefined") return
|
||||
|
||||
feedback.hidden = false // (1)!
|
||||
|
||||
feedback.addEventListener("submit", function(ev) {
|
||||
ev.preventDefault()
|
||||
|
||||
var page = document.location.pathname // (2)!
|
||||
var data = ev.submitter.getAttribute("data-md-value")
|
||||
|
||||
console.log(page, data) // (3)!
|
||||
|
||||
feedback.firstElementChild.disabled = true // (4)!
|
||||
|
||||
var note = feedback.querySelector(
|
||||
".md-feedback__note [data-md-value='" + data + "']"
|
||||
)
|
||||
if (note)
|
||||
note.hidden = false // (5)!
|
||||
})
|
||||
}
|
||||
```
|
||||
|
||||
1. The feedback widget is hidden by default so that it does not appear when
|
||||
people have JavaScript turned off. So, it needs to be turned on here.
|
||||
|
||||
2. Retrieve page and feedback value.
|
||||
|
||||
3. Replace this with the code that sends the data off to your analytics
|
||||
provider.
|
||||
|
||||
4. Disable the form after submission.
|
||||
|
||||
5. Show the configured notes. Which one is shown depends on the user
|
||||
feedback.
|
||||
|
||||
=== ":octicons-file-code-16: `mkdocs.yml`"
|
||||
|
||||
``` yaml
|
||||
extra_javascript:
|
||||
- javascripts/feedback.js
|
||||
```
|
||||
|
||||
|
||||
{ #feedback style="margin: 0; height: 0" }
|
||||
|
||||
[additional JavaScript]: ../customization.md#additional-javascript
|
||||
@@ -0,0 +1,229 @@
|
||||
---
|
||||
search:
|
||||
boost: 1.05
|
||||
---
|
||||
|
||||
# Setting up site search
|
||||
|
||||
Material for MkDocs provides an excellent client-side search implementation,
|
||||
omitting the need for the integration of third-party services, which might
|
||||
not be compliant with privacy regulations. Moreover, search even works
|
||||
[offline], allowing users to download your documentation.
|
||||
|
||||
[offline]: building-for-offline-usage.md
|
||||
|
||||
## Configuration
|
||||
|
||||
### Built-in search plugin
|
||||
|
||||
<!-- md:version 0.1.0 -->
|
||||
<!-- md:plugin -->
|
||||
|
||||
The built-in search plugin integrates seamlessly with Material for MkDocs,
|
||||
adding multilingual client-side search with [lunr] and [lunr-languages]. It's
|
||||
enabled by default, but must be re-added to `mkdocs.yml` when other plugins
|
||||
are used:
|
||||
|
||||
``` yaml
|
||||
plugins:
|
||||
- search
|
||||
```
|
||||
|
||||
For a list of all settings, please consult the [plugin documentation].
|
||||
|
||||
[plugin documentation]: ../plugins/search.md
|
||||
|
||||
[lunr]: https://lunrjs.com
|
||||
[lunr-languages]: https://github.com/MihaiValentin/lunr-languages
|
||||
|
||||
### Search suggestions
|
||||
|
||||
<!-- md:version 7.2.0 -->
|
||||
<!-- md:feature -->
|
||||
<!-- md:flag experimental -->
|
||||
|
||||
When search suggestions are enabled, the search will display the likeliest
|
||||
completion for the last word which can be accepted with the ++arrow-right++ key.
|
||||
Add the following lines to `mkdocs.yml`:
|
||||
|
||||
``` yaml
|
||||
theme:
|
||||
features:
|
||||
- search.suggest
|
||||
```
|
||||
|
||||
Searching for [:octicons-search-24: search su][Search suggestions example]
|
||||
yields ^^search suggestions^^ as a suggestion.
|
||||
|
||||
[Search suggestions example]: ?q=search+su
|
||||
|
||||
### Search highlighting
|
||||
|
||||
<!-- md:version 7.2.0 -->
|
||||
<!-- md:feature -->
|
||||
<!-- md:flag experimental -->
|
||||
|
||||
When search highlighting is enabled and a user clicks on a search result,
|
||||
Material for MkDocs will highlight all occurrences after following the link.
|
||||
Add the following lines to `mkdocs.yml`:
|
||||
|
||||
``` yaml
|
||||
theme:
|
||||
features:
|
||||
- search.highlight
|
||||
```
|
||||
|
||||
Searching for [:octicons-search-24: code blocks][Search highlighting example]
|
||||
highlights all occurrences of both terms.
|
||||
|
||||
[Search highlighting example]: ../reference/code-blocks.md?h=code+blocks
|
||||
|
||||
### Search sharing
|
||||
|
||||
<!-- md:version 7.2.0 -->
|
||||
<!-- md:feature -->
|
||||
|
||||
When search sharing is activated, a :material-share-variant: share button is
|
||||
rendered next to the reset button, which allows to deep link to the current
|
||||
search query and result. Add the following lines to `mkdocs.yml`:
|
||||
|
||||
``` yaml
|
||||
theme:
|
||||
features:
|
||||
- search.share
|
||||
```
|
||||
|
||||
When a user clicks the share button, the URL is automatically copied to the
|
||||
clipboard.
|
||||
|
||||
## Usage
|
||||
|
||||
### Search boosting
|
||||
|
||||
<!-- md:version 8.3.0 -->
|
||||
<!-- md:flag metadata -->
|
||||
|
||||
Pages can be boosted in search with the front matter `search.boost` property,
|
||||
which will make them rank higher. Add the following lines at the top of a
|
||||
Markdown file:
|
||||
|
||||
=== ":material-arrow-up-circle: Rank up"
|
||||
|
||||
``` yaml
|
||||
---
|
||||
search:
|
||||
boost: 2 # (1)!
|
||||
---
|
||||
|
||||
# Page title
|
||||
...
|
||||
```
|
||||
|
||||
1. :woman_in_lotus_position: When boosting pages, be gentle and start with
|
||||
__low values__.
|
||||
|
||||
=== ":material-arrow-down-circle: Rank down"
|
||||
|
||||
``` yaml
|
||||
---
|
||||
search:
|
||||
boost: 0.5
|
||||
---
|
||||
|
||||
# Page title
|
||||
...
|
||||
```
|
||||
|
||||
### Search exclusion
|
||||
|
||||
<!-- md:version 9.0.0 -->
|
||||
<!-- md:flag metadata -->
|
||||
<!-- md:flag experimental -->
|
||||
|
||||
Pages can be excluded from search with the front matter `search.exclude`
|
||||
property, removing them from the index. Add the following lines at the top of a
|
||||
Markdown file:
|
||||
|
||||
``` yaml
|
||||
---
|
||||
search:
|
||||
exclude: true
|
||||
---
|
||||
|
||||
# Page title
|
||||
...
|
||||
```
|
||||
|
||||
#### Excluding sections
|
||||
|
||||
When [Attribute Lists] is enabled, specific sections of pages can be excluded
|
||||
from search by adding the `data-search-exclude` pragma after a Markdown
|
||||
heading:
|
||||
|
||||
=== ":octicons-file-code-16: `docs/page.md`"
|
||||
|
||||
``` markdown
|
||||
# Page title
|
||||
|
||||
## Section 1
|
||||
|
||||
The content of this section is included
|
||||
|
||||
## Section 2 { data-search-exclude }
|
||||
|
||||
The content of this section is excluded
|
||||
```
|
||||
|
||||
=== ":octicons-codescan-16: `search_index.json`"
|
||||
|
||||
``` json
|
||||
{
|
||||
...
|
||||
"docs": [
|
||||
{
|
||||
"location":"page/",
|
||||
"text":"",
|
||||
"title":"Document title"
|
||||
},
|
||||
{
|
||||
"location":"page/#section-1",
|
||||
"text":"<p>The content of this section is included</p>",
|
||||
"title":"Section 1"
|
||||
}
|
||||
]
|
||||
}
|
||||
```
|
||||
|
||||
[Attribute Lists]: extensions/python-markdown.md#attribute-lists
|
||||
|
||||
#### Excluding blocks
|
||||
|
||||
When [Attribute Lists] is enabled, specific sections of pages can be excluded
|
||||
from search by adding the `data-search-exclude` pragma after a Markdown
|
||||
inline- or block-level element:
|
||||
|
||||
=== ":octicons-file-code-16: `docs/page.md`"
|
||||
|
||||
``` markdown
|
||||
# Page title
|
||||
|
||||
The content of this block is included
|
||||
|
||||
The content of this block is excluded
|
||||
{ data-search-exclude }
|
||||
```
|
||||
|
||||
=== ":octicons-codescan-16: `search_index.json`"
|
||||
|
||||
``` json
|
||||
{
|
||||
...
|
||||
"docs": [
|
||||
{
|
||||
"location":"page/",
|
||||
"text":"<p>The content of this block is included</p>",
|
||||
"title":"Document title"
|
||||
}
|
||||
]
|
||||
}
|
||||
```
|
||||
@@ -0,0 +1,636 @@
|
||||
# Setting up social cards
|
||||
|
||||
Material for MkDocs can automatically create beautiful social cards for your
|
||||
documentation, which appear as link previews on social media platforms. You
|
||||
can select from several [pre-designed layouts][default layouts] or create
|
||||
[custom layouts] to match your unique style and branding.
|
||||
|
||||
---
|
||||
|
||||
:fontawesome-brands-youtube:{ style="color: #EE0F0F" }
|
||||
__[How to build custom social cards]__ by @james-willett – :octicons-clock-24:
|
||||
24m – Learn how to create entirely custom social cards perfectly matching your
|
||||
branding for each page automatically!
|
||||
|
||||
[How to build custom social cards]: https://www.youtube.com/watch?v=4OjnOc6ftJ8
|
||||
|
||||
<figure markdown>
|
||||
|
||||
[![Layout default variant]][Layout default variant]
|
||||
|
||||
<figcaption markdown>
|
||||
|
||||
Social card of our [formatting] reference
|
||||
|
||||
</figcaption>
|
||||
</figure>
|
||||
|
||||
[default layouts]: ../plugins/social.md#layouts
|
||||
[custom layouts]: #customization
|
||||
[formatting]: ../reference/formatting.md
|
||||
[Layout default variant]: ../assets/screenshots/social-cards-variant.png
|
||||
|
||||
## Configuration
|
||||
|
||||
### Built-in social plugin
|
||||
|
||||
<!-- md:version 8.5.0 -->
|
||||
<!-- md:plugin -->
|
||||
<!-- md:flag experimental -->
|
||||
<!-- md:demo create-social-cards -->
|
||||
|
||||
The built-in social plugin automatically generate a custom preview image for
|
||||
each page. Install all [dependencies for image processing] and add the
|
||||
following lines to `mkdocs.yml`:
|
||||
|
||||
``` yaml
|
||||
plugins:
|
||||
- social
|
||||
```
|
||||
|
||||
For a list of all settings, please consult the [plugin documentation].
|
||||
|
||||
[plugin documentation]: ../plugins/social.md
|
||||
|
||||
!!! info "The [`site_url`][site_url] setting must be set"
|
||||
|
||||
Note that you must set [`site_url`][site_url] when using the social plugin,
|
||||
or the generated cards will not be correctly linked. Social media services
|
||||
like X and Facebook demand that social previews point to an absolute
|
||||
URL, which the plugin can only compute when [`site_url`][site_url] is set.
|
||||
Example:
|
||||
|
||||
``` yaml
|
||||
site_url: https://example.com
|
||||
```
|
||||
|
||||
[dependencies for image processing]: ../plugins/requirements/image-processing.md
|
||||
[site_url]: https://www.mkdocs.org/user-guide/configuration/#site_url
|
||||
|
||||
## Usage
|
||||
|
||||
If you want to adjust the title or set a custom description for the social card,
|
||||
you can set the front matter [`title`][Changing the title] and
|
||||
[`description`][Changing the description] properties, which take precedence over
|
||||
the defaults, or use:
|
||||
|
||||
- [`cards_layout_options.title`](../plugins/social.md#option.title)
|
||||
- [`cards_layout_options.description`](../plugins/social.md#option.description)
|
||||
|
||||
[Changing the title]: ../reference/index.md#setting-the-page-title
|
||||
[Changing the description]: ../reference/index.md#setting-the-page-description
|
||||
|
||||
### Choosing a font
|
||||
|
||||
Some fonts do not contain CJK characters, like for example the
|
||||
[default font, `Roboto`][font]. In case your `site_name`, `site_description`, or
|
||||
page title contain CJK characters, choose another font from [Google Fonts] which
|
||||
comes with CJK characters, e.g. one from the `Noto Sans` font family:
|
||||
|
||||
=== "Chinese (Simplified)"
|
||||
|
||||
``` yaml
|
||||
plugins:
|
||||
- social:
|
||||
cards_layout_options:
|
||||
font_family: Noto Sans SC
|
||||
```
|
||||
|
||||
=== "Chinese (Traditional)"
|
||||
|
||||
``` yaml
|
||||
plugins:
|
||||
- social:
|
||||
cards_layout_options:
|
||||
font_family: Noto Sans TC
|
||||
```
|
||||
|
||||
=== "Japanese"
|
||||
|
||||
``` yaml
|
||||
plugins:
|
||||
- social:
|
||||
cards_layout_options:
|
||||
font_family: Noto Sans JP
|
||||
```
|
||||
|
||||
=== "Korean"
|
||||
|
||||
``` yaml
|
||||
plugins:
|
||||
- social:
|
||||
cards_layout_options:
|
||||
font_family: Noto Sans KR
|
||||
```
|
||||
|
||||
[font]: changing-the-fonts.md#regular-font
|
||||
|
||||
### Changing the layout
|
||||
|
||||
<!-- md:version 9.7.0 -->
|
||||
<!-- md:flag metadata -->
|
||||
<!-- md:flag experimental -->
|
||||
|
||||
If you want to use a different layout for a single page (e.g. your landing
|
||||
page), you can use the `social` front matter property together with the
|
||||
[`cards_layout`](../plugins/social.md#meta.social.cards_layout) key, exactly as
|
||||
in `mkdocs.yml`:
|
||||
|
||||
``` yaml
|
||||
---
|
||||
social:
|
||||
cards_layout: custom
|
||||
---
|
||||
|
||||
# Page title
|
||||
...
|
||||
```
|
||||
|
||||
You can apply those changes for entire subtrees of your documentation, e.g.,
|
||||
to generate different social cards for your blog and API reference, by using
|
||||
the [built-in meta plugin].
|
||||
|
||||
[built-in meta plugin]: ../plugins/meta.md
|
||||
|
||||
### Parametrizing the layout
|
||||
|
||||
<!-- md:version 9.7.0 -->
|
||||
<!-- md:flag metadata -->
|
||||
<!-- md:flag experimental -->
|
||||
|
||||
Besides changing the entire layout, you can override all options that a layout
|
||||
exposes. This means you can parametrize social cards with custom front matter
|
||||
properties, such as `tags`, `date`, `author` or anything you can think of.
|
||||
Simply define [`cards_layout_options`](../plugins/social.md#meta.social.cards_layout_options):
|
||||
|
||||
``` yaml
|
||||
---
|
||||
social:
|
||||
cards_layout_options:
|
||||
background_color: blue # Change background color
|
||||
background_image: null # Remove background image
|
||||
---
|
||||
|
||||
# Page title
|
||||
...
|
||||
```
|
||||
|
||||
You can apply those changes for entire subtrees of your documentation, e.g.,
|
||||
to generate different social cards for your blog and API reference, by using
|
||||
the [built-in meta plugin].
|
||||
|
||||
### Disabling social cards
|
||||
|
||||
<!-- md:version 9.7.0 -->
|
||||
<!-- md:flag metadata -->
|
||||
<!-- md:flag experimental -->
|
||||
|
||||
If you wish to disable social cards for a page, simply add the following to the
|
||||
front matter of the Markdown document:
|
||||
|
||||
``` yaml
|
||||
---
|
||||
social:
|
||||
cards: false
|
||||
---
|
||||
|
||||
# Page title
|
||||
...
|
||||
```
|
||||
|
||||
## Customization
|
||||
|
||||
<!-- md:version 9.7.0 -->
|
||||
<!-- md:flag experimental -->
|
||||
|
||||
<div class="mdx-social">
|
||||
<div class="mdx-social__layer">
|
||||
<div class="mdx-social__image">
|
||||
<span class="mdx-social__label">Layer 0</span>
|
||||
<img src="../../assets/screenshots/social-cards-layer-0.png" />
|
||||
</div>
|
||||
</div>
|
||||
<div class="mdx-social__layer">
|
||||
<div class="mdx-social__image">
|
||||
<span class="mdx-social__label">Layer 1</span>
|
||||
<img src="../../assets/screenshots/social-cards-layer-1.png" />
|
||||
</div>
|
||||
</div>
|
||||
<div class="mdx-social__layer">
|
||||
<div class="mdx-social__image">
|
||||
<span class="mdx-social__label">Layer 2</span>
|
||||
<img src="../../assets/screenshots/social-cards-layer-2.png" />
|
||||
</div>
|
||||
</div>
|
||||
<div class="mdx-social__layer">
|
||||
<div class="mdx-social__image">
|
||||
<span class="mdx-social__label">Layer 3</span>
|
||||
<img src="../../assets/screenshots/social-cards-layer-3.png" />
|
||||
</div>
|
||||
</div>
|
||||
<div class="mdx-social__layer">
|
||||
<div class="mdx-social__image">
|
||||
<span class="mdx-social__label">Layer 4</span>
|
||||
<img src="../../assets/screenshots/social-cards-layer-4.png" />
|
||||
</div>
|
||||
</div>
|
||||
<div class="mdx-social__layer">
|
||||
<div class="mdx-social__image">
|
||||
<span class="mdx-social__label">Layer 5</span>
|
||||
<img src="../../assets/screenshots/social-cards-layer-5.png" />
|
||||
</div>
|
||||
</div>
|
||||
</div>
|
||||
|
||||
Social cards are composed of layers, analogous to how they are represented in
|
||||
graphic design software such as Adobe Photoshop. As many layers are common
|
||||
across the cards generated for each page (e.g., backgrounds or logos), the
|
||||
built-in social plugin can automatically deduplicate layers and render them
|
||||
just once, substantially accelerating card generation. The generated cards are
|
||||
cached to ensure they are only regenerated when their contents change.
|
||||
|
||||
Layouts are written in YAML syntax. Before starting to create a custom layout,
|
||||
it is a good idea to [study the pre-designed layouts], in order to get a better
|
||||
understanding of how they work. Then, create a new layout and reference it in
|
||||
`mkdocs.yml`:
|
||||
|
||||
=== ":octicons-file-code-16: `layouts/custom.yml`"
|
||||
|
||||
``` yaml
|
||||
size: { width: 1200, height: 630 }
|
||||
layers: []
|
||||
```
|
||||
|
||||
=== ":octicons-file-code-16: `mkdocs.yml`"
|
||||
|
||||
``` yaml
|
||||
plugins:
|
||||
- social:
|
||||
cards_layout_dir: layouts
|
||||
cards_layout: custom
|
||||
debug: true
|
||||
```
|
||||
|
||||
Note that the `.yml` file extension should be omitted. Next, run `mkdocs serve`,
|
||||
and see how the `.cache` directory is populated with the generated cards. Open
|
||||
any card in your editor, so you can see your changes immediately. Since we
|
||||
haven't defined any layers, the cards are transparent.
|
||||
|
||||
The following sections explain how to create custom layouts.
|
||||
|
||||
[built-in social plugin]: ../plugins/social.md
|
||||
[Google Fonts]: https://fonts.google.com/
|
||||
[Jinja templates]: https://jinja.palletsprojects.com/en/3.1.x/
|
||||
[study the pre-designed layouts]: https://github.com/squidfunk/mkdocs-material/tree/master/src/plugins/social/layouts
|
||||
|
||||
### Size and offset
|
||||
|
||||
Each layer has an associated size and offset, which is defined in pixels. The
|
||||
`size` is defined by a `width` and `height` property, and the `offset` by `x`
|
||||
and `y` properties:
|
||||
|
||||
``` yaml
|
||||
size: { width: 1200, height: 630 }
|
||||
layers:
|
||||
- size: { width: 1200, height: 630 }
|
||||
offset: { x: 0, y: 0 }
|
||||
```
|
||||
|
||||
If the `size` is omitted, it defaults to the size of the layout. If the `offset`
|
||||
is omitted, it defaults to the top left corner, which is the default `origin`.
|
||||
Saving the layout and reloading renders:
|
||||
|
||||
![Layer size]
|
||||
|
||||
The layer outline and grid are visible because we enabled [`debug`][debug]
|
||||
mode in `mkdocs.yml`. The top left shows the layer index and offset, which is
|
||||
useful for alignment and composition.
|
||||
|
||||
[Layer size]: ../assets/screenshots/social-cards-layer-size.png
|
||||
[debug]: ../plugins/social.md#debugging
|
||||
|
||||
#### Origin
|
||||
|
||||
<!-- md:version 9.7.0 -->
|
||||
<!-- md:flag experimental -->
|
||||
|
||||
The `origin` for the `x` and `y` values can be changed, so that the layer is
|
||||
aligned to one of the edges or corners of the layout, e.g., to the bottom right
|
||||
corner of the layout:
|
||||
|
||||
``` yaml hl_lines="5"
|
||||
size: { width: 1200, height: 630 }
|
||||
layers:
|
||||
- size: { width: 1200, height: 630 }
|
||||
offset: { x: 0, y: 0 }
|
||||
origin: end bottom
|
||||
```
|
||||
|
||||
The following table shows the supported values:
|
||||
|
||||
<figure markdown>
|
||||
|
||||
| Origin | | |
|
||||
| -------------- | --------------- | ------------ |
|
||||
| :material-arrow-top-left: `start top` | :material-arrow-up: `center top` | :material-arrow-top-right: `end top` |
|
||||
| :material-arrow-left: `start center` | :material-circle-small: `center` | :material-arrow-right: `end center` |
|
||||
| :material-arrow-bottom-left: `start bottom` | :material-arrow-down: `center bottom` | :material-arrow-bottom-right: `end bottom` |
|
||||
|
||||
<figcaption>
|
||||
Supported values for origin
|
||||
</figcaption>
|
||||
</figure>
|
||||
|
||||
### Backgrounds
|
||||
|
||||
Each layer can be assigned a background color and image. If both are given, the
|
||||
color is rendered on top of the image, allowing for semi-transparent, tinted
|
||||
backgrounds:
|
||||
|
||||
=== "Background color"
|
||||
|
||||
``` yaml
|
||||
size: { width: 1200, height: 630 }
|
||||
layers:
|
||||
- background:
|
||||
color: "#4051b5"
|
||||
```
|
||||
|
||||
![Layer background color]
|
||||
|
||||
=== "Background image"
|
||||
|
||||
``` yaml
|
||||
size: { width: 1200, height: 630 }
|
||||
layers:
|
||||
- background:
|
||||
image: layouts/background.png
|
||||
```
|
||||
|
||||
![Layer background image]
|
||||
|
||||
=== "Background image, tinted"
|
||||
|
||||
``` yaml
|
||||
size: { width: 1200, height: 630 }
|
||||
layers:
|
||||
- background:
|
||||
image: layouts/background.png
|
||||
color: "#4051b5ee" # (1)!
|
||||
```
|
||||
|
||||
1. The color value can be set to a [CSS color keyword], or a 3, 4, 6 or 8
|
||||
letter HEX color code, allowing for semi-transparent layers.
|
||||
|
||||
![Layer background]
|
||||
|
||||
Background images are automatically scaled to fit the layer while preserving
|
||||
aspect-ratio. Notice how we omitted `size` and `offset`, because we want to
|
||||
fill the entire area of the social card.
|
||||
|
||||
[Layer background color]: ../assets/screenshots/social-cards-layer-background-color.png
|
||||
[Layer background image]: ../assets/screenshots/social-cards-layer-background-image.png
|
||||
[Layer background]: ../assets/screenshots/social-cards-layer-background.png
|
||||
|
||||
### Typography
|
||||
|
||||
Now, we can add dynamic typography that is sourced from Markdown files - this is
|
||||
the actual raison d'être of the [built-in social plugin]. [Jinja templates] are
|
||||
used to render a text string that is then added to the image:
|
||||
|
||||
``` yaml
|
||||
size: { width: 1200, height: 630 }
|
||||
layers:
|
||||
- size: { width: 832, height: 310 }
|
||||
offset: { x: 62, y: 160 }
|
||||
typography:
|
||||
content: "{{ page.title }}" # (1)!
|
||||
align: start
|
||||
color: white
|
||||
line:
|
||||
amount: 3
|
||||
height: 1.25
|
||||
font:
|
||||
family: Roboto
|
||||
style: Bold
|
||||
```
|
||||
|
||||
1. The following variables can be used in [Jinja templates]:
|
||||
|
||||
- [`config.*`][config variable]
|
||||
- [`page.*`][page variable]
|
||||
- [`layout.*`][layout options]
|
||||
|
||||
The author is free in defining `layout.*` options, which can be used to pass
|
||||
arbitrary data to the layout from `mkdocs.yml`.
|
||||
|
||||
This renders a text layer with the title of the page with a line height of 1.25,
|
||||
and a maximum number of 3 lines. The plugin automatically computes the font size
|
||||
from the line height, the number of lines, and font metrics like ascender and
|
||||
descender.[^2] This renders:
|
||||
|
||||
[^2]:
|
||||
If the plugin would require the author to specify the font size and line
|
||||
height manually, it would be impossible to guarantee that the text fits
|
||||
into the layer. For this reason we implemented a declarative approach,
|
||||
where the author specifies the desired line height and number of lines, and
|
||||
the plugin computes the font size automatically.
|
||||
|
||||
![Layer typography]
|
||||
|
||||
[config variable]: https://www.mkdocs.org/dev-guide/themes/#config
|
||||
[page variable]: https://www.mkdocs.org/dev-guide/themes/#page
|
||||
[Layer typography]: ../assets/screenshots/social-cards-layer-typography.png
|
||||
|
||||
#### Overflow
|
||||
|
||||
If the text overflows the layer, there are two possible behaviors: either the
|
||||
text is automatically truncated and shortened with an ellipsis, or the text is
|
||||
automatically scaled down to fit the layer:
|
||||
|
||||
``` { .markdown .no-copy }
|
||||
# If we use a very long headline, we can see how the text will be truncated
|
||||
```
|
||||
|
||||
=== ":octicons-ellipsis-16: Ellipsis"
|
||||
|
||||
![Layer typography ellipsis]
|
||||
|
||||
=== ":material-arrow-collapse: Shrink"
|
||||
|
||||
![Layer typography shrink]
|
||||
|
||||
While truncating with an ellipsis is the default, auto-shrinking can be enabled
|
||||
by setting `overflow` to `shrink`:
|
||||
|
||||
``` yaml hl_lines="7"
|
||||
size: { width: 1200, height: 630 }
|
||||
layers:
|
||||
- size: { width: 832, height: 310 }
|
||||
offset: { x: 62, y: 160 }
|
||||
typography:
|
||||
content: "{{ page.title }}"
|
||||
overflow: shrink
|
||||
align: start
|
||||
color: white
|
||||
line:
|
||||
amount: 3
|
||||
height: 1.25
|
||||
font:
|
||||
family: Roboto
|
||||
style: Bold
|
||||
```
|
||||
|
||||
[Layer typography ellipsis]: ../assets/screenshots/social-cards-layer-typography-ellipsis.png
|
||||
[Layer typography shrink]: ../assets/screenshots/social-cards-layer-typography-shrink.png
|
||||
|
||||
#### Alignment
|
||||
|
||||
Text can be aligned to all corners and edges of the layer. For example, if we
|
||||
want to align the text to the middle of the layer, we can set `align` to `start center`, which will render as:
|
||||
|
||||
![Layer typography align]
|
||||
|
||||
[Layer typography align]: ../assets/screenshots/social-cards-layer-typography-align.png
|
||||
|
||||
The following table shows the supported values:
|
||||
|
||||
<figure markdown>
|
||||
|
||||
| Alignment | | |
|
||||
| -------------- | --------------- | ------------ |
|
||||
| :material-arrow-top-left: `start top` | :material-arrow-up: `center top` | :material-arrow-top-right: `end top` |
|
||||
| :material-arrow-left: `start center` | :material-circle-small: `center` | :material-arrow-right: `end center` |
|
||||
| :material-arrow-bottom-left: `start bottom` | :material-arrow-down: `center bottom` | :material-arrow-bottom-right: `end bottom` |
|
||||
|
||||
<figcaption>
|
||||
Supported values for text alignment
|
||||
</figcaption>
|
||||
</figure>
|
||||
|
||||
#### Font
|
||||
|
||||
The [built-in social plugin] integrates with [Google Fonts] and will
|
||||
automatically download the font files for you. The `font` property accepts a
|
||||
`family` and `style` property, where the `family` must be set to the name of the
|
||||
font, and the `style` to one of the supported font styles. For example, setting
|
||||
`family` to `Roboto` will automatically download the following files:
|
||||
|
||||
``` { .sh .no-copy #example }
|
||||
.cache/plugins/social/fonts
|
||||
└─ Roboto/
|
||||
├─ Black.ttf
|
||||
├─ Black Italic.ttf
|
||||
├─ Bold.ttf
|
||||
├─ Bold Italic.ttf
|
||||
├─ Italic.ttf
|
||||
├─ Light.ttf
|
||||
├─ Light Italic.ttf
|
||||
├─ Medium.ttf
|
||||
├─ Medium Italic.ttf
|
||||
├─ Regular.ttf
|
||||
├─ Thin.ttf
|
||||
└─ Thin Italic.ttf
|
||||
```
|
||||
|
||||
In that case, the author can use `Bold` or `Medium Italic` as the `style`. If
|
||||
the font style specified in the layer is not part of the font family, the
|
||||
font always falls back to `Regular` and prints a warning in [`debug`][debug]
|
||||
mode, as `Regular` is included with all font families.
|
||||
|
||||
### Icons
|
||||
|
||||
Authors can leverage the full range of icons that are shipped with Material for
|
||||
MkDocs, or even provide custom icons by using theme extension and going through
|
||||
the process described in the guide on [additional icons]. Icons can even be
|
||||
tinted by using the `color` property:
|
||||
|
||||
``` yaml
|
||||
size: { width: 1200, height: 630 }
|
||||
layers:
|
||||
- background:
|
||||
color: "#4051b5"
|
||||
- size: { width: 144, height: 144 }
|
||||
offset: { x: 992, y: 64 }
|
||||
icon:
|
||||
value: material/cat
|
||||
color: white
|
||||
```
|
||||
|
||||
This will render the icon in the top right corner of the social card:
|
||||
|
||||
![Layer icon]
|
||||
|
||||
The possibilities are endless. For example, icons can be used to draw shapes
|
||||
like circles:
|
||||
|
||||
``` yaml
|
||||
size: { width: 1200, height: 630 }
|
||||
layers:
|
||||
- background:
|
||||
color: "#4051b5"
|
||||
- size: { width: 2400, height: 2400 }
|
||||
offset: { x: -1024, y: 64 }
|
||||
icon:
|
||||
value: material/circle
|
||||
color: "#5c6bc0"
|
||||
- size: { width: 1800, height: 1800 }
|
||||
offset: { x: 512, y: -1024 }
|
||||
icon:
|
||||
value: material/circle
|
||||
color: "#3949ab"
|
||||
```
|
||||
|
||||
This will add two circles to the background:
|
||||
|
||||
![Layer icon circles]
|
||||
|
||||
### Tags
|
||||
|
||||
The new [built-in social plugin] gives full flexibility of the meta tags that
|
||||
are added to your site, which are necessary to instruct services like X
|
||||
or Discord how to display your social card. All default layouts use the following
|
||||
set of tags, which you can copy to your layout and adapt:
|
||||
|
||||
``` yaml
|
||||
definitions:
|
||||
|
||||
- &page_title_with_site_name >-
|
||||
{%- if not page.is_homepage -%}
|
||||
{{ page.meta.get("title", page.title) }} - {{ config.site_name }}
|
||||
{%- else -%}
|
||||
{{ page.meta.get("title", page.title) }}
|
||||
{%- endif -%}
|
||||
|
||||
- &page_description >-
|
||||
{{ page.meta.get("description", config.site_description) or "" }}
|
||||
|
||||
tags:
|
||||
|
||||
og:type: website
|
||||
og:title: *page_title_with_site_name
|
||||
og:description: *page_description
|
||||
og:image: "{{ image.url }}"
|
||||
og:image:type: "{{ image.type }}"
|
||||
og:image:width: "{{ image.width }}"
|
||||
og:image:height: "{{ image.height }}"
|
||||
og:url: "{{ page.canonical_url }}"
|
||||
|
||||
twitter:card: summary_large_image
|
||||
twitter:title: *page_title_with_site_name
|
||||
twitter:description: *page_description
|
||||
twitter:image: "{{ image.url }}"
|
||||
```
|
||||
|
||||
Note that this example makes use of [YAML anchors] to minify repetition. The
|
||||
`definitions` property is solely intended for the definition on aliases that
|
||||
can then be referenced with anchors.
|
||||
|
||||
[YAML anchors]: https://support.atlassian.com/bitbucket-cloud/docs/yaml-anchors/
|
||||
|
||||
__Are you missing something? Please [open a discussion] and let us know!__
|
||||
|
||||
[additional icons]: ./changing-the-logo-and-icons.md#additional-icons
|
||||
[Layer icon]: ../assets/screenshots/social-cards-layer-icon.png
|
||||
[Layer icon circles]: ../assets/screenshots/social-cards-layer-icon-circles.png
|
||||
[open a discussion]: https://github.com/squidfunk/mkdocs-material/discussions/new
|
||||
@@ -0,0 +1,310 @@
|
||||
# Setting up tags
|
||||
|
||||
Material for MkDocs adds first-class support for categorizing pages with tags,
|
||||
which adds the possibility to group related pages and make them discoverable
|
||||
via search and a dedicated [tags index]. If your documentation is large, tags
|
||||
can help to discover relevant information faster.
|
||||
|
||||
[tags index]: #adding-a-tags-index
|
||||
|
||||
## Configuration
|
||||
|
||||
### Built-in tags plugin
|
||||
|
||||
<!-- md:version 8.2.0 -->
|
||||
<!-- md:plugin -->
|
||||
|
||||
The built-in tags plugin adds the ability to categorize any page with tags
|
||||
as part of the front matter of the page. In order to add support for tags, add
|
||||
the following lines to `mkdocs.yml`:
|
||||
|
||||
``` yaml
|
||||
plugins:
|
||||
- tags
|
||||
```
|
||||
|
||||
For a list of all settings, please consult the [plugin documentation].
|
||||
|
||||
[plugin documentation]: ../plugins/tags.md
|
||||
|
||||
### Tag icons and identifiers
|
||||
|
||||
<!-- md:version 8.5.0 -->
|
||||
<!-- md:flag experimental -->
|
||||
<!-- md:example tags-with-icons -->
|
||||
|
||||
Each tag can be associated with an icon, which is then rendered inside the tag.
|
||||
Before assigning icons to tags, associate each tag with a unique identifier,
|
||||
by adding the following to `mkdocs.yml`:
|
||||
|
||||
``` yaml
|
||||
extra:
|
||||
tags:
|
||||
<tag>: <identifier> # (1)!
|
||||
```
|
||||
|
||||
1. The identifier can only include alphanumeric characters, as well as dashes
|
||||
and underscores. For example, if you have a tag `Compatibility`, you can
|
||||
set `compat` as an identifier:
|
||||
|
||||
``` yaml
|
||||
extra:
|
||||
tags:
|
||||
Compatibility: compat
|
||||
```
|
||||
|
||||
Identifiers can be reused between tags. Tags which are not explicitly
|
||||
associated will use the default tag icon which is :material-pound:
|
||||
|
||||
Next, each identifier can be associated with an icon, even a [custom icon], by
|
||||
adding the following lines to `mkdocs.yml` under the `theme.icon` configuration
|
||||
setting:
|
||||
|
||||
=== "Tag icon"
|
||||
|
||||
``` yaml
|
||||
theme:
|
||||
icon:
|
||||
tag:
|
||||
<identifier>: <icon> # (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="tag" />
|
||||
<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>
|
||||
|
||||
=== "Tag default icon"
|
||||
|
||||
``` yaml
|
||||
theme:
|
||||
icon:
|
||||
tag:
|
||||
default: <icon>
|
||||
```
|
||||
|
||||
??? example "Expand to inspect example"
|
||||
|
||||
``` yaml
|
||||
theme:
|
||||
icon:
|
||||
tag:
|
||||
html: fontawesome/brands/html5
|
||||
js: fontawesome/brands/js
|
||||
css: fontawesome/brands/css3
|
||||
extra:
|
||||
tags:
|
||||
HTML5: html
|
||||
JavaScript: js
|
||||
CSS: css
|
||||
```
|
||||
|
||||
[custom icon]: changing-the-logo-and-icons.md#additional-icons
|
||||
[icon search]: ../reference/icons-emojis.md#search
|
||||
|
||||
## Usage
|
||||
|
||||
### Adding tags
|
||||
|
||||
<!-- md:version 8.2.0 -->
|
||||
<!-- md:example tags -->
|
||||
|
||||
When the [built-in tags plugin] is enabled, tags can be added for a document
|
||||
with the front matter `tags` property. Add the following lines at the top of a
|
||||
Markdown file:
|
||||
|
||||
``` sh
|
||||
---
|
||||
tags:
|
||||
- HTML5
|
||||
- JavaScript
|
||||
- CSS
|
||||
---
|
||||
|
||||
...
|
||||
```
|
||||
|
||||
The page will now render with those tags above the main headline and within the
|
||||
search preview, which now allows to __find pages by tags__.
|
||||
|
||||
??? question "How to set tags for an entire folder?"
|
||||
|
||||
With the help of the [built-in meta plugin], you can ensure that tags are
|
||||
set for an entire section and all nested pages, by creating a `.meta.yml`
|
||||
file in the corresponding folder with the following content:
|
||||
|
||||
``` yaml
|
||||
tags:
|
||||
- HTML5
|
||||
- JavaScript
|
||||
- CSS
|
||||
```
|
||||
|
||||
The tags set in `.meta.yml` are merged and deduplicated with the tags
|
||||
defined for a page, which means you can define common tags in `.meta.yml`
|
||||
and then add specific tags for each page. The tags in `.meta.yml` are
|
||||
appended.
|
||||
|
||||
[built-in tags plugin]: ../plugins/tags.md
|
||||
[built-in meta plugin]: ../plugins/meta.md
|
||||
|
||||
### Adding a tags index
|
||||
|
||||
<!-- md:version 8.2.0 -->
|
||||
<!-- md:example tags -->
|
||||
|
||||
The [built-in tags plugin] allows to define a file to render a tags index,
|
||||
which can be any page that is part of the `nav` section. To add a tags index,
|
||||
create a page, e.g. `tags.md`:
|
||||
|
||||
``` markdown
|
||||
# Tags
|
||||
|
||||
Following is a list of relevant tags:
|
||||
|
||||
<!-- material/tags -->
|
||||
```
|
||||
|
||||
The tags marker specifies the position of the tags index, i.e. it is
|
||||
replaced with the actual tags index when the page is rendered. You can include
|
||||
arbitrary content before and after the marker:
|
||||
|
||||
[![Tags index][tags index enabled]][tags index enabled]
|
||||
|
||||
[tags index enabled]: ../assets/screenshots/tags-index.png
|
||||
|
||||
### Advanced features
|
||||
|
||||
#### Configurable listings
|
||||
|
||||
<!-- md:version 9.6.0 -->
|
||||
<!-- md:flag experimental -->
|
||||
|
||||
Listings can be configured in `mkdocs.yml` or directly at the location of the
|
||||
marker that you position in a Markdown document. Some examples:
|
||||
|
||||
- __Use [scoped listings]__: limit the tags index to pages that are on the same
|
||||
level of the subsection of the documentation the page is in:
|
||||
|
||||
``` html
|
||||
<!-- material/tags { scope: true } -->
|
||||
```
|
||||
|
||||
- __List only specific tags__: limit the tags index to a single or multiple
|
||||
selected tags, e.g., `Foo` and `Bar`, excluding all other tags:
|
||||
|
||||
``` html
|
||||
<!-- material/tags { include: [Foo, Bar] } -->
|
||||
```
|
||||
|
||||
- __Exclude pages with specific tags__: don't include pages that are tagged
|
||||
with specific tags, e.g. `Internal`. This can be any tag, including a shadow
|
||||
tag:
|
||||
|
||||
``` html
|
||||
<!-- material/tags { exclude: [Internal] } -->
|
||||
```
|
||||
|
||||
- __Enable or disable tags inside the table of contents__: specify whether the
|
||||
table of contents lists all tags under the nearest headline:
|
||||
|
||||
``` html
|
||||
<!-- material/tags { toc: false } -->
|
||||
```
|
||||
|
||||
See the [listing configuration] for all options.
|
||||
|
||||
[listing configuration]: ../plugins/tags.md#listing-configuration
|
||||
|
||||
#### Scoped listings
|
||||
|
||||
<!-- md:version 9.7.0 -->
|
||||
<!-- md:flag experimental -->
|
||||
|
||||
If your documentation is large, you might want to consider using scoped listings
|
||||
which will only include pages that are on the same level or below the page
|
||||
containing the listing. Just use:
|
||||
|
||||
``` html
|
||||
<!-- material/tags { scope: true } -->
|
||||
```
|
||||
|
||||
If you plan to use multiple scoped indexes, it's a good idea to define a
|
||||
listing configuration in `mkdocs.yml`, which you can then reference by its id:
|
||||
|
||||
``` yaml
|
||||
plugins:
|
||||
- tags:
|
||||
listings_map:
|
||||
scoped:
|
||||
scope: true
|
||||
```
|
||||
|
||||
You can now use:
|
||||
|
||||
``` html
|
||||
<!-- material/tags scoped -->
|
||||
```
|
||||
|
||||
#### Shadow tags
|
||||
|
||||
<!-- md:version 9.7.0 -->
|
||||
<!-- md:flag experimental -->
|
||||
|
||||
Shadow tags are tags that are solely meant to organization, which can be
|
||||
included or excluded for rendering with a simple flag. They can be enumerated
|
||||
in the [`shadow_tags`][config.shadow_tags] setting:
|
||||
|
||||
``` yaml
|
||||
plugins:
|
||||
- tags:
|
||||
shadow_tags:
|
||||
- Draft
|
||||
- Internal
|
||||
```
|
||||
|
||||
If a document is tagged with `Draft`, the tag will only be rendered if
|
||||
[`shadow`][config.shadow] setting is enabled, and excluded when it is disabled.
|
||||
This is an excellent opportunity for using tags for structuring.
|
||||
|
||||
[config.shadow]: ../plugins/tags.md#config.shadow
|
||||
[config.shadow_tags]: ../plugins/tags.md#config.shadow_tags
|
||||
|
||||
#### Nested tags
|
||||
|
||||
<!-- md:version 9.7.0 -->
|
||||
<!-- md:flag experimental -->
|
||||
|
||||
The [`tags_hierarchy_separator`][config.tags_hierarchy_separator] allows to
|
||||
create hierarchies of tags, e.g., `Foo/Bar`. Nested tags will be rendered as
|
||||
children of the parent tag:
|
||||
|
||||
``` yaml
|
||||
plugins:
|
||||
- tags:
|
||||
tags_hierarchy: true
|
||||
```
|
||||
|
||||
[config.tags_hierarchy_separator]: ../plugins/tags.md#config.tags_hierarchy_separator
|
||||
|
||||
### Hiding tags on a page
|
||||
|
||||
While the tags are rendered above the main headline, sometimes, it might be
|
||||
desirable to hide them for a specific page, which can be achieved with the
|
||||
front matter `hide` property:
|
||||
|
||||
``` yaml
|
||||
---
|
||||
hide:
|
||||
- tags
|
||||
---
|
||||
|
||||
# Page title
|
||||
...
|
||||
```
|
||||
@@ -0,0 +1,182 @@
|
||||
# Setting up the footer
|
||||
|
||||
The footer of your project documentation is a great place to add links to
|
||||
websites or platforms you or your company are using as additional marketing
|
||||
channels, e.g. :fontawesome-brands-mastodon:{ style="color: #5A4CE0" } or
|
||||
:fontawesome-brands-youtube:{ style="color: #EE0F0F" }, which you can easily
|
||||
configure via `mkdocs.yml`.
|
||||
|
||||
## Configuration
|
||||
|
||||
### Navigation
|
||||
|
||||
<!-- md:version 9.0.0 -->
|
||||
<!-- md:feature -->
|
||||
|
||||
The footer can include links to the previous and next page of the current page.
|
||||
If you wish to enable this behavior, add the following lines to `mkdocs.yml`:
|
||||
|
||||
``` yaml
|
||||
theme:
|
||||
features:
|
||||
- navigation.footer
|
||||
```
|
||||
|
||||
### Social links
|
||||
|
||||
<!-- md:version 1.0.0 -->
|
||||
<!-- md:default none -->
|
||||
|
||||
Social links are rendered next to the copyright notice as part of the
|
||||
footer of your project documentation. Add a list of social links in `mkdocs.yml`
|
||||
with:
|
||||
|
||||
``` yaml
|
||||
extra:
|
||||
social:
|
||||
- icon: fontawesome/brands/mastodon # (1)!
|
||||
link: https://fosstodon.org/@squidfunk
|
||||
```
|
||||
|
||||
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="mastodon" />
|
||||
<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>
|
||||
|
||||
The following properties are available for each link:
|
||||
|
||||
<!-- md:option social.icon -->
|
||||
|
||||
: <!-- md:default none --> <!-- md:flag required -->
|
||||
This property must contain a valid path to any icon bundled with the theme,
|
||||
or the build will not succeed. Some popular choices:
|
||||
|
||||
* :fontawesome-brands-github: – `fontawesome/brands/github`
|
||||
* :fontawesome-brands-gitlab: – `fontawesome/brands/gitlab`
|
||||
* :fontawesome-brands-x-twitter: – `fontawesome/brands/x-twitter`
|
||||
* :fontawesome-brands-mastodon: – `fontawesome/brands/mastodon`
|
||||
<small>automatically adds [`rel=me`][rel=me]</small>
|
||||
* :fontawesome-brands-docker: – `fontawesome/brands/docker`
|
||||
* :fontawesome-brands-facebook: – `fontawesome/brands/facebook`
|
||||
* :fontawesome-brands-instagram: – `fontawesome/brands/instagram`
|
||||
* :fontawesome-brands-linkedin: – `fontawesome/brands/linkedin`
|
||||
* :fontawesome-brands-slack: – `fontawesome/brands/slack`
|
||||
* :fontawesome-brands-discord: – `fontawesome/brands/discord`
|
||||
* :fontawesome-brands-pied-piper-alt: – `fontawesome/brands/pied-piper-alt`
|
||||
|
||||
<!-- md:option social.link -->
|
||||
|
||||
: <!-- md:default none --> <!-- md:flag required -->
|
||||
This property must be set to a relative or absolute URL including the URI
|
||||
scheme. All URI schemes are supported, including `mailto` and `bitcoin`:
|
||||
|
||||
=== ":fontawesome-brands-mastodon: Mastodon"
|
||||
|
||||
``` yaml
|
||||
extra:
|
||||
social:
|
||||
- icon: fontawesome/brands/mastodon
|
||||
link: https://fosstodon.org/@squidfunk
|
||||
```
|
||||
|
||||
=== ":octicons-mail-16: Email"
|
||||
|
||||
``` yaml
|
||||
extra:
|
||||
social:
|
||||
- icon: fontawesome/solid/paper-plane
|
||||
link: mailto:<email-address>
|
||||
```
|
||||
|
||||
<!-- md:option social.name -->
|
||||
|
||||
: <!-- md:default _domain name from_ `link`_, if available_ -->
|
||||
This property is used as the link's `title` attribute and can be set to a
|
||||
discernable name to improve accessibility:
|
||||
|
||||
``` yaml
|
||||
extra:
|
||||
social:
|
||||
- icon: fontawesome/brands/mastodon
|
||||
link: https://fosstodon.org/@squidfunk
|
||||
name: squidfunk on Fosstodon
|
||||
```
|
||||
|
||||
[icon search]: ../reference/icons-emojis.md#search
|
||||
[rel=me]: https://docs.joinmastodon.org/user/profile/#verification
|
||||
|
||||
### Copyright notice
|
||||
|
||||
<!-- md:version 0.1.0 -->
|
||||
<!-- md:default none -->
|
||||
|
||||
A custom copyright banner can be rendered as part of the footer, which is
|
||||
displayed next to the social links. It can be defined as part of `mkdocs.yml`:
|
||||
|
||||
``` yaml
|
||||
copyright: Copyright © 2016 - 2020 Martin Donath
|
||||
```
|
||||
|
||||
### Generator notice
|
||||
|
||||
<!-- md:version 7.3.0 -->
|
||||
<!-- md:default `true` -->
|
||||
|
||||
The footer displays a _Made with Material for MkDocs_ notice to denote how
|
||||
the site was generated. The notice can be removed with the following option
|
||||
via `mkdocs.yml`:
|
||||
|
||||
``` yaml
|
||||
extra:
|
||||
generator: false
|
||||
```
|
||||
|
||||
!!! info "Please read this before removing the generator notice"
|
||||
|
||||
The subtle __Made with Material for MkDocs__ hint in the footer is one of
|
||||
the reasons why this project is so popular, as it tells the user how the
|
||||
site is generated, helping new users to discover this project. Before
|
||||
removing please consider that you're enjoying the benefits of @squidfunk's
|
||||
work for free, as this project is Open Source and has a permissive license.
|
||||
Thousands of hours went into this project, most of them
|
||||
without any financial return.
|
||||
|
||||
## Usage
|
||||
|
||||
### Hiding prev/next links
|
||||
|
||||
The footer navigation showing links to the previous and next page can be hidden
|
||||
with the front matter `hide` property. Add the following lines at the top of a
|
||||
Markdown file:
|
||||
|
||||
``` yaml
|
||||
---
|
||||
hide:
|
||||
- footer
|
||||
---
|
||||
|
||||
# Page title
|
||||
...
|
||||
```
|
||||
|
||||
## Customization
|
||||
|
||||
### Custom copyright
|
||||
|
||||
<!-- md:version 8.0.0 -->
|
||||
<!-- md:flag customization -->
|
||||
|
||||
In order to customize and override the [copyright notice], [extend the theme]
|
||||
and [override the `copyright.html` partial][overriding partials], which normally
|
||||
includes the `copyright` property set in `mkdocs.yml`.
|
||||
|
||||
[copyright notice]: #copyright-notice
|
||||
[generator notice]: #generator-notice
|
||||
[extend the theme]: ../customization.md#extending-the-theme
|
||||
[overriding partials]: ../customization.md#overriding-partials
|
||||
@@ -0,0 +1,68 @@
|
||||
# Setting up the header
|
||||
|
||||
Material for MkDocs' header can be customized to show an announcement bar that
|
||||
disappears upon scrolling, and provides some options for further configuration.
|
||||
It also includes the [search bar] and a place to display your project's
|
||||
[git repository], as explained in those dedicated guides.
|
||||
|
||||
[search bar]: setting-up-site-search.md
|
||||
[git repository]: adding-a-git-repository.md
|
||||
|
||||
## Configuration
|
||||
|
||||
### Automatic hiding
|
||||
|
||||
<!-- md:version 6.2.0 -->
|
||||
<!-- md:feature -->
|
||||
|
||||
When autohiding is enabled, the header is automatically hidden when the
|
||||
user scrolls past a certain threshold, leaving more space for content. Add the
|
||||
following lines to `mkdocs.yml`:
|
||||
|
||||
``` yaml
|
||||
theme:
|
||||
features:
|
||||
- header.autohide
|
||||
```
|
||||
|
||||
### Announcement bar
|
||||
|
||||
<!-- md:version 5.0.0 -->
|
||||
<!-- md:flag customization -->
|
||||
|
||||
Material for MkDocs includes an announcement bar, which is the perfect place to
|
||||
display project news or other important information to the user. When the user
|
||||
scrolls past the header, the bar will automatically disappear. In order to add
|
||||
an announcement bar, [extend the theme] and [override the `announce`
|
||||
block][overriding blocks], which is empty by default:
|
||||
|
||||
``` html
|
||||
{% extends "base.html" %}
|
||||
|
||||
{% block announce %}
|
||||
<!-- Add announcement here, including arbitrary HTML -->
|
||||
{% endblock %}
|
||||
```
|
||||
|
||||
[extend the theme]: ../customization.md#extending-the-theme
|
||||
[overriding blocks]: ../customization.md#overriding-blocks
|
||||
|
||||
#### Mark as read
|
||||
|
||||
<!-- md:version 8.4.0 -->
|
||||
<!-- md:feature -->
|
||||
<!-- md:flag experimental -->
|
||||
|
||||
In order to render temporary announcements that can be marked as read by the
|
||||
user, a button to dismiss the current announcement can be included. Add the
|
||||
following lines to `mkdocs.yml`:
|
||||
|
||||
``` yaml
|
||||
theme:
|
||||
features:
|
||||
- announce.dismiss
|
||||
```
|
||||
|
||||
When the user clicks the button, the current announcement is dismissed and not
|
||||
displayed again until the content of the announcement changes. This is handled
|
||||
automatically.
|
||||
@@ -0,0 +1,189 @@
|
||||
# Setting up versioning
|
||||
|
||||
Material for MkDocs makes it easy to deploy multiple versions of your project
|
||||
documentation by integrating with external utilities that add those capabilities
|
||||
to MkDocs, i.e. [mike]. When deploying a new version, older versions of your
|
||||
documentation remain untouched.
|
||||
|
||||
[mike]: https://github.com/jimporter/mike
|
||||
|
||||
## Configuration
|
||||
|
||||
### Versioning
|
||||
|
||||
<!-- md:version 7.0.0 -->
|
||||
<!-- md:utility [mike] -->
|
||||
<!-- md:demo example-versioning -->
|
||||
|
||||
[mike] makes it easy to deploy multiple versions of your project documentation.
|
||||
It integrates natively with Material for MkDocs and can be enabled via
|
||||
`mkdocs.yml`:
|
||||
|
||||
``` yaml
|
||||
extra:
|
||||
version:
|
||||
provider: mike
|
||||
```
|
||||
|
||||
This renders a version selector in the header:
|
||||
|
||||
<figure markdown>
|
||||
|
||||
[![Version selector preview]][Version selector preview]
|
||||
|
||||
<figcaption markdown>
|
||||
|
||||
Check out the versioning example to see it in action –
|
||||
[mkdocs-material.github.io/example-versioning][version example]
|
||||
|
||||
</figcaption>
|
||||
</figure>
|
||||
|
||||
!!! quote "[Why use mike?]"
|
||||
|
||||
mike is built around the idea that once you've generated your docs for a
|
||||
particular version, you should never need to touch that version again. This
|
||||
means you never have to worry about breaking changes in MkDocs, since your
|
||||
old docs (built with an old version of MkDocs) are already generated and
|
||||
sitting in your `gh-pages` branch.
|
||||
|
||||
While mike is flexible, it's optimized around putting your docs in a
|
||||
`<major>.<minor>` directory, with optional aliases (e.g. `latest` or `dev`)
|
||||
to particularly notable versions. This makes it easy to make permalinks to
|
||||
whatever version of the documentation you want to direct people to.
|
||||
|
||||
[Version selector preview]: ../assets/screenshots/versioning.png
|
||||
[version example]: https://mkdocs-material.github.io/example-versioning/
|
||||
[Why use mike?]: https://github.com/jimporter/mike#why-use-mike
|
||||
|
||||
### Stay on the same page when switching versions
|
||||
|
||||
When the user chooses a version in the version selector, they usually want to go
|
||||
to the page corresponding to the page they were previously viewing. Material for
|
||||
MkDocs implements this behavior by default, but there are a few caveats:
|
||||
|
||||
- the [`site_url`][mkdocs.site_url] must be set correctly in `mkdocs.yml`.
|
||||
See the ["Publishing a new version"](#publishing-a-new-version) section for
|
||||
an example.
|
||||
- the redirect happens via JavaScript and there is no way to know which page you
|
||||
will be redirected to ahead of time.
|
||||
|
||||
### Version warning
|
||||
|
||||
<!-- md:version 8.0.0 -->
|
||||
<!-- md:flag customization -->
|
||||
|
||||
If you're using versioning, you might want to display a warning when the user
|
||||
visits any other version than the latest version. Using [theme extension],
|
||||
you can [override the `outdated` block][overriding blocks]:
|
||||
|
||||
``` html
|
||||
{% extends "base.html" %}
|
||||
|
||||
{% block outdated %}
|
||||
You're not viewing the latest version.
|
||||
<a href="{{ '../' ~ base_url }}"> <!-- (1)! -->
|
||||
<strong>Click here to go to latest.</strong>
|
||||
</a>
|
||||
{% endblock %}
|
||||
```
|
||||
|
||||
1. Given this value for the `href` attribute, the link will always redirect to
|
||||
the root of your site, which will then redirect to the latest version. This
|
||||
ensures that older versions of your site do not depend on a specific alias,
|
||||
e.g. `latest`, to allow for changing the alias later on without breaking
|
||||
earlier versions.
|
||||
|
||||
This will render a version warning above the header:
|
||||
|
||||
[![Version warning preview]][Version warning preview]
|
||||
|
||||
The default version is identified by the `latest` alias. If you wish to set
|
||||
another alias as the latest version, e.g. `stable`, add the following lines
|
||||
to `mkdocs.yml`:
|
||||
|
||||
``` yaml
|
||||
extra:
|
||||
version:
|
||||
default: stable # (1)!
|
||||
```
|
||||
|
||||
1. You can also define multiple aliases as the default version, e.g. `stable`
|
||||
and `development`.
|
||||
|
||||
``` yaml
|
||||
extra:
|
||||
version:
|
||||
default:
|
||||
- stable
|
||||
- development
|
||||
```
|
||||
|
||||
Now every version that has the `stable` and `development` aliases will not
|
||||
display the version warning.
|
||||
|
||||
Make sure one alias matches the [default version], as this is where users are
|
||||
redirected to.
|
||||
|
||||
[theme extension]: ../customization.md#extending-the-theme
|
||||
[overriding blocks]: ../customization.md#overriding-blocks
|
||||
[Version warning preview]: ../assets/screenshots/version-warning.png
|
||||
[default version]: #setting-a-default-version
|
||||
|
||||
### Version alias
|
||||
|
||||
<!-- md:version 9.5.23 -->
|
||||
<!-- md:default `false` -->
|
||||
|
||||
If you're using aliases for versioning, and want to show the version alias
|
||||
besides the version number, you can enable this feature by setting the `alias`
|
||||
option to `true`:
|
||||
|
||||
``` yaml
|
||||
extra:
|
||||
version:
|
||||
alias: true
|
||||
```
|
||||
|
||||
## Usage
|
||||
|
||||
While this section outlines the basic workflow for publishing new versions,
|
||||
it's best to check out [mike's documentation][mike] to make yourself familiar
|
||||
with its mechanics.
|
||||
|
||||
### Publishing a new version
|
||||
|
||||
If you want to publish a new version of your project documentation, choose a
|
||||
version identifier and update the alias set as the default version with:
|
||||
|
||||
```
|
||||
mike deploy --push --update-aliases 0.1 latest
|
||||
```
|
||||
|
||||
Note that every version will be deployed as a subdirectory of your `site_url`,
|
||||
which you should set explicitly. For example, if your `mkdocs.yml` contains:
|
||||
|
||||
``` yaml
|
||||
site_url: 'https://docs.example.com/' # Trailing slash is recommended
|
||||
```
|
||||
|
||||
the documentation will be published to URLs such as:
|
||||
|
||||
- _docs.example.com/0.1/_
|
||||
- _docs.example.com/0.2/_
|
||||
- ...
|
||||
|
||||
### Setting a default version
|
||||
|
||||
When starting with [mike], a good idea is to set an alias as a default version,
|
||||
e.g. `latest`, and when publishing a new version, always update the alias to
|
||||
point to the latest version:
|
||||
|
||||
```
|
||||
mike set-default --push latest
|
||||
```
|
||||
|
||||
When publishing a new version, [mike] will create a redirect in the root of
|
||||
your project documentation to the version associated with the alias:
|
||||
|
||||
_docs.example.com_ :octicons-arrow-right-24: _docs.example.com/0.1_
|
||||
Reference in New Issue
Block a user