starred/mkdocs-material
1
0
Fork 0
mirror of https://github.com/squidfunk/mkdocs-material.git synced 2026-07-25 07:12:44 -04:00
Code Issues Packages Projects Releases Wiki Activity

Merge branch 'master' into master

Browse Source
This commit is contained in:
Olivier Jacques
2022-09-19 21:27:10 +02:00
committed by GitHub
parent 30d844cc1e 1410254c1a
commit bc74a2472e
4537 changed files with 12124 additions and 3907 deletions
Download Patch File Download Diff File Expand all files Collapse all files

50
docs/setup/adding-a-comment-system.md
View File

@@ -42,24 +42,14 @@ Before you can use [Giscus], you need to complete the following steps:
</script>
```
You can either integrate [Giscus] on every page by overriding the `main.html`
template, or create a new template (e.g. `blog.html`) to extend from `main.html`
which includes the comment system, so you can decide for each page whether you
want to allow comments or not.
The by default empty [`comments.html`][comments] partial is the best place to
add the code snippet generated by [Giscus]. Follow the guide on [theme extension]
and [override the `comments.html` partial][overriding partials] with:
In order to integrate [Giscus], follow the guide on [theme extension] and
[override the `content` block][overriding blocks], extending the default by
calling the `super()` function at the beginning of the block:
``` html hl_lines="8"
{% extends "base.html" %}
{% block content %}
{{ super() }}
<!-- Giscus -->
``` html hl_lines="3"
{% if page.meta.comments %}
<h2 id="__comments">{{ lang.t("meta.comments") }}</h2>
<!-- Replace with generated snippet -->
<!-- Insert generated code here -->
<!-- Synchronize Giscus theme with palette -->
<script>
@@ -71,7 +61,7 @@ calling the `super()` function at the beginning of the block:
var theme = palette.color.scheme === "slate" ? "dark" : "light"
giscus.setAttribute("data-theme", theme) // (1)!
}
/* Register event handlers after documented loaded */
document.addEventListener("DOMContentLoaded", function() {
var ref = document.querySelector("[data-md-component=palette]")
@@ -90,7 +80,7 @@ calling the `super()` function at the beginning of the block:
})
})
</script>
{% endblock %}
{% endif %}
```
1. This code block ensures that [Giscus] renders with a dark theme when the
@@ -98,12 +88,24 @@ calling the `super()` function at the beginning of the block:
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 extended `main.html`, you should
now see the [Giscus] comment system at the bottom of each page. If you created
a new, separate template, you can enable Giscus by [setting the page template]
via front matter.
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
---
# Document 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
[overriding blocks]: ../customization.md#overriding-blocks
[setting the page template]: ../reference/index.md#setting-the-page-template
[comments]: https://github.com/squidfunk/mkdocs-material/blob/master/src/partials/comments.html
[overriding partials]: ../customization.md#overriding-partials
[built-in meta plugin]: ../reference/index.md#built-in-meta-plugin

57
docs/setup/adding-a-git-repository.md
View File

@@ -13,7 +13,7 @@ static site, including stars and forks. Furthermore, the
### Repository
[:octicons-tag-24: 0.1.0][repo_url support] ·
[:octicons-tag-24: 0.1.0][Repository support] ·
:octicons-milestone-24: Default: _none_
In order to display a link to the repository of your project as part of your
@@ -37,14 +37,14 @@ GitHub repositories also include the tag of the latest release.[^1]
pre-release) for the latest tag you want to display next to the number of
stars and forks.
[repo_url support]: https://github.com/squidfunk/mkdocs-material/releases/tag/0.1.0
[Repository support]: https://github.com/squidfunk/mkdocs-material/releases/tag/0.1.0
[repo_url]: https://www.mkdocs.org/user-guide/configuration/#repo_url
[latest release]: https://docs.github.com/en/rest/reference/releases#get-the-latest-release
[create a release]: https://docs.github.com/en/repositories/releasing-projects-on-github/managing-releases-in-a-repository#creating-a-release
#### Repository name
[:octicons-tag-24: 0.1.0][repo_name support] ·
[:octicons-tag-24: 0.1.0][Repository name support] ·
:octicons-milestone-24: Default: _automatically set to_ `GitHub`, `GitLab` _or_
`Bitbucket`
@@ -56,14 +56,14 @@ _repository name_ automatically. If you wish to customize the name, set
repo_name: squidfunk/mkdocs-material
```
[repo_name support]: https://github.com/squidfunk/mkdocs-material/releases/tag/0.1.0
[Repository name support]: https://github.com/squidfunk/mkdocs-material/releases/tag/0.1.0
[repo_name]: https://www.mkdocs.org/user-guide/configuration/#repo_name
#### Repository icon
[:octicons-tag-24: 5.0.0][icon.repo support] ·
[:octicons-tag-24: 5.0.0][Repository icon support] ·
:octicons-milestone-24: Default:
[`fontawesome/brands/git-alt`][icon.repo default]
:fontawesome-brands-git-alt: – `fontawesome/brands/git-alt`
While the default repository icon is a generic git icon, it can be set to
any icon bundled with the theme by referencing a valid icon path in
@@ -97,13 +97,13 @@ Some popular choices:
- :fontawesome-brands-bitbucket: – `fontawesome/brands/bitbucket`
- :fontawesome-solid-trash: – `fontawesome/solid/trash`
[icon.repo support]: https://github.com/squidfunk/mkdocs-material/releases/tag/5.0.0
[icon.repo default]: https://github.com/squidfunk/mkdocs-material/blob/master/material/.icons/fontawesome/brands/git-alt.svg
[Repository icon support]: https://github.com/squidfunk/mkdocs-material/releases/tag/5.0.0
[Repository icon default]: https://github.com/squidfunk/mkdocs-material/blob/master/material/.icons/fontawesome/brands/git-alt.svg
[icon search]: ../reference/icons-emojis.md#search
#### Edit button
[:octicons-tag-24: 0.1.0][edit_uri support] ·
[:octicons-tag-24: 0.1.0][Edit button support] ·
:octicons-milestone-24: Default: _automatically set_
If the repository URL points to a [GitHub], [GitLab] or [Bitbucket] repository,
@@ -122,7 +122,26 @@ changed by setting [`edit_uri`][edit_uri] in `mkdocs.yml`:
edit_uri: ""
```
[edit_uri support]: https://github.com/squidfunk/mkdocs-material/releases/tag/0.1.0
The icon of the edit button can be changed with the following lines:
``` yaml
theme:
icon:
edit: material/pencil # (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 file edit" />
<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>
[Edit button support]: https://github.com/squidfunk/mkdocs-material/releases/tag/0.1.0
[edit_uri]: https://www.mkdocs.org/user-guide/configuration/#edit_uri
[GitHub]: https://github.com/
[GitLab]: https://about.gitlab.com/
@@ -140,7 +159,7 @@ links to all [contributors] or [authors] involved.
#### Document dates
[:octicons-tag-24: 4.6.0][git-revision-date-localized support] ·
[:octicons-tag-24: 4.6.0][Document dates support] ·
[:octicons-cpu-24: Plugin][git-revision-date-localized]
The [git-revision-date-localized] plugin adds support for adding the date of
@@ -161,7 +180,7 @@ plugins:
The following configuration options are supported:
`type`{ #type }
[`type`](#+git-revision-date-localized.type){ #+git-revision-date-localized.type }
: :octicons-milestone-24: Default: `date` – The format of the date to be
displayed. Valid values are `date`, `datetime`, `iso_date`, `iso_datetime`
@@ -173,10 +192,9 @@ The following configuration options are supported:
type: date
```
`enable_creation_date`{ #enable-creation-date }
[`enable_creation_date`](#+git-revision-date-localized.enable_creation_date){ #+git-revision-date-localized.enable_creation_date }
: [:octicons-tag-24: 7.1.4][enable_creation_date support] ·
:octicons-milestone-24: Default: `false` – Enables the display of the
: :octicons-milestone-24: Default: `false` – Enables the display of the
creation date of the file associated with the page next to the last updated
date at the bottom of the page:
@@ -186,7 +204,7 @@ The following configuration options are supported:
enable_creation_date: true
```
`fallback_to_build_date`{ #fallback-to-build-date }
[`fallback_to_build_date`](#+git-revision-date-localized.fallback_to_build_date){ #+git-revision-date-localized.fallback_to_build_date }
: :octicons-milestone-24: Default: `false` – Enables falling back to
the time when `mkdocs build` was executed. Can be used as a fallback when
@@ -202,9 +220,8 @@ The other configuration options of this extension are not officially supported
by Material for MkDocs, which is why they may yield unexpected results. Use
them at your own risk.
[git-revision-date-localized support]: https://github.com/squidfunk/mkdocs-material/releases/tag/4.6.0
[Document dates support]: https://github.com/squidfunk/mkdocs-material/releases/tag/4.6.0
[git-revision-date-localized]: https://github.com/timvink/mkdocs-git-revision-date-localized-plugin
[enable_creation_date support]: https://github.com/squidfunk/mkdocs-material/releases/tag/7.1.4
#### Document contributors
@@ -238,9 +255,9 @@ plugins:
The following configuration options are supported:
`repository`{ #committers-repository }
[`repository`](#+git-committers.repository){ #+git-committers.repository }
: :octicons-milestone-24: Default: _none_ · :octicons-alert-24: Required –
: :octicons-milestone-24: Default: _none_ · :octicons-alert-24: __Required__ –
This property must be set to the slug of the repository that contains your
documentation. The slug must follow the pattern `<username>/<repository>`:

2
docs/setup/building-for-offline-usage.md
View File

@@ -49,7 +49,7 @@ from the local file system.
The following configuration options are available:
`enabled`{ #enabled }
[`enabled`](#+offline.enabled){ #+offline.enabled }
: :octicons-milestone-24: Default: `true` – This option specifies whether
the plugin is enabled when building your project. If you want to switch

36
docs/setup/changing-the-colors.md
View File

@@ -18,7 +18,7 @@ fit your brand's identity by using [CSS variables][custom colors].
#### Color scheme
[:octicons-tag-24: 5.2.0][palette.scheme support] ·
[:octicons-tag-24: 5.2.0][Color scheme support] ·
:octicons-milestone-24: Default: `default`
Material for MkDocs supports two color schemes: a __light mode__, which is just
@@ -50,11 +50,11 @@ Click on a tile to change the color scheme:
})
</script>
[palette.scheme support]: https://github.com/squidfunk/mkdocs-material/releases/tag/5.2.0
[Color scheme support]: https://github.com/squidfunk/mkdocs-material/releases/tag/5.2.0
#### Primary color
[:octicons-tag-24: 0.2.0][palette.primary support] ·
[:octicons-tag-24: 0.2.0][Primary color support] ·
:octicons-milestone-24: Default: `indigo`
The primary color is used for the header, the sidebar, text links and several
@@ -105,11 +105,11 @@ Click on a tile to change the primary color:
})
</script>
[palette.primary support]: https://github.com/squidfunk/mkdocs-material/releases/tag/0.2.0
[Primary color support]: https://github.com/squidfunk/mkdocs-material/releases/tag/0.2.0
#### Accent color
[:octicons-tag-24: 0.2.0][palette.accent support] ·
[:octicons-tag-24: 0.2.0][Accent color support] ·
:octicons-milestone-24: Default: `indigo`
The accent color is used to denote elements that can be interacted with, e.g.
@@ -162,11 +162,11 @@ Click on a tile to change the accent color:
})
</script>
[palette.accent support]: https://github.com/squidfunk/mkdocs-material/releases/tag/0.2.0
[Accent color support]: https://github.com/squidfunk/mkdocs-material/releases/tag/0.2.0
### Color palette toggle
[:octicons-tag-24: 7.1.0][palette.toggle support] ·
[:octicons-tag-24: 7.1.0][Color palette toggle support] ·
:octicons-milestone-24: Default: _none_
Offering a light _and_ dark color palette makes your documentation pleasant to
@@ -209,9 +209,9 @@ and [`accent`][palette.accent] per color palette.
The following properties must be set for each toggle:
`icon`{ #toggle-icon }
[`icon`](#+palette.toggle.icon){ #+palette.toggle.icon }
: :octicons-milestone-24: Default: _none_ · :octicons-alert-24: Required –
: :octicons-milestone-24: Default: _none_ · :octicons-alert-24: __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:
@@ -221,13 +221,13 @@ The following properties must be set for each toggle:
* :material-eye: + :material-eye-outline: – `material/eye` + `material/eye-outline`
* :material-lightbulb: + :material-lightbulb-outline: – `material/lightbulb` + `material/lightbulb-outline`
`name`{ #toggle-name }
[`name`](#+palette.toggle.name){ #+palette.toggle.name }
: :octicons-milestone-24: Default: _none_ · :octicons-alert-24: Required –
: :octicons-milestone-24: Default: _none_ · :octicons-alert-24: __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.toggle support]: https://github.com/squidfunk/mkdocs-material/releases/tag/7.1.0
[Color palette toggle support]: https://github.com/squidfunk/mkdocs-material/releases/tag/7.1.0
[palette.scheme]: #color-scheme
[palette.primary]: #primary-color
[palette.accent]: #accent-color
@@ -236,7 +236,7 @@ The following properties must be set for each toggle:
### System preference
[:octicons-tag-24: 7.1.0][palette.media support] ·
[:octicons-tag-24: 7.1.0][System preference support] ·
:octicons-milestone-24: Default: _none_
Each color palette can be linked to the user's system preference for light and
@@ -266,7 +266,7 @@ 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.
[palette.media support]: https://github.com/squidfunk/mkdocs-material/releases/tag/7.1.0
[System preference support]: https://github.com/squidfunk/mkdocs-material/releases/tag/7.1.0
#### Automatic light / dark mode
@@ -327,7 +327,7 @@ 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"
=== ":octicons-file-code-16: `docs/stylesheets/extra.css`"
``` css
:root > * {
@@ -337,7 +337,7 @@ add:
}
```
=== ":octicons-file-code-16: mkdocs.yml"
=== ":octicons-file-code-16: `mkdocs.yml`"
``` yaml
extra_css:
@@ -358,7 +358,7 @@ 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"
=== ":octicons-file-code-16: `docs/stylesheets/extra.css`"
``` css
[data-md-color-scheme="youtube"] {
@@ -368,7 +368,7 @@ in the [color schemes][palette.scheme] section:
}
```
=== ":octicons-file-code-16: mkdocs.yml"
=== ":octicons-file-code-16: `mkdocs.yml`"
``` yaml
theme:

14
docs/setup/changing-the-fonts.md
View File

@@ -15,7 +15,7 @@ or another destination should be used.
### Regular font
[:octicons-tag-24: 0.1.2][font support] ·
[:octicons-tag-24: 0.1.2][Font support] ·
:octicons-milestone-24: Default: [`Roboto`][Roboto]
The regular font is used for all body copy, headlines, and essentially
@@ -31,11 +31,11 @@ theme:
The typeface will be loaded in 300, 400, _400i_ and __700__.
[Roboto]: https://fonts.google.com/specimen/Roboto
[font support]: https://github.com/squidfunk/mkdocs-material/releases/tag/0.1.2
[Font support]: https://github.com/squidfunk/mkdocs-material/releases/tag/0.1.2
### Monospaced font
[:octicons-tag-24: 0.1.2][font support] ·
[:octicons-tag-24: 0.1.2][Font support] ·
:octicons-milestone-24: Default: [`Roboto Mono`][Roboto Mono]
The _monospaced font_ is used for code blocks and can be configured separately.
@@ -54,7 +54,7 @@ The typeface will be loaded in 400.
### Autoloading
[:octicons-tag-24: 1.0.0][font=false support] ·
[:octicons-tag-24: 1.0.0][Autoloading support] ·
:octicons-milestone-24: Default: _none_
If you want to prevent typefaces from being loaded from [Google Fonts], e.g.
@@ -73,7 +73,7 @@ theme:
by automatically downloading and self-hosting the web font files.
[data privacy]: https://developers.google.com/fonts/faq#what_does_using_the_google_fonts_api_mean_for_the_privacy_of_my_users
[font=false support]: https://github.com/squidfunk/mkdocs-material/releases/tag/1.0.0
[Autoloading support]: https://github.com/squidfunk/mkdocs-material/releases/tag/1.0.0
[built-in privacy plugin]: ensuring-data-privacy.md#built-in-privacy-plugin
## Customization
@@ -84,7 +84,7 @@ 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"
=== ":octicons-file-code-16: `docs/stylesheets/extra.css`"
``` css
@font-face {
@@ -93,7 +93,7 @@ corresponding `@font-face` definition:
}
```
=== ":octicons-file-code-16: mkdocs.yml"
=== ":octicons-file-code-16: `mkdocs.yml`"
``` yaml
extra_css:

28
docs/setup/changing-the-language.md
View File

@@ -13,7 +13,7 @@ available.
### Site language
[:octicons-tag-24: 1.12.0][language support] ·
[:octicons-tag-24: 1.12.0][Site language support] ·
:octicons-milestone-24: Default: `en`
You can set the site language in `mkdocs.yml` with:
@@ -100,7 +100,7 @@ The following languages are supported:
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].
[language support]: https://github.com/squidfunk/mkdocs-material/releases/tag/1.12.0
[Site language support]: https://github.com/squidfunk/mkdocs-material/releases/tag/1.12.0
[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
@@ -108,7 +108,7 @@ the default slug function works. Consider using a [Unicode-aware slug function].
### Site language selector
[:octicons-tag-24: 7.0.0][alternate support] ·
[:octicons-tag-24: 7.0.0][Site language selector support] ·
:octicons-milestone-24: Default: _none_ ·
:octicons-beaker-24: Experimental
@@ -133,35 +133,35 @@ extra:
The following properties are available for each alternate language:
`name`{ #language-name }
[`name`](#+alternate.name){ #+alternate.name }
: :octicons-milestone-24: Default: _none_ · :octicons-alert-24: Required –
: :octicons-milestone-24: Default: _none_ · :octicons-alert-24: __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.
`link`{ #language-link }
[`link`](#+alternate.link){ #+alternate.link }
: :octicons-milestone-24: Default: _none_ · :octicons-alert-24: Required –
: :octicons-milestone-24: Default: _none_ · :octicons-alert-24: __Required__ –
This property must be set to an absolute link, which might also point to
another domain or subdomain not necessarily generated with MkDocs.
`lang`{ #language-lang }
[`lang`](#+alternate.lang){ #+alternate.lang }
: :octicons-milestone-24: Default: _none_ · :octicons-alert-24: Required –
: :octicons-milestone-24: Default: _none_ · :octicons-alert-24: __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]
[alternate support]: https://github.com/squidfunk/mkdocs-material/releases/tag/7.0.0
[Site language selector support]: https://github.com/squidfunk/mkdocs-material/releases/tag/7.0.0
[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
### Directionality
[:octicons-tag-24: 2.5.0][direction support] ·
[:octicons-tag-24: 2.5.0][Directionality support] ·
:octicons-milestone-24: Default: _automatically set_
While many languages are read `ltr` (left-to-right), Material for MkDocs also
@@ -192,7 +192,7 @@ Click on a tile to change the directionality:
})
</script>
[direction support]: https://github.com/squidfunk/mkdocs-material/releases/tag/2.5.0
[Directionality support]: https://github.com/squidfunk/mkdocs-material/releases/tag/2.5.0
## Customization
@@ -203,7 +203,7 @@ 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"
=== ":octicons-file-code-16: `overrides/partials/languages/custom.html`"
``` html
<!-- Import translations for language and fallback -->
@@ -228,7 +228,7 @@ adjust the ones you want to override:
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"
=== ":octicons-file-code-16: `mkdocs.yml`"
``` yaml
theme:

15
docs/setup/changing-the-logo-and-icons.md
View File

@@ -15,8 +15,8 @@ when writing your documentation in Markdown. Not enough? You can also add
### Logo
[:octicons-tag-24: 0.1.0][logo support] ·
:octicons-milestone-24: Default: [`material/library`][logo default]
[:octicons-tag-24: 0.1.0][Logo support] ·
:octicons-milestone-24: Default: :material-library: – `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.
@@ -48,8 +48,7 @@ Add the following lines to `mkdocs.yml`:
</div>
</div>
[logo support]: https://github.com/squidfunk/mkdocs-material/releases/tag/0.1.0
[logo default]: https://github.com/squidfunk/mkdocs-material/blob/master/material/.icons/material/library.svg
[Logo support]: https://github.com/squidfunk/mkdocs-material/releases/tag/0.1.0
[icon search]: ../reference/icons-emojis.md#search
Normally, the logo in the header and sidebar links to the homepage of the
@@ -63,8 +62,8 @@ extra:
### Favicon
[:octicons-tag-24: 0.1.0][favicon support] ·
:octicons-milestone-24: Default: [`assets/images/favicon.png`][favicon default]
[:octicons-tag-24: 0.1.0][Favicon support] ·
:octicons-milestone-24: 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`:
@@ -74,8 +73,8 @@ theme:
favicon: images/favicon.png
```
[favicon support]: https://github.com/squidfunk/mkdocs-material/releases/tag/0.1.0
[favicon default]: https://github.com/squidfunk/mkdocs-material/blob/master/material/assets/images/favicon.png
[Favicon support]: https://github.com/squidfunk/mkdocs-material/releases/tag/0.1.0
[Favicon default]: https://github.com/squidfunk/mkdocs-material/blob/master/material/assets/images/favicon.png
## Customization

59
docs/setup/ensuring-data-privacy.md
View File

@@ -6,23 +6,23 @@ template: overrides/main.html
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 [tracking]. Additionally, external assets can be
users before setting up [analytics]. Additionally, external assets can be
automatically downloaded for [self-hosting].
[cookie consent]: #native-cookie-consent
[tracking]: setting-up-site-analytics.md
[cookie consent]: #cookie-consent
[analytics]: setting-up-site-analytics.md
[self-hosting]: #built-in-privacy-plugin
## Configuration
### Cookie consent { #native-cookie-consent }
### Cookie consent
[:octicons-tag-24: 8.4.0][cookie consent support] ·
[:octicons-tag-24: 8.4.0][Cookie consent support] ·
:octicons-milestone-24: Default: _none_ ·
:octicons-beaker-24: Experimental
Material for MkDocs ships a native and extensible cookie consent form which
asks the user for consent prior to sending any data via analytics. Add the
asks the user for consent prior to sending requests to third parties. Add the
following to `mkdocs.yml`:
``` yaml
@@ -41,25 +41,30 @@ extra:
The following properties are available:
`title`{ #consent-title }
[`title`](#+consent.title){ #+consent.title }
: :octicons-milestone-24: Default: _none_ · :octicons-alert-24: Required –
: :octicons-milestone-24: Default: _none_ · :octicons-alert-24: __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.
`description`{ #consent-description }
[`description`](#+consent.description){ #+consent.description }
: :octicons-milestone-24: Default: _none_ · :octicons-alert-24: Required –
: :octicons-milestone-24: Default: _none_ · :octicons-alert-24: __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).
`cookies`{ #consent-cookies }
[`cookies`](#+consent.cookies){ #+consent.cookies }
: :octicons-milestone-24: Default: _none_ – This property allows to add custom
cookies or change the initial `checked` state and name of the `analytics`
cookie. 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:
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"
@@ -95,11 +100,11 @@ The following properties are available:
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]
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.
`actions`{ #consent-actions }
[`actions`](#+consent.actions){ #+consent.actions }
: :octicons-milestone-24: Default: `[accept, manage]` – This property defines
which buttons are shown and in which order, e.g. to allow the user to accept
@@ -121,11 +126,11 @@ The following properties are available:
When a user first visits your site, a cookie consent form is rendered:
[![cookie consent enabled]][cookie consent enabled]
[![Cookie consent enabled]][Cookie consent enabled]
[Custom cookies]: #custom-cookies
[cookie consent support]: https://github.com/squidfunk/mkdocs-material/releases/tag/8.4.0
[cookie consent enabled]: ../assets/screenshots/consent.png
[Cookie consent support]: https://github.com/squidfunk/mkdocs-material/releases/tag/8.4.0
[Cookie consent enabled]: ../assets/screenshots/consent.png
#### Change cookie settings
@@ -168,7 +173,7 @@ plugins:
The following configuration options are available:
`enabled`{ #enabled }
[`enabled`](#+privacy.enabled){ #+privacy.enabled }
: :octicons-milestone-24: Default: `true` – This option specifies whether
the plugin is enabled when building your project. If you want to switch
@@ -180,7 +185,7 @@ The following configuration options are available:
enabled: !ENV [PRIVACY, false]
```
`externals`{ #externals }
[`externals`](#+privacy.externals){ #+privacy.externals }
: :octicons-milestone-24: Default: `bundle` – This option specifies what the
plugin should do when encountering external assets. There are two options:
@@ -204,7 +209,7 @@ The following configuration options are available:
[customization]: ../customization.md
[strict mode]: https://www.mkdocs.org/user-guide/configuration/#strict
`externals_dir`{ #externals-dir }
[`externals_dir`](#+privacy.externals_dir){ #+privacy.externals_dir }
: :octicons-milestone-24: Default: `assets/externals` – This option
specifies where the downloaded [external assets] will be stored. It's
@@ -216,7 +221,7 @@ The following configuration options are available:
externals_dir: assets/externals
```
`externals_exclude`{ #externals-exclude }
[`externals_exclude`](#+privacy.externals_exclude){ #+privacy.externals_exclude }
: :octicons-milestone-24: Default: _none_ – This option allows to exclude
certain external assets from processing by the privacy plugin, so they will
@@ -440,7 +445,7 @@ If you've customized the [cookie consent] and added a `custom` cookie, the user
will be prompted to accept your custom cookie. Use [additional JavaScript] to
check whether the user accepted it:
=== ":octicons-file-code-16: docs/javascripts/consent.js"
=== ":octicons-file-code-16: `docs/javascripts/consent.js`"
``` js
var consent = __md_get("__consent")
@@ -449,7 +454,7 @@ check whether the user accepted it:
}
```
=== ":octicons-file-code-16: mkdocs.yml"
=== ":octicons-file-code-16: `mkdocs.yml`"
``` yaml
extra_javascript:

38
docs/setup/extensions/python-markdown-extensions.md
View File

@@ -37,7 +37,7 @@ 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"
=== ":octicons-file-code-16: `docs/javascripts/mathjax.js`"
``` js
window.MathJax = {
@@ -58,7 +58,7 @@ of [additional JavaScript]:
})
```
=== ":octicons-file-code-16: mkdocs.yml"
=== ":octicons-file-code-16: `mkdocs.yml`"
``` yaml
extra_javascript:
@@ -154,7 +154,7 @@ markdown_extensions:
The following configuration options are supported:
`mode`{ #critic-mode }
[`mode`](#+pymdownx.critic.mode){ #+pymdownx.critic.mode }
: :octicons-milestone-24: Default: `view` – This option defines how the markup
should be parsed, i.e. whether to just `view` all suggested changes, or
@@ -237,7 +237,7 @@ markdown_extensions:
The following configuration options are supported:
`emoji_index`{ #emoji-index }
[`emoji_index`](#+pymdownx.emoji.emoji_index){ #+pymdownx.emoji.emoji_index }
: :octicons-milestone-24: Default: `emojione` – This option defines which set
of emojis is used for rendering. Note that the use of `emojione` is not
@@ -249,7 +249,7 @@ The following configuration options are supported:
emoji_index: !!python/name:materialx.emoji.twemoji
```
`emoji_generator`{ #emoji-generator }
[`emoji_generator`](#+pymdownx.emoji.emoji_generator){ #+pymdownx.emoji.emoji_generator }
: :octicons-milestone-24: Default: `to_png` – This option defines how the
resolved emoji or icon shortcode is render. Note that icons can only be
@@ -261,7 +261,7 @@ The following configuration options are supported:
emoji_generator: !!python/name:materialx.emoji.to_svg
```
`options.custom_icons`{ #custom-icons }
[`options.custom_icons`](#+pymdownx.emoji.options.custom_icons){ #+pymdownx.emoji.options.custom_icons }
: :octicons-milestone-24: Default: _none_ – This option allows to list folders
with additional icon sets to be used in Markdown or `mkdocs.yml`, which is
@@ -319,7 +319,7 @@ markdown_extensions:
The following configuration options are supported:
`use_pygments`{ #highlight-use-pygments }
[`use_pygments`](#+pymdownx.highlight.use_pygments){ #+pymdownx.highlight.use_pygments }
: :octicons-milestone-24: Default: `true` – This option allows to control
whether highlighting should be carried out during build time using
@@ -346,7 +346,7 @@ The following configuration options are supported:
integrated with some [additional JavaScript] and an [additional style
sheet] in `mkdocs.yml`:
=== ":octicons-file-code-16: docs/javascripts/highlight.js"
=== ":octicons-file-code-16: `docs/javascripts/highlight.js`"
``` js
document$.subscribe(() => {
@@ -354,7 +354,7 @@ The following configuration options are supported:
})
```
=== ":octicons-file-code-16: mkdocs.yml"
=== ":octicons-file-code-16: `mkdocs.yml`"
``` yaml
extra_javascript:
@@ -371,7 +371,7 @@ The following configuration options are supported:
syntax highlighting using [Pygments], so they don't apply if `use_pygments`
is set to `false`.
`auto_title`{ #highlight-auto-title }
[`auto_title`](#+pymdownx.highlight.auto_title){ #+pymdownx.highlight.auto_title }
: :octicons-milestone-24: Default: `false` – This option will automatically
add a [title] to all code blocks that shows the name of the language being
@@ -383,7 +383,7 @@ The following configuration options are supported:
auto_title: true
```
`linenums`{ #highlight-linenums }
[`linenums`](#+pymdownx.highlight.linenums){ #+pymdownx.highlight.linenums }
: :octicons-milestone-24: Default: `false` – This option will add line numbers
to _all_ code blocks. If you wish to add line numbers to _some_, but not all
@@ -397,7 +397,7 @@ The following configuration options are supported:
linenums: true
```
`linenums_style`{ #highlight-linenums-style }
[`linenums_style`](#+pymdownx.highlight.linenums_style){ #+pymdownx.highlight.linenums_style }
: :octicons-milestone-24: Default: `table` – The [Highlight] extension
provides three ways to add line numbers, two of which are supported by
@@ -415,7 +415,7 @@ The following configuration options are supported:
copying a code block to the clipboard. Thus, the usage of either `table`
or `pymdownx-inline` is recommended.
`anchor_linenums`{ #highlight-anchor-linenums }
[`anchor_linenums`](#+pymdownx.highlight.anchor_linenums){ #+pymdownx.highlight.anchor_linenums }
: [:octicons-tag-24: 8.1.0][anchor_linenums support] · :octicons-milestone-24:
Default: `false` – If a code blocks contains line numbers, enabling this
@@ -579,7 +579,7 @@ markdown_extensions:
The following configuration options are supported:
`custom_fences`{ #superfences-custom-fences }
[`custom_fences`](#+pymdownx.superfences.custom_fences){ #+pymdownx.superfences.custom_fences }
: :octicons-milestone-24: Default: _none_ – This option allows to define a
handler for custom fences, e.g. to preserve the definitions of [Mermaid.js]
@@ -643,11 +643,11 @@ markdown_extensions:
The following configuration options are supported:
`alternate_style`{ #tabbed-alternate-style }
[`alternate_style`](#+pymdownx.tabbed.alternate_style){ #+pymdownx.tabbed:alternate_style }
: [:octicons-tag-24: 7.3.1][Tabbed alternate support] ·
:octicons-milestone-24: Default: `false` · :octicons-alert-24: Required –
This option enables the content tabs [alternate style], which has
:octicons-milestone-24: Default: `false` · :octicons-alert-24: __Required__
– This option enables the content tabs [alternate style], which has
[better behavior on mobile viewports], and is the only supported style:
``` yaml
@@ -692,7 +692,7 @@ markdown_extensions:
The following configuration options are supported:
`custom_checkbox`{ #tasklist-custom-checkbox }
[`custom_checkbox`](#+pymdownx.tasklist.custom_checkbox){ #+pymdownx.tasklist:custom_checkbox }
: :octicons-milestone-24: Default: `false` · This option toggles the rendering
style of checkboxes, replacing native checkbox styles with beautiful icons,
@@ -704,7 +704,7 @@ The following configuration options are supported:
custom_checkbox: true
```
`clickable_checkbox`{ #tasklist-clickable-checkbox }
[`clickable_checkbox`](#+pymdownx.tasklist.clickable_checkbox){ #+pymdownx.tasklist:clickable_checkbox }
: :octicons-milestone-24: Default: `false` · This option toggles whether
checkboxes are clickable. As the state is not persisted, the use of this

10
docs/setup/extensions/python-markdown.md
View File

@@ -196,7 +196,7 @@ markdown_extensions:
The following configuration options are supported:
`title`{ #toc-title }
[`title`](#+toc.title){ #+toc.title }
: [:octicons-tag-24: 7.3.5][title support] ·
:octicons-milestone-24: Default: _automatically set_ – This option sets the
@@ -210,7 +210,7 @@ The following configuration options are supported:
title: On this page
```
`permalink`{ #toc-permalink }
[`permalink`](#+toc.permalink){ #+toc.permalink }
: :octicons-milestone-24: Default: `false` – This option adds an anchor link
containing the paragraph symbol `` or another custom symbol at the end of
@@ -233,7 +233,7 @@ The following configuration options are supported:
permalink: ⚓︎
```
`permalink_title`{ #toc-permalink-title }
[`permalink_title`](#+toc.permalink_title){ #+toc.permalink_title }
: :octicons-milestone-24: Default: `Permanent link` – This option sets the
title of the anchor link which is shown on hover and read by screen readers.
@@ -246,7 +246,7 @@ The following configuration options are supported:
permalink_title: Anchor link to this section for reference
```
`slugify`{ #toc-slugify }
[`slugify`](#+toc.slugify){ #+toc.slugify }
: :octicons-milestone-24: Default: `headerid.slugify` – This option allows for
customization of the slug function. For some languages, the default may not
@@ -269,7 +269,7 @@ The following configuration options are supported:
slugify: !!python/name:pymdownx.slugs.uslugify_cased
```
`toc_depth`{ #toc-depth }
[`toc_depth`](#+toc.toc_depth){ #+toc.toc_depth }
: :octicons-milestone-24: Default: `6` – Define the range of levels to be
included in the table of contents. This may be useful for project

1219
docs/setup/setting-up-a-blog.md Normal file
View File

File diff suppressed because it is too large Load Diff

154
docs/setup/setting-up-navigation.md
View File

@@ -6,19 +6,18 @@ template: overrides/main.html
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][navigation.tabs] and
[sections][navigation.sections], and its flag-ship feature: [instant loading]
[navigation.instant].
the behavior of navigational elements, including [tabs] and [sections], and one
of its flag-ship feature: [instant loading].
[navigation.tabs]: #navigation-tabs
[navigation.sections]: #navigation-sections
[navigation.instant]: #instant-loading
[tabs]: #navigation-tabs
[sections]: #navigation-sections
[instant loading]: #instant-loading
## Configuration
### Instant loading
[:octicons-tag-24: 5.0.0][navigation.instant support] ·
[:octicons-tag-24: 5.0.0][Instant loading support] ·
:octicons-unlock-24: Feature flag
When instant loading is enabled, clicks on all internal links will be
@@ -36,7 +35,7 @@ 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.
[navigation.instant support]: https://github.com/squidfunk/mkdocs-material/releases/tag/5.2.0
[Instant loading support]: https://github.com/squidfunk/mkdocs-material/releases/tag/5.2.0
[XHR]: https://developer.mozilla.org/en-US/docs/Web/API/XMLHttpRequest
### Anchor tracking
@@ -59,7 +58,7 @@ theme:
### Navigation tabs
[:octicons-tag-24: 1.1.0][navigation.tabs support] ·
[:octicons-tag-24: 1.1.0][Navigation tabs support] ·
:octicons-unlock-24: Feature flag
When tabs are enabled, top-level sections are rendered in a menu layer below
@@ -81,21 +80,21 @@ theme:
- navigation.tabs
```
=== ":octicons-check-circle-fill-16: Enabled"
=== "With tabs"
[![navigation.tabs enabled]][navigation.tabs enabled]
[![Navigation tabs enabled]][Navigation tabs enabled]
=== ":octicons-skip-16: Disabled"
=== "Without"
[![navigation.tabs disabled]][navigation.tabs disabled]
[![Navigation tabs disabled]][Navigation tabs disabled]
[navigation.tabs support]: https://github.com/squidfunk/mkdocs-material/releases/tag/1.1.0
[navigation.tabs enabled]: ../assets/screenshots/navigation-tabs.png
[navigation.tabs disabled]: ../assets/screenshots/navigation.png
[Navigation tabs support]: https://github.com/squidfunk/mkdocs-material/releases/tag/1.1.0
[Navigation tabs enabled]: ../assets/screenshots/navigation-tabs.png
[Navigation tabs disabled]: ../assets/screenshots/navigation.png
#### Sticky navigation tabs
[:octicons-tag-24: 7.3.0][navigation.tabs.sticky support] ·
[:octicons-tag-24: 7.3.0][Sticky navigation tabs support] ·
:octicons-unlock-24: Feature flag
When sticky tabs are enabled, navigation tabs will lock below the header and
@@ -109,21 +108,21 @@ theme:
- navigation.tabs.sticky
```
=== ":octicons-check-circle-fill-16: Enabled"
=== "With sticky tabs"
[![navigation.tabs.sticky enabled]][navigation.tabs.sticky enabled]
[![Sticky navigation tabs enabled]][Sticky navigation tabs enabled]
=== ":octicons-skip-16: Disabled"
=== "Without"
[![navigation.tabs.sticky disabled]][navigation.tabs.sticky disabled]
[![Sticky navigation tabs disabled]][Sticky navigation tabs disabled]
[navigation.tabs.sticky support]: https://github.com/squidfunk/mkdocs-material/releases/tag/7.3.0
[navigation.tabs.sticky enabled]: ../assets/screenshots/navigation-tabs-sticky.png
[navigation.tabs.sticky disabled]: ../assets/screenshots/navigation-tabs-collapsed.png
[Sticky navigation tabs support]: https://github.com/squidfunk/mkdocs-material/releases/tag/7.3.0
[Sticky navigation tabs enabled]: ../assets/screenshots/navigation-tabs-sticky.png
[Sticky navigation tabs disabled]: ../assets/screenshots/navigation-tabs-collapsed.png
### Navigation sections
[:octicons-tag-24: 6.2.0][navigation.sections support] ·
[:octicons-tag-24: 6.2.0][Navigation sections support] ·
:octicons-unlock-24: Feature flag
When sections are enabled, top-level sections are rendered as groups in the
@@ -136,26 +135,25 @@ theme:
- navigation.sections
```
=== ":octicons-check-circle-fill-16: Enabled"
=== "With sections"
[![navigation.sections enabled]][navigation.sections enabled]
[![Navigation sections enabled]][Navigation sections enabled]
=== ":octicons-skip-16: Disabled"
=== "Without"
[![navigation.sections disabled]][navigation.sections disabled]
[![Navigation sections disabled]][Navigation sections disabled]
[navigation.sections support]: https://github.com/squidfunk/mkdocs-material/releases/tag/6.2.0
[navigation.sections enabled]: ../assets/screenshots/navigation-sections.png
[navigation.sections disabled]: ../assets/screenshots/navigation.png
[Navigation sections support]: https://github.com/squidfunk/mkdocs-material/releases/tag/6.2.0
[Navigation sections enabled]: ../assets/screenshots/navigation-sections.png
[Navigation sections disabled]: ../assets/screenshots/navigation.png
Both feature flags, [`navigation.tabs`][navigation.tabs] and
[`navigation.sections`][navigation.sections], can be combined with each other.
If both feature flags are enabled, sections are rendered for level 2 navigation
items.
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
[:octicons-tag-24: 6.2.0][navigation.expand support] ·
[:octicons-tag-24: 6.2.0][Navigation expansion support] ·
:octicons-unlock-24: Feature flag
When expansion is enabled, the left sidebar will expand all collapsible
@@ -168,17 +166,17 @@ theme:
- navigation.expand
```
=== ":octicons-check-circle-fill-16: Enabled"
=== "With expansion"
[![navigation.expand enabled]][navigation.expand enabled]
[![Navigation expansion enabled]][Navigation expansion enabled]
=== ":octicons-skip-16: Disabled"
=== "Without"
[![navigation.expand disabled]][navigation.expand disabled]
[![Navigation expansion disabled]][Navigation expansion disabled]
[navigation.expand support]: https://github.com/squidfunk/mkdocs-material/releases/tag/6.2.0
[navigation.expand enabled]: ../assets/screenshots/navigation-expand.png
[navigation.expand disabled]: ../assets/screenshots/navigation.png
[Navigation expansion support]: https://github.com/squidfunk/mkdocs-material/releases/tag/6.2.0
[Navigation expansion enabled]: ../assets/screenshots/navigation-expand.png
[Navigation expansion disabled]: ../assets/screenshots/navigation.png
### Navigation pruning
@@ -205,11 +203,12 @@ This feature flag is especially useful for documentation sites with 100+ or even
Navigation pruning will replace all expandable sections with links to the first
page in that section (or the section index page).
[Insiders]: ../insiders/index.md
[navigation.expand]: #navigation-expansion
### Section index pages
[:octicons-tag-24: 7.3.0][navigation.indexes support] ·
[:octicons-tag-24: 7.3.0][Section index pages support] ·
:octicons-unlock-24: Feature flag
When section index pages are enabled, documents can be directly attached to
@@ -225,13 +224,13 @@ theme:
1. This feature flag is not compatible with [`toc.integrate`][toc.integrate],
as sections cannot host the table of contents due to missing space.
=== ":octicons-check-circle-fill-16: Enabled"
=== "With section index pages"
[![navigation.indexes enabled]][navigation.indexes enabled]
[![Section index pages enabled]][Section index pages enabled]
=== ":octicons-skip-16: Disabled"
=== "Without"
[![navigation.indexes disabled]][navigation.indexes disabled]
[![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
@@ -246,17 +245,16 @@ nav:
- Page n: section/page-n.md
```
[navigation.indexes support]: https://github.com/squidfunk/mkdocs-material/releases/tag/7.3.0
[navigation.indexes enabled]: ../assets/screenshots/navigation-index-on.png
[navigation.indexes disabled]: ../assets/screenshots/navigation-index-off.png
[Section index pages support]: https://github.com/squidfunk/mkdocs-material/releases/tag/7.3.0
[Section index pages enabled]: ../assets/screenshots/navigation-index-on.png
[Section index pages disabled]: ../assets/screenshots/navigation-index-off.png
[toc.integrate]: #navigation-integration
### Table of contents
#### Anchor following
[:octicons-heart-fill-24:{ .mdx-heart } Sponsors only][Insiders]{ .mdx-insiders } ·
[:octicons-tag-24: insiders-4.8.0][Insiders] ·
[:octicons-tag-24: 8.5.0][Anchor following support] ·
:octicons-beaker-24: Experimental
When anchor following for the [table of contents] is enabled, the sidebar is
@@ -269,11 +267,11 @@ theme:
- toc.follow
```
[Insiders]: ../insiders/index.md
[Anchor following support]: https://github.com/squidfunk/mkdocs-material/releases/tag/8.5.0
#### Navigation integration
[:octicons-tag-24: 6.2.0][toc.integrate support] ·
[:octicons-tag-24: 6.2.0][Navigation integration support] ·
:octicons-unlock-24: Feature flag
When navigation integration for the [table of contents] is enabled, it is always
@@ -290,23 +288,23 @@ theme:
[`navigation.indexes`][navigation.indexes], as sections cannot host the
table of contents due to missing space.
=== ":octicons-check-circle-fill-16: Enabled"
=== "With navigation integration"
[![toc.integrate enabled]][toc.integrate enabled]
[![Navigation integration enabled]][Navigation integration enabled]
=== ":octicons-skip-16: Disabled"
=== "Without"
[![toc.integrate disabled]][toc.integrate disabled]
[![Navigation integration disabled]][Navigation integration disabled]
[table of contents]: extensions/python-markdown.md#table-of-contents
[toc.integrate support]: https://github.com/squidfunk/mkdocs-material/releases/tag/7.3.0
[toc.integrate enabled]: ../assets/screenshots/toc-integrate.png
[toc.integrate disabled]: ../assets/screenshots/navigation-tabs.png
[Navigation integration support]: https://github.com/squidfunk/mkdocs-material/releases/tag/7.3.0
[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
[:octicons-tag-24: 7.1.0][navigation.top support] ·
[:octicons-tag-24: 7.1.0][Back-to-top button support] ·
:octicons-unlock-24: Feature flag
A back-to-top button can be shown when the user, after scrolling down, starts
@@ -319,7 +317,7 @@ theme:
- navigation.top
```
[navigation.top support]: https://github.com/squidfunk/mkdocs-material/releases/tag/7.1.0
[Back-to-top button support]: https://github.com/squidfunk/mkdocs-material/releases/tag/7.1.0
## Usage
@@ -329,7 +327,7 @@ 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:
``` sh
``` yaml
---
hide:
- navigation
@@ -342,19 +340,19 @@ hide:
=== "Hide navigation"
[![hide.navigation enabled]][hide.navigation enabled]
[![Hide navigation enabled]][Hide navigation enabled]
=== "Hide table of contents"
[![hide.toc enabled]][hide.toc enabled]
[![Hide table of contents enabled]][Hide table of contents enabled]
=== "Hide both"
[![hide.* enabled]][hide.* enabled]
[![Hide both enabled]][Hide both enabled]
[hide.navigation enabled]: ../assets/screenshots/hide-navigation.png
[hide.toc enabled]: ../assets/screenshots/hide-toc.png
[hide.* enabled]: ../assets/screenshots/hide-navigation-toc.png
[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
## Customization
@@ -363,7 +361,7 @@ hide:
Material for MkDocs includes several keyboard shortcuts that make it possible
to navigate your project documentation via keyboard. There are two modes:
`search`{ #mode-search }
[`search`](#mode:search){ #mode:search }
: This mode is active when the _search is focused_. It provides several key
bindings to make search accessible and navigable via keyboard:
@@ -372,7 +370,7 @@ to navigate your project documentation via keyboard. There are two modes:
* ++esc++ , ++tab++ : close search dialog
* ++enter++ : follow selected result
`global`{ #mode-global }
[`global`](#mode:global){ #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
@@ -386,7 +384,7 @@ 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"
=== ":octicons-file-code-16: `docs/javascripts/shortcuts.js`"
``` js
keyboard$.subscribe(function(key) {
@@ -401,7 +399,7 @@ your custom event listener:
underlying event, so the keypress will not propagate further and
touch other event listeners.
=== ":octicons-file-code-16: mkdocs.yml"
=== ":octicons-file-code-16: `mkdocs.yml`"
``` yaml
extra_javascript:
@@ -421,7 +419,7 @@ 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"
=== ":octicons-file-code-16: `docs/stylesheets/extra.css`"
``` css
.md-grid {
@@ -438,7 +436,7 @@ of CSS:
}
```
=== ":octicons-file-code-16: mkdocs.yml"
=== ":octicons-file-code-16: `mkdocs.yml`"
``` yaml
extra_css:

32
docs/setup/setting-up-site-analytics.md
View File

@@ -10,7 +10,7 @@ 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#native-cookie-consent
[cookie consent]: ensuring-data-privacy.md#cookie-consent
[feedback widget]: #was-this-page-helpful
## Configuration
@@ -70,7 +70,7 @@ following lines to `mkdocs.yml`:
### Was this page helpful?
[:octicons-tag-24: 8.4.0][feedback support] ·
[:octicons-tag-24: 8.4.0][Was this page helpful? support] ·
:octicons-milestone-24: Default: _none_ ·
:octicons-beaker-24: Experimental
@@ -169,9 +169,9 @@ integrated with the [cookie consent] feature[^1].
The following properties are available for each rating:
`icon`{ #feedback-rating-icon }
[`icon`](#+analytics.feedback.ratings.icon){ #+analytics.feedback.ratings.icon }
: :octicons-milestone-24: Default: _none_ · :octicons-alert-24: Required –
: :octicons-milestone-24: Default: _none_ · :octicons-alert-24: __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:
@@ -180,24 +180,24 @@ The following properties are available for each rating:
* :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`
`name`{ #feedback-rating-name }
[`name`](#+analytics.feedback.ratings.name){ #+analytics.feedback.ratings.name }
: :octicons-milestone-24: Default: _none_ · :octicons-alert-24: Required –
: :octicons-milestone-24: Default: _none_ · :octicons-alert-24: __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.
`data`{ #feedback-rating-data }
[`data`](#+analytics.feedback.ratings.data){ #+analytics.feedback.ratings.data }
: :octicons-milestone-24: Default: _none_ · :octicons-alert-24: Required –
: :octicons-milestone-24: Default: _none_ · :octicons-alert-24: __Required__ –
The value of this property is sent as a data value with the custom event
that is transmitted to Google Analytics[^2] (or any custom integration).
[^2]:
Note that for Google Analytics, the data value must be an integer.
`note`{ #feedback-rating-note }
[`note`](#+analytics.feedback.ratings.note){ #+analytics.feedback.ratings.note }
: :octicons-milestone-24: Default: _none_ · :octicons-alert-24: Required –
: :octicons-milestone-24: Default: _none_ · :octicons-alert-24: __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.
@@ -221,7 +221,7 @@ The following properties are available for each rating:
An alternative to GitHub issues is [Google Forms].
[feedback support]: https://github.com/squidfunk/mkdocs-material/releases/tag/8.4.0
[Was this page helpful? support]: https://github.com/squidfunk/mkdocs-material/releases/tag/8.4.0
[feedback widget]: #feedback
[analytics]: #google-analytics
[feedback report]: ../assets/screenshots/feedback-report.png
@@ -235,7 +235,7 @@ The following properties are available for each rating:
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:
``` sh
``` yaml
---
hide:
- feedback
@@ -254,7 +254,7 @@ 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"
=== ":octicons-file-code-16: `overrides/partials/integrations/analytics/custom.html`"
``` html
<script>
@@ -276,7 +276,7 @@ used to configure the custom integration via `mkdocs.yml`:
observable to listen for navigation events, which always emits the
current `URL`.
=== ":octicons-file-code-16: mkdocs.yml"
=== ":octicons-file-code-16: `mkdocs.yml`"
``` yaml
extra:
@@ -298,7 +298,7 @@ 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"
=== ":octicons-file-code-16: `docs/javascripts/feedback.js`"
``` js
var feedback = document.forms.feedback
@@ -314,7 +314,7 @@ generated by users interacting with the feedback widget with the help of some
})
```
=== ":octicons-file-code-16: mkdocs.yml"
=== ":octicons-file-code-16: `mkdocs.yml`"
``` yaml
extra_javascript:

64
docs/setup/setting-up-site-search.md
View File

@@ -17,7 +17,7 @@ not be compliant with privacy regulations. Moreover, search even works
### Built-in search plugin
[:octicons-tag-24: 0.1.0][search support] ·
[:octicons-tag-24: 0.1.0][Search support] ·
:octicons-cpu-24: Plugin
The built-in search plugin integrates seamlessly with Material for MkDocs,
@@ -32,7 +32,7 @@ plugins:
The following configuration options are supported:
`lang`{ #search-lang }
[`lang`](#+search.lang){ #+search.lang }
: :octicons-milestone-24: Default: _automatically set_ – This option allows
to include the language-specific stemmers provided by [lunr-languages].
@@ -92,7 +92,7 @@ The following configuration options are supported:
part of this list by automatically falling back to the stemmer yielding the
best result.
`separator`{ #search-separator }
[`separator`](#+search.separator){ #+search.separator }
: :octicons-milestone-24: Default: _automatically set_ – The separator for
indexing and query tokenization can be customized, making it possible to
@@ -112,7 +112,7 @@ The following configuration options are supported:
<div class="mdx-deprecated" markdown>
`prebuild_index`{ #search-prebuild-index }
[`prebuild_index`](#+search.prebuild_index){ #+search.prebuild_index }
: [:octicons-tag-24: 5.0.0][prebuilt index support] · :octicons-archive-24:
Deprecated · :octicons-trash-24: 8.0.0 · :octicons-milestone-24: Default:
@@ -135,7 +135,7 @@ The following configuration options are supported:
</div>
[search support]: https://github.com/squidfunk/mkdocs-material/releases/tag/0.1.0
[Search support]: https://github.com/squidfunk/mkdocs-material/releases/tag/0.1.0
[lunr]: https://lunrjs.com
[lunr-languages]: https://github.com/MihaiValentin/lunr-languages
[lunr's default tokenizer]: https://github.com/olivernn/lunr.js/blob/aa5a878f62a6bba1e8e5b95714899e17e8150b38/lunr.js#L413-L456
@@ -143,7 +143,7 @@ The following configuration options are supported:
[tokenizer lookahead]: #tokenizer-lookahead
[prebuilt index support]: https://github.com/squidfunk/mkdocs-material/releases/tag/5.0.0
[prebuilt index]: https://www.mkdocs.org/user-guide/configuration/#prebuild_index
[50% smaller]: ../blog/2021/search-better-faster-smaller.md#benchmarks
[50% smaller]: ../blog/posts/search-better-faster-smaller.md#benchmarks
#### Chinese language support
@@ -163,7 +163,7 @@ If [jieba] is installed, the [built-in search plugin] automatically detects
Chinese characters and runs them through the segmenter. The following
configuration options are available:
`jieba_dict`{ #jieba-dict }
[`jieba_dict`](#+search.jieba_dict){ #+search.jieba_dict }
: [:octicons-tag-24: insiders-4.17.2][Insiders] · :octicons-milestone-24:
Default: _none_ – This option allows for specifying a [custom dictionary]
@@ -180,7 +180,7 @@ configuration options are available:
- [dict.txt.small] – 占用内存较小的词典文件
- [dict.txt.big] – 支持繁体分词更好的词典文件
`jieba_dict_user`{ #jieba-dict-user }
[`jieba_dict_user`](#+search.jieba_dict_user){ #+search.jieba_dict_user }
: [:octicons-tag-24: insiders-4.17.2][Insiders] · :octicons-milestone-24:
Default: _none_ – This option allows for specifying an additional
@@ -196,7 +196,7 @@ configuration options are available:
User dictionaries can be used for tuning the segmenter to preserve
technical terms.
[chinese search]: ../blog/2022/chinese-search-support.md
[chinese search]: ../blog/posts/chinese-search-support.md
[jieba]: https://pypi.org/project/jieba/
[built-in search plugin]: #built-in-search-plugin
[custom dictionary]: https://github.com/fxsjy/jieba#%E5%85%B6%E4%BB%96%E8%AF%8D%E5%85%B8
@@ -223,9 +223,9 @@ occurrences inside those blocks:
![search preview before]
[Insiders]: ../insiders/index.md
[new search plugin]: ../blog/2021/search-better-faster-smaller.md
[search preview now]: ../blog/2021/search-better-faster-smaller/search-preview-now.png
[search preview before]: ../blog/2021/search-better-faster-smaller/search-preview-before.png
[new search plugin]: ../blog/posts/search-better-faster-smaller.md
[search preview now]: ../blog/posts/search-better-faster-smaller/search-preview-now.png
[search preview before]: ../blog/posts/search-better-faster-smaller/search-preview-before.png
### Tokenizer lookahead
@@ -290,13 +290,13 @@ The following section explains what can be achieved with tokenizer lookahead:
[separator]: #search-separator
[words are split at case changes]: ?q=searchHighlight
[tokenize case changes]: ../blog/2021/search-better-faster-smaller.md#case-changes
[tokenize version numbers]: ../blog/2021/search-better-faster-smaller.md#version-numbers
[tokenize html-xml tags]: ../blog/2021/search-better-faster-smaller.md#htmlxml-tags
[tokenize case changes]: ../blog/posts/search-better-faster-smaller.md#case-changes
[tokenize version numbers]: ../blog/posts/search-better-faster-smaller.md#version-numbers
[tokenize html-xml tags]: ../blog/posts/search-better-faster-smaller.md#htmlxml-tags
### Search suggestions
[:octicons-tag-24: 7.2.0][search.suggest support] ·
[:octicons-tag-24: 7.2.0][Search suggestions support] ·
:octicons-unlock-24: Feature flag ·
:octicons-beaker-24: Experimental
@@ -310,15 +310,15 @@ theme:
- search.suggest
```
Searching for [:octicons-search-24: search su][search.suggest example] yields
^^search suggestions^^ as a suggestion.
Searching for [:octicons-search-24: search su][Search suggestions example]
yields ^^search suggestions^^ as a suggestion.
[search.suggest support]: https://github.com/squidfunk/mkdocs-material/releases/tag/7.2.0
[search.suggest example]: ?q=search+su
[Search suggestions support]: https://github.com/squidfunk/mkdocs-material/releases/tag/7.2.0
[Search suggestions example]: ?q=search+su
### Search highlighting
[:octicons-tag-24: 7.2.0][search.highlight support] ·
[:octicons-tag-24: 7.2.0][Search highlighting support] ·
:octicons-unlock-24: Feature flag ·
:octicons-beaker-24: Experimental
@@ -332,15 +332,15 @@ theme:
- search.highlight
```
Searching for [:octicons-search-24: code blocks][search.highlight example]
Searching for [:octicons-search-24: code blocks][Search highlighting example]
highlights all occurrences of both terms.
[search.highlight support]: https://github.com/squidfunk/mkdocs-material/releases/tag/7.2.0
[search.highlight example]: ../reference/code-blocks.md?h=code+blocks
[Search highlighting support]: https://github.com/squidfunk/mkdocs-material/releases/tag/7.2.0
[Search highlighting example]: ../reference/code-blocks.md?h=code+blocks
### Search sharing
[:octicons-tag-24: 7.2.0][search.share support] ·
[:octicons-tag-24: 7.2.0][Search sharing support] ·
:octicons-unlock-24: Feature flag ·
:octicons-beaker-24: Experimental
@@ -357,7 +357,7 @@ theme:
When a user clicks the share button, the URL is automatically copied to the
clipboard.
[search.share support]: https://github.com/squidfunk/mkdocs-material/releases/tag/7.2.0
[Search sharing support]: https://github.com/squidfunk/mkdocs-material/releases/tag/7.2.0
## Usage
@@ -370,7 +370,7 @@ 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:
``` sh
``` yaml
---
search:
boost: 2 # (1)!
@@ -395,7 +395,7 @@ 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:
``` sh
``` yaml
---
search:
exclude: true
@@ -411,7 +411,7 @@ 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"
=== ":octicons-file-code-16: `docs/page.md`"
``` markdown
# Document title
@@ -425,7 +425,7 @@ heading:
The content of this section is excluded
```
=== ":octicons-codescan-16: search_index.json"
=== ":octicons-codescan-16: `search_index.json`"
``` json
{
@@ -453,7 +453,7 @@ 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"
=== ":octicons-file-code-16: `docs/page.md`"
``` markdown
# Document title
@@ -464,7 +464,7 @@ inline- or block-level element:
{ data-search-exclude }
```
=== ":octicons-codescan-16: search_index.json"
=== ":octicons-codescan-16: `search_index.json`"
``` json
{

104
docs/setup/setting-up-social-cards.md
View File

@@ -6,8 +6,8 @@ template: overrides/main.html
Social cards, also known as social previews, are images that are displayed when
a link to your project documentation is shared on social media. Material for
MkDocs can generate beautiful social cards automatically, using the [colors]
[palette.primary], [fonts][font.text] and [logo][^1] defined in `mkdocs.yml`,
MkDocs can generate beautiful social cards automatically, using the [colors],
[fonts] and [logo][^1] defined in `mkdocs.yml`,
e.g.:
<figure markdown>
@@ -28,8 +28,8 @@ The social preview image for the page on [setting up site analytics].
color used in the header (white or black), which depends on the primary
color.
[palette.primary]: changing-the-colors.md#primary-color
[font.text]: changing-the-fonts.md#regular-font
[colors]: changing-the-colors.md#primary-color
[fonts]: changing-the-fonts.md#regular-font
[logo]: changing-the-logo-and-icons.md#logo
[Social cards preview]: ../assets/screenshots/social-cards.png
[setting up site analytics]: setting-up-site-analytics.md
@@ -39,8 +39,7 @@ The social preview image for the page on [setting up site analytics].
### Built-in social plugin
[:octicons-heart-fill-24:{ .mdx-heart } Sponsors only][Insiders]{ .mdx-insiders } ·
[:octicons-tag-24: insiders-2.12.0][Insiders] ·
[:octicons-tag-24: 8.5.0][Social cards support] ·
:octicons-cpu-24: Plugin ·
:octicons-beaker-24: Experimental
@@ -53,13 +52,9 @@ plugins:
- social
```
> If you need to be able to build your documentation with and without
> [Insiders], please refer to the [built-in plugins] section to learn how
> shared configurations help to achieve this.
The following configuration options are available:
`cards`{ #cards }
[`cards`](#+social.cards){ #+social.cards }
: :octicons-milestone-24: Default: `true` – This option specifies whether
to generate social card images. If you want to switch the plugin off, e.g.
@@ -71,12 +66,11 @@ The following configuration options are available:
cards: !ENV [CARDS, false]
```
`cards_color`{ #cards-color }
[`cards_color`](#+social.cards_color){ #+social.cards_color }
: [:octicons-tag-24: insiders-2.13.0][Insiders] · :octicons-milestone-24:
Default: [`theme.palette.primary`][palette.primary] – This option specifies
the colors for the background `fill` and foreground `text` when generating
the social card:
: :octicons-milestone-24: Default: [`theme.palette.primary`][palette.primary]
– This option specifies the colors for the background `fill` and foreground
`text` when generating the social card:
``` yaml
plugins:
@@ -89,12 +83,11 @@ The following configuration options are available:
1. Colors can either be defined as HEX colors, or as [CSS color keywords].
Note that HEX colors must be enclosed in quotes.
`cards_font`{ #cards-font }
[`cards_font`](#+social.cards_font){ #+social.cards_font }
: [:octicons-tag-24: insiders-4.3.0][Insiders] · :octicons-milestone-24:
Default: [`theme.font.text`][font.text] – This option specifies which font
to use for rendering the social card, which can be any font hosted on
[Google Fonts]:
: :octicons-milestone-24: Default: [`theme.font.text`][font.text] – This
option specifies which font to use for rendering the social card, which can
be any font hosted on [Google Fonts]:
``` yaml
plugins:
@@ -102,7 +95,47 @@ The following configuration options are available:
cards_font: Roboto
```
`cards_dir`{ #cards-dir }
!!! question "Why do social cards render boxes for CJK languages?"
Some fonts do not contain CJK characters, like for example the
[default font, `Roboto`][font.text]. 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_font: Noto Sans SC
```
=== "Chinese (Traditional)"
``` yaml
plugins:
- social:
cards_font: Noto Sans TC
```
=== "Japanese"
``` yaml
plugins:
- social:
cards_font: Noto Sans JP
```
=== "Korean"
``` yaml
plugins:
- social:
cards_font: Noto Sans KR
```
[`cards_dir`](#+social.cards_dir){ #+social.cards_dir }
: :octicons-milestone-24: Default: `assets/images/social` – This option
specifies where the generated social card images will be written to. It's
@@ -111,28 +144,33 @@ The following configuration options are available:
``` yaml
plugins:
- social:
cards_dir: assets/images/social
cards_dir: path/to/folder
```
[Insiders]: ../insiders/index.md
[Social cards support]: https://github.com/squidfunk/mkdocs-material/releases/tag/8.5.0
[dependencies]: #dependencies
[site_url]: https://www.mkdocs.org/user-guide/configuration/#site_url
[built-in plugins]: ../insiders/getting-started.md#built-in-plugins
[palette.primary]: changing-the-colors.md#primary-color
[font.text]: changing-the-fonts.md#regular-font
[environment variable]: https://www.mkdocs.org/user-guide/configuration/#environment-variables
[CSS color keywords]: https://developer.mozilla.org/en-US/docs/Web/CSS/color_value#color_keywords
[Google Fonts]: https://fonts.google.com
[page title]: ../reference/index.md#setting-the-page-title
#### Dependencies
Two Python packages are installed alongside Material for MkDocs to generate the
social preview images, both of which are based on the [Cairo Graphics] library:
Two Python libraries must be installed alongside Material for MkDocs to generate
the social preview images, both of which are based on [Cairo Graphics] –
[Pillow] and [CairoSVG]:
- [Pillow] – Python imaging library
- [CairoSVG] – Converter for `*.svg` files
```
pip install pillow cairosvg
```
The [Docker image] for Insiders comes with all dependencies pre-installed. If
you don't want to use Docker, see the following section which explains how to
install all dependencies on your system:
Both libraries are built with native extensions which need to be installed as
well. The [Docker image] comes with all dependencies pre-installed. If you don't
want to use Docker, see the following section which explains how to install all
dependencies on your system:
=== ":material-apple: macOS"
@@ -177,7 +215,7 @@ install all dependencies on your system:
[Cairo Graphics]: https://www.cairographics.org/
[Pillow]: https://pillow.readthedocs.io/
[CairoSVG]: https://cairosvg.org/
[Docker image]: ../insiders/getting-started.md#with-docker
[Docker image]: https://hub.docker.com/r/squidfunk/mkdocs-material/
[Homebrew]: https://brew.sh/
[installation guide]: https://www.cairographics.org/download/
[GTK+]: https://www.gtk.org/docs/installations/windows/

28
docs/setup/setting-up-tags.md
View File

@@ -15,7 +15,7 @@ can help to discover relevant information faster.
### Built-in tags plugin
[:octicons-tag-24: 8.2.0][tags support] ·
[:octicons-tag-24: 8.2.0][Tags support] ·
:octicons-cpu-24: Plugin ·
:octicons-beaker-24: Experimental
@@ -30,7 +30,7 @@ plugins:
The following configuration options are available:
`tags_file`{ #tags-file }
[`tags_file`](#+tags.tags_file){ #+tags.tags_file }
: :octicons-milestone-24: Default: _none_ – This option specifies which file
should be used to render the tags index. See the section on [adding a tags
@@ -48,7 +48,7 @@ The following configuration options are available:
of `mkdocs.yml`. Note, however, that this options is not required – only use
it if you want a tags index page.
`tags_extra_files`{ #tags-extra-files } :material-alert-decagram:{ .mdx-pulse title="Added on July 7, 2022" }
[`tags_extra_files`](#+tags.tags_extra_files){ #+tags.tags_extra_files } :material-alert-decagram:{ .mdx-pulse title="Added on July 7, 2022" }
: [:octicons-tag-24: insiders-4.20.0][Insiders] · :octicons-milestone-24:
Default: _none_ – This option allows to define additional pages to render
@@ -86,13 +86,13 @@ The following configuration options are available:
See #3864 for additional use cases.
[tags support]: https://github.com/squidfunk/mkdocs-material/releases/tag/8.2.0
[Tags support]: https://github.com/squidfunk/mkdocs-material/releases/tag/8.2.0
[Insiders]: ../insiders/index.md
[tag identifiers]: #tag-icons
### Tag icons
[:octicons-heart-fill-24:{ .mdx-heart } Sponsors only][Insiders]{ .mdx-insiders } ·
[:octicons-tag-24: insiders-4.13.0][Insiders] ·
[:octicons-tag-24: 8.5.0][Tag icons support] ·
:octicons-beaker-24: Experimental
Each tag can be associated with an icon, which is then rendered inside the tag.
@@ -118,9 +118,9 @@ extra:
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, or even a [custom icon],
by adding the following lines to `mkdocs.yml` under the `theme.icon`
configuration setting:
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"
@@ -167,7 +167,7 @@ configuration setting:
CSS: css
```
[Insiders]: ../insiders/index.md
[Tag icons support]: https://github.com/squidfunk/mkdocs-material/releases/tag/8.5.0
[custom icon]: changing-the-logo-and-icons.md#additional-icons
[icon search]: ../reference/icons-emojis.md#search
@@ -197,7 +197,7 @@ search preview, which now allows to __find pages by tags__.
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`
in the corresponding folder with the following content:
file in the corresponding folder with the following content:
``` yaml
tags:
@@ -232,10 +232,10 @@ 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][9]][9]
[![Tags index][tags index enabled]][tags index enabled]
[tags.tags_file]: #tags-file
[9]: ../assets/screenshots/tags-index.png
[tags index enabled]: ../assets/screenshots/tags-index.png
### Hiding tags on a page
@@ -243,7 +243,7 @@ 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:
``` sh
``` yaml
---
hide:
- tags

33
docs/setup/setting-up-the-footer.md
View File

@@ -14,7 +14,7 @@ configure via `mkdocs.yml`.
### Social links
[:octicons-tag-24: 1.0.0][social support] ·
[:octicons-tag-24: 1.0.0][Social links support] ·
:octicons-milestone-24: Default: _none_
Social links are rendered next to the copyright notice as part of the
@@ -41,14 +41,12 @@ extra:
The following properties are available for each link:
`icon`{ #social-icon }
[`icon`](#+social.icon){ #+social.icon }
: [:octicons-tag-24: 5.0.0][social.icon support] · :octicons-milestone-24:
Default: _none_ · :octicons-alert-24: Required – This property must contain
a valid path to any icon bundled with the theme, or the
build will not succeed. Some popular choices:
: :octicons-milestone-24: Default: _none_ · :octicons-alert-24: __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-behance: – `fontawesome/brands/behance`
* :fontawesome-brands-docker: – `fontawesome/brands/docker`
* :fontawesome-brands-facebook: – `fontawesome/brands/facebook`
* :fontawesome-brands-github: – `fontawesome/brands/github`
@@ -60,9 +58,9 @@ The following properties are available for each link:
* :fontawesome-brands-slack: – `fontawesome/brands/slack`
* :fontawesome-brands-twitter: – `fontawesome/brands/twitter`
`link`{ #social-link }
[`link`](#+social.link){ #+social.link }
: :octicons-milestone-24: Default: _none_ · :octicons-alert-24: Required –
: :octicons-milestone-24: Default: _none_ · :octicons-alert-24: __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`:
@@ -84,12 +82,11 @@ The following properties are available for each link:
link: mailto:<email-address>
```
`name`{ #social-name }
[`name`](#+social.name){ #+social.name }
: [:octicons-tag-24: 5.1.5][social.name support] · :octicons-milestone-24:
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:
: :octicons-milestone-24: 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:
@@ -100,9 +97,7 @@ The following properties are available for each link:
```
[icon search]: ../reference/icons-emojis.md#search
[social support]: https://github.com/squidfunk/mkdocs-material/releases/tag/1.0.0
[social.icon support]: https://github.com/squidfunk/mkdocs-material/releases/tag/5.0.0
[social.name support]: https://github.com/squidfunk/mkdocs-material/releases/tag/5.1.5
[Social links support]: https://github.com/squidfunk/mkdocs-material/releases/tag/1.0.0
### Copyright notice
@@ -156,7 +151,7 @@ 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:
``` sh
``` yaml
---
hide:
- footer
@@ -174,7 +169,7 @@ hide:
:octicons-file-symlink-file-24: Customization
In order to customize and override the [copyright notice], [extend the theme]
and [override the `copyright` partial][overriding partials], which normally
and [override the `copyright.html` partial][overriding partials], which normally
includes the `copyright` property set in `mkdocs.yml`.
[Custom copyright support]: https://github.com/squidfunk/mkdocs-material/releases/tag/8.0.0

4
docs/setup/setting-up-versioning.md
View File

@@ -15,7 +15,7 @@ documentation remain untouched.
### Versioning
[:octicons-tag-24: 7.0.0][version support] ·
[:octicons-tag-24: 7.0.0][Versioning support] ·
[:octicons-package-24: Utility][mike]
[mike] makes it easy to deploy multiple versions of your project documentation.
@@ -55,7 +55,7 @@ Check out the versioning example to see it in action –
to particularly notable versions. This makes it easy to make permalinks to
whatever version of the documentation you want to direct people to.
[version support]: https://github.com/squidfunk/mkdocs-material/releases/tag/7.0.0
[Versioning support]: https://github.com/squidfunk/mkdocs-material/releases/tag/7.0.0
[Version selector preview]: ../assets/screenshots/versioning.png
[version example]: https://squidfunk.github.io/mkdocs-material-example-versioning/
[Why use mike?]: https://github.com/jimporter/mike#why-use-mike