mirror of
https://github.com/squidfunk/mkdocs-material.git
synced 2024-11-24 07:30:12 +01:00
Updated documentation
This commit is contained in:
squidfunk
parent
43cdb91472
commit
a0ff73932f
@ -299,7 +299,7 @@ will stretch to the full width of the viewport, e.g. on mobile viewports.
|
||||
Following is a list of type qualifiers provided by Material for MkDocs, whereas
|
||||
the default type, and thus fallback for unknown type qualifiers, is `note`:
|
||||
|
||||
`note`{ #note }, ~~`seealso`~~ [^1]
|
||||
`note`{ #type-note }, ~~`seealso`~~ [^1]
|
||||
|
||||
: !!! note
|
||||
|
||||
@ -307,7 +307,7 @@ the default type, and thus fallback for unknown type qualifiers, is `note`:
|
||||
euismod nulla. Curabitur feugiat, tortor non consequat finibus, justo
|
||||
purus auctor massa, nec semper lorem quam in massa.
|
||||
|
||||
`abstract`{ #abstract }, `summary`, `tldr`
|
||||
`abstract`{ #type-abstract }, `summary`, `tldr`
|
||||
|
||||
: !!! abstract
|
||||
|
||||
@ -315,7 +315,7 @@ the default type, and thus fallback for unknown type qualifiers, is `note`:
|
||||
euismod nulla. Curabitur feugiat, tortor non consequat finibus, justo
|
||||
purus auctor massa, nec semper lorem quam in massa.
|
||||
|
||||
`info`{ #info }, `todo`
|
||||
`info`{ #type-info }, `todo`
|
||||
|
||||
: !!! info
|
||||
|
||||
@ -323,7 +323,7 @@ the default type, and thus fallback for unknown type qualifiers, is `note`:
|
||||
euismod nulla. Curabitur feugiat, tortor non consequat finibus, justo
|
||||
purus auctor massa, nec semper lorem quam in massa.
|
||||
|
||||
`tip`{ #tip }, `hint`, `important`
|
||||
`tip`{ #type-tip }, `hint`, `important`
|
||||
|
||||
: !!! tip
|
||||
|
||||
@ -331,7 +331,7 @@ the default type, and thus fallback for unknown type qualifiers, is `note`:
|
||||
euismod nulla. Curabitur feugiat, tortor non consequat finibus, justo
|
||||
purus auctor massa, nec semper lorem quam in massa.
|
||||
|
||||
`success`{ #success }, `check`, `done`
|
||||
`success`{ #type-success }, `check`, `done`
|
||||
|
||||
: !!! success
|
||||
|
||||
@ -339,7 +339,7 @@ the default type, and thus fallback for unknown type qualifiers, is `note`:
|
||||
euismod nulla. Curabitur feugiat, tortor non consequat finibus, justo
|
||||
purus auctor massa, nec semper lorem quam in massa.
|
||||
|
||||
`question`{ #question }, `help`, `faq`
|
||||
`question`{ #type-question }, `help`, `faq`
|
||||
|
||||
: !!! question
|
||||
|
||||
@ -347,7 +347,7 @@ the default type, and thus fallback for unknown type qualifiers, is `note`:
|
||||
euismod nulla. Curabitur feugiat, tortor non consequat finibus, justo
|
||||
purus auctor massa, nec semper lorem quam in massa.
|
||||
|
||||
`warning`{ #warning }, `caution`, `attention`
|
||||
`warning`{ #type-warning }, `caution`, `attention`
|
||||
|
||||
: !!! warning
|
||||
|
||||
@ -355,7 +355,7 @@ the default type, and thus fallback for unknown type qualifiers, is `note`:
|
||||
euismod nulla. Curabitur feugiat, tortor non consequat finibus, justo
|
||||
purus auctor massa, nec semper lorem quam in massa.
|
||||
|
||||
`failure`{ #failure }, `fail`, `missing`
|
||||
`failure`{ #type-failure }, `fail`, `missing`
|
||||
|
||||
: !!! failure
|
||||
|
||||
@ -363,7 +363,7 @@ the default type, and thus fallback for unknown type qualifiers, is `note`:
|
||||
euismod nulla. Curabitur feugiat, tortor non consequat finibus, justo
|
||||
purus auctor massa, nec semper lorem quam in massa.
|
||||
|
||||
`danger`{ #danger }, `error`
|
||||
`danger`{ #type-danger }, `error`
|
||||
|
||||
: !!! danger
|
||||
|
||||
@ -371,7 +371,7 @@ the default type, and thus fallback for unknown type qualifiers, is `note`:
|
||||
euismod nulla. Curabitur feugiat, tortor non consequat finibus, justo
|
||||
purus auctor massa, nec semper lorem quam in massa.
|
||||
|
||||
`bug`{ #bug }
|
||||
`bug`{ #type-bug }
|
||||
|
||||
: !!! bug
|
||||
|
||||
@ -379,7 +379,7 @@ the default type, and thus fallback for unknown type qualifiers, is `note`:
|
||||
euismod nulla. Curabitur feugiat, tortor non consequat finibus, justo
|
||||
purus auctor massa, nec semper lorem quam in massa.
|
||||
|
||||
`example`{ #example }
|
||||
`example`{ #type-example }
|
||||
|
||||
: !!! example
|
||||
|
||||
@ -387,7 +387,7 @@ the default type, and thus fallback for unknown type qualifiers, is `note`:
|
||||
euismod nulla. Curabitur feugiat, tortor non consequat finibus, justo
|
||||
purus auctor massa, nec semper lorem quam in massa.
|
||||
|
||||
`quote`{ #quote }, `cite`
|
||||
`quote`{ #type-quote }, `cite`
|
||||
|
||||
: !!! quote
|
||||
|
||||
|
||||
@ -120,16 +120,10 @@ _Result_:
|
||||
|
||||
Modern browsers provide [native support for lazy-loading images][lazy-loading]
|
||||
through the `loading=lazy` directive, which degrades to eager-loading in
|
||||
browsers without support
|
||||
|
||||
_Example_:
|
||||
browsers without support:
|
||||
|
||||
``` markdown
|
||||
{ loading=lazy }
|
||||
```
|
||||
|
||||
_Result_:
|
||||
|
||||
{ loading=lazy width=300 }
|
||||
|
||||
[lazy-loading]: https://caniuse.com/#feat=loading-lazy-attr
|
||||
|
||||
@ -312,6 +312,9 @@ in the [color schemes][palette.scheme] section:
|
||||
=== ":octicons-file-code-16: mkdocs.yml"
|
||||
|
||||
``` yaml
|
||||
theme:
|
||||
palette:
|
||||
scheme: youtube
|
||||
extra_css:
|
||||
- stylesheets/extra.css
|
||||
```
|
||||
|
||||
@ -132,12 +132,12 @@ The following properties must be set for each alternate language:
|
||||
the `hreflang` attribute of the link, improving discoverability via search
|
||||
engines.
|
||||
|
||||
[![Language selector]][Language selector]
|
||||
[![Language selector preview]][Language selector preview]
|
||||
|
||||
[alternate 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]: ../assets/screenshots/language-selection.png
|
||||
[Language selector preview]: ../assets/screenshots/language-selection.png
|
||||
|
||||
### Directionality
|
||||
|
||||
@ -180,23 +180,31 @@ Click on a tile to change the directionality:
|
||||
|
||||
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 your language as a fallback and only
|
||||
folder. Then, import the [translations] of the language as a fallback and only
|
||||
adjust the ones you want to override:
|
||||
|
||||
=== ":octicons-file-code-16: partials/languages/custom.html"
|
||||
|
||||
``` html
|
||||
<!-- Import translations for your language as fallback -->
|
||||
{% import "partials/languages/" ~ config.theme.language ~ ".html" as fallback %}
|
||||
<!-- 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) %}{{ {
|
||||
"toc.title": "On this page" <!-- (1) -->
|
||||
"toc.title": "Auf dieser Seite" <!-- (2) -->
|
||||
}[key] }}{% endmacro %}
|
||||
|
||||
<!-- Re-export translations -->
|
||||
{% macro t(key) %}{{ override(key) or fallback.t(key) }}{% endmacro %}
|
||||
{% macro t(key) %}{{
|
||||
override(key) or language(key) or fallback.t(key)
|
||||
}}{% endmacro %}
|
||||
```
|
||||
|
||||
1. Check the [list of available languages], pick the translation you want
|
||||
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"
|
||||
|
||||
@ -154,7 +154,7 @@ markdown_extensions:
|
||||
|
||||
The following configuration options are supported:
|
||||
|
||||
`mode`{ #mode }
|
||||
`mode`{ #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
|
||||
@ -265,7 +265,7 @@ The following configuration options are supported:
|
||||
|
||||
: :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
|
||||
explained in more detail in the [icon customization guide].
|
||||
explained in more detail in the [icon customization guide]:
|
||||
|
||||
``` yaml
|
||||
markdown_extensions:
|
||||
@ -318,7 +318,7 @@ markdown_extensions:
|
||||
|
||||
The following configuration options are supported:
|
||||
|
||||
`use_pygments`{ #use-pygments }
|
||||
`use_pygments`{ #highlight-use-pygments }
|
||||
|
||||
: :octicons-milestone-24: Default: `true` – This option allows to control
|
||||
whether highlighting should be carried out during build time using
|
||||
@ -365,7 +365,7 @@ The following configuration options are supported:
|
||||
|
||||
Note that [Highlight.js] has no affiliation with the Highlight extension.
|
||||
|
||||
`linenums`{ #linenums }
|
||||
`linenums`{ #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
|
||||
@ -379,7 +379,7 @@ The following configuration options are supported:
|
||||
linenums: true
|
||||
```
|
||||
|
||||
`linenums_style`{ #linenums-style }
|
||||
`linenums_style`{ #highlight-linenums-style }
|
||||
|
||||
: :octicons-milestone-24: Default: `table` – The [Highlight] extension
|
||||
provides three ways to add line numbers, all of which are supported by
|
||||
@ -544,7 +544,7 @@ markdown_extensions:
|
||||
|
||||
The following configuration options are supported:
|
||||
|
||||
`custom_fences`{ #custom-fences }
|
||||
`custom_fences`{ #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]
|
||||
@ -603,7 +603,7 @@ markdown_extensions:
|
||||
|
||||
The following configuration options are supported:
|
||||
|
||||
`alternate_style`{ #alternate-style }
|
||||
`alternate_style`{ #tabbed-alternate-style }
|
||||
|
||||
: :octicons-milestone-24: Default: `false` · [:octicons-tag-24: 7.3.1]
|
||||
[Tabbed alternate support] – This option enables the [alternate style] of
|
||||
@ -652,7 +652,7 @@ markdown_extensions:
|
||||
|
||||
The following configuration options are supported:
|
||||
|
||||
`custom_checkbox`{ #custom-checkbox }
|
||||
`custom_checkbox`{ #tasklist-custom-checkbox }
|
||||
|
||||
: :octicons-milestone-24: Default: `false` · This option toggles the rendering
|
||||
style of checkboxes, replacing native checkbox styles with beautiful icons,
|
||||
@ -664,7 +664,7 @@ The following configuration options are supported:
|
||||
custom_checkbox: true
|
||||
```
|
||||
|
||||
`clickable_checkbox`{ #clickable-checkbox }
|
||||
`clickable_checkbox`{ #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
|
||||
|
||||
@ -213,7 +213,7 @@ markdown_extensions:
|
||||
|
||||
The following configuration options are supported:
|
||||
|
||||
`permalink`{ #permalink }
|
||||
`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
|
||||
@ -236,7 +236,7 @@ The following configuration options are supported:
|
||||
permalink: ⚓︎
|
||||
```
|
||||
|
||||
`slugify`{ #slugify }
|
||||
`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
|
||||
@ -259,7 +259,7 @@ The following configuration options are supported:
|
||||
slugify: !!python/name:pymdownx.slugs.uslugify_cased
|
||||
```
|
||||
|
||||
`toc_depth`{ #toc_depth }
|
||||
`toc_depth`{ #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
|
||||
|
||||
@ -317,7 +317,7 @@ hide:
|
||||
Material for MkDocs includes several keyboard shortcuts that make it possible
|
||||
to navigate your project documentation via keyboard. There're two modes:
|
||||
|
||||
`search`{ #search }
|
||||
`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:
|
||||
@ -326,7 +326,7 @@ to navigate your project documentation via keyboard. There're two modes:
|
||||
* ++esc++ , ++tab++ : close search dialog
|
||||
* ++enter++ : follow selected result
|
||||
|
||||
`global`{ #global }
|
||||
`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
|
||||
|
||||
@ -6,25 +6,24 @@ template: overrides/main.html
|
||||
|
||||
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][1] and offers a customizable
|
||||
and extendable [cookie consent][2].
|
||||
MkDocs natively integrates with [Google Analytics] and offers a customizable
|
||||
and extendable [cookie consent][extra.consent].
|
||||
|
||||
[1]: https://developers.google.com/analytics
|
||||
[2]: #cookie-consent
|
||||
[Google Analytics]: https://developers.google.com/analytics
|
||||
[extra.consent]: #cookie-consent
|
||||
|
||||
## Configuration
|
||||
|
||||
### Google Analytics
|
||||
|
||||
:octicons-hash-24: Setting ·
|
||||
:octicons-milestone-24: Default: _none_ ·
|
||||
[:octicons-tag-24: 7.1.8][Google Analytics support]
|
||||
[:octicons-tag-24: 7.1.8][Google Analytics support] ·
|
||||
:octicons-milestone-24: Default: _none_
|
||||
|
||||
Material for MkDocs integrates with both, Google Analytics 4 and the now phasing
|
||||
out Universal Analytics (`UA-*`). Depending on the prefix of the property, add
|
||||
the following to `mkdocs.yml`:
|
||||
out Universal Analytics (`UA-*`). Depending on the property prefix, add the
|
||||
following lines to `mkdocs.yml`:
|
||||
|
||||
=== "Google Analytics 4"
|
||||
=== ":material-google-analytics: Google Analytics 4"
|
||||
|
||||
``` yaml
|
||||
extra:
|
||||
@ -33,7 +32,7 @@ the following to `mkdocs.yml`:
|
||||
property: G-XXXXXXXXXX
|
||||
```
|
||||
|
||||
=== "Universal Analytics"
|
||||
=== ":material-google-analytics: Universal Analytics"
|
||||
|
||||
``` yaml
|
||||
extra:
|
||||
@ -43,11 +42,10 @@ the following to `mkdocs.yml`:
|
||||
```
|
||||
|
||||
[Google Analytics support]: https://github.com/squidfunk/mkdocs-material/releases/tag/7.1.8
|
||||
[3]: https://github.com/squidfunk/mkdocs-material/blob/master/src/partials/integrations/analytics.html
|
||||
|
||||
#### Site search tracking
|
||||
|
||||
Besides basic page views, _site search_ can also be tracked to understand better
|
||||
Besides basic page views, site search can also be tracked to understand better
|
||||
how people use your documentation and what they expect to find. To enable
|
||||
search tracking:
|
||||
|
||||
@ -57,21 +55,20 @@ search tracking:
|
||||
4. Scroll down and enable __site search settings__
|
||||
5. Set the __query parameter__ to `q`.
|
||||
|
||||
_Site search tracking is not supported with Google Analytics 4 due to the much
|
||||
more complicated manual setup. If you want to set up site search tracking
|
||||
yourself, [this tutorial][4] might be a good start._
|
||||
Site search tracking is not supported with Google Analytics 4 due to the more
|
||||
complicated manual setup. If you want to set up site search tracking yourself,
|
||||
[this tutorial][tutorial] is a good start.
|
||||
|
||||
[4]: https://www.analyticsmania.com/post/track-site-search-with-google-tag-manager-and-google-analytics/
|
||||
[tutorial]: https://www.analyticsmania.com/post/track-site-search-with-google-tag-manager-and-google-analytics/
|
||||
|
||||
### Cookie consent
|
||||
|
||||
[:octicons-heart-fill-24:{ .mdx-heart } Insiders][Insiders]{ .mdx-insiders } ·
|
||||
:octicons-hash-24: Setting ·
|
||||
:octicons-milestone-24: Default: _none_ ·
|
||||
[:octicons-tag-24: insiders-2.10.0][Insiders]
|
||||
[:octicons-tag-24: insiders-2.10.0][Insiders] ·
|
||||
:octicons-milestone-24: Default: _none_
|
||||
|
||||
Material for MkDocs ships a native and extensible cookie consent form, which
|
||||
asks the user for his consent prior to setting up analytics. Add the following
|
||||
Material for MkDocs ships a native and extensible cookie consent form which
|
||||
asks the user for his consent prior to sending any analytics. Add the following
|
||||
to `mkdocs.yml`:
|
||||
|
||||
``` yaml
|
||||
@ -90,10 +87,10 @@ extra:
|
||||
|
||||
Note that both, `title` and `description`, are required. If Google Analytics was
|
||||
configured via `mkdocs.yml`, the cookie consent will automatically include a
|
||||
setting for the user to disable it. Furthermore, [custom cookies][6] can be
|
||||
setting for the user to disable it. Furthermore, [custom cookies] can be
|
||||
integrated by using the `cookies` field:
|
||||
|
||||
=== "Change cookie name"
|
||||
=== "Custom cookie name"
|
||||
|
||||
``` yaml
|
||||
extra:
|
||||
@ -104,7 +101,7 @@ integrated by using the `cookies` field:
|
||||
|
||||
1. The default name of the `analytics` cookie is `Google Analytics`.
|
||||
|
||||
=== "Add custom cookie"
|
||||
=== "Custom cookie"
|
||||
|
||||
``` yaml
|
||||
extra:
|
||||
@ -119,79 +116,87 @@ integrated by using the `cookies` field:
|
||||
|
||||
When a user first visits your site, a cookie consent form is rendered:
|
||||
|
||||
[![Cookie consent][7]][7]
|
||||
[![extra.consent enabled]][extra.consent enabled]
|
||||
|
||||
In order to comply with GDPR, users must be able to change their cookie settings
|
||||
at any time. This can be done by creating a simple link as part of any document,
|
||||
e.g. privacy policy:
|
||||
e.g. your privacy policy:
|
||||
|
||||
``` markdown
|
||||
[Change cookie settings](#__consent){ .md-button }
|
||||
```
|
||||
|
||||
[Insiders]: ../insiders/index.md
|
||||
[5]: ../insiders/index.md
|
||||
[6]: #custom-cookies
|
||||
[7]: ../assets/screenshots/consent.png
|
||||
[custom cookies]: #custom-cookies
|
||||
[extra.consent enabled]: ../assets/screenshots/consent.png
|
||||
|
||||
## Customization
|
||||
|
||||
### Custom site analytics
|
||||
|
||||
[:octicons-file-code-24: Source][3] ·
|
||||
:octicons-mortar-board-24: Difficulty: _moderate_
|
||||
|
||||
In order to integrate another analytics service provider offering a
|
||||
JavaScript-based tracking solution, you can [extend the theme][8] and add a new
|
||||
`custom.html` partial [here][9]. The name of the partial can then be used to
|
||||
configure the custom integration from `mkdocs.yml`:
|
||||
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`:
|
||||
|
||||
``` yaml
|
||||
extra:
|
||||
analytics:
|
||||
provider: custom # (1)
|
||||
key: value # (2)
|
||||
```
|
||||
=== ":octicons-file-code-16: partials/integrations/analytics/custom.html"
|
||||
|
||||
1. Of course, you can change the name to the partial to anything you like.
|
||||
2. You can add arbitrary `key` and `value` combinations to configure your custom
|
||||
integration. This is especially useful if you're sharing the custom
|
||||
integration across multiple repositories.
|
||||
``` html
|
||||
<script>
|
||||
/* Add custom analytics integration here, e.g. */
|
||||
var property = "{{ config.extra.analytics.property }}" // (1)
|
||||
|
||||
[8]: ../customization.md#extending-the-theme
|
||||
[9]: https://github.com/squidfunk/mkdocs-material/tree/master/src/partials/integrations/analytics
|
||||
/* 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>
|
||||
```
|
||||
|
||||
#### Instant loading
|
||||
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`.
|
||||
|
||||
If you're using [instant loading][10], you may use the `location$` observable,
|
||||
which will emit the current `URL` to listen for navigation events and register
|
||||
a page view event with:
|
||||
=== ":octicons-file-code-16: mkdocs.yml"
|
||||
|
||||
``` js
|
||||
location$.subscribe(function(url) {
|
||||
/* Track a page event */
|
||||
})
|
||||
```
|
||||
``` yaml
|
||||
extra:
|
||||
analytics:
|
||||
provider: custom
|
||||
property: foobar # (1)
|
||||
```
|
||||
|
||||
Note that this must be integrated with [additional JavaScript][11].
|
||||
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.
|
||||
|
||||
[10]: setting-up-navigation.md#instant-loading
|
||||
[11]: ../customization.md#additional-javascript
|
||||
[theme extension]: ../customization.md#extending-the-theme
|
||||
[instant loading]: setting-up-navigation.md#instant-loading
|
||||
|
||||
### Custom cookies
|
||||
|
||||
[:octicons-file-code-24: Source][3] ·
|
||||
:octicons-mortar-board-24: Difficulty: _moderate_
|
||||
If you've customized the [cookie consent][extra.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:
|
||||
|
||||
If you've customized the [cookie consent][12] and added a `custom` cookie, the
|
||||
user will be prompted to accept your custom cookie. Use
|
||||
[additional JavaScript][11] to check whether the user accepted it:
|
||||
=== ":octicons-file-code-16: docs/javascripts/consent.js"
|
||||
|
||||
``` js
|
||||
var consent = __md_get("__consent")
|
||||
if (consent && consent.custom) {
|
||||
/* The user accepted the cookie */
|
||||
}
|
||||
```
|
||||
``` js
|
||||
var consent = __md_get("__consent")
|
||||
if (consent && consent.custom) {
|
||||
/* The user accepted the cookie */
|
||||
}
|
||||
```
|
||||
|
||||
[12]: #cookie-consent
|
||||
=== ":octicons-file-code-16: mkdocs.yml"
|
||||
|
||||
``` yaml
|
||||
extra_javascript:
|
||||
- javascripts/consent.js
|
||||
```
|
||||
|
||||
[additional JavaScript]: ../customization.md#additional-javascript
|
||||
|
||||
@ -37,9 +37,9 @@ plugins:
|
||||
|
||||
The following options are supported:
|
||||
|
||||
`lang`{ #lang }
|
||||
`lang`{ #search-lang }
|
||||
|
||||
: :octicons-milestone-24: Default: _auto_ – This option allows
|
||||
: :octicons-milestone-24: Default: _automatically set_ – This option allows
|
||||
to include the language-specific stemmers provided by [lunr-languages][5].
|
||||
Note that Material for MkDocs will set this automatically based on the
|
||||
[site language][6], but it may be overridden, e.g. to support multiple
|
||||
@ -98,9 +98,9 @@ The following options are supported:
|
||||
JavaScript payload by around 20kb (before `gzip`) and by another 15-30kb
|
||||
per language.
|
||||
|
||||
`separator`{ #separator }
|
||||
`separator`{ #search-separator }
|
||||
|
||||
: :octicons-milestone-24: Default: _auto_ – The separator for
|
||||
: :octicons-milestone-24: Default: _automatically set_ – The separator for
|
||||
indexing and query tokenization can be customized, making it possible to
|
||||
index parts of words separated by other characters than whitespace and `-`,
|
||||
e.g. by including `.`:
|
||||
@ -111,7 +111,7 @@ The following options are supported:
|
||||
separator: '[\s\-\.]+'
|
||||
```
|
||||
|
||||
~~`prebuild_index`~~{ #prebuild-index }[^1]
|
||||
~~`prebuild_index`~~{ #search-prebuild-index }[^1]
|
||||
|
||||
: :octicons-milestone-24: Default: `false` · :octicons-archive-24: Deprecated
|
||||
– MkDocs can generate a [prebuilt index][7] of all pages during
|
||||
|
||||
@ -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][1],
|
||||
[fonts][2] and [logo][3][^1] defined in `mkdocs.yml`.
|
||||
MkDocs can generate beautiful social cards automatically, using the [colors]
|
||||
[palette.primary], [fonts][font.text] and [logo][^1] defined in `mkdocs.yml`.
|
||||
|
||||
[^1]:
|
||||
Both types of logos, images (`theme.logo`) and icons (`theme.icon.logo`)
|
||||
@ -15,69 +15,66 @@ MkDocs can generate beautiful social cards automatically, using the [colors][1],
|
||||
color used in the header (white or black), which depends on the primary
|
||||
color.
|
||||
|
||||
[1]: changing-the-colors.md#primary-color
|
||||
[2]: changing-the-fonts.md#regular-font
|
||||
[3]: changing-the-logo-and-icons.md#logo
|
||||
[palette.primary]: changing-the-colors.md#primary-color
|
||||
[font.text]: changing-the-fonts.md#regular-font
|
||||
[logo]: changing-the-logo-and-icons.md#logo
|
||||
|
||||
## Configuration
|
||||
|
||||
### Built-in social cards
|
||||
|
||||
[:octicons-heart-fill-24:{ .mdx-heart } Insiders][Insiders]{ .mdx-insiders } ·
|
||||
[:octicons-tag-24: insiders-2.12.0][Insiders] ·
|
||||
:octicons-cpu-24: Plugin ·
|
||||
:octicons-beaker-24: Experimental ·
|
||||
[:octicons-tag-24: insiders-2.12.0][Insiders]
|
||||
:octicons-beaker-24: Experimental
|
||||
|
||||
The [built-in social cards plugin][4] generates a social card image for every
|
||||
page and adds the necessary meta tags, so it's displayed on social media when
|
||||
shared. Enable it via `mkdocs.yml`:
|
||||
The built-in social cards plugin generates a social preview image for every page
|
||||
and adds the necessary meta tags, so it's displayed on social media when shared.
|
||||
Enable it via `mkdocs.yml`:
|
||||
|
||||
``` yaml
|
||||
plugins:
|
||||
- social
|
||||
```
|
||||
|
||||
For example, the page on [setting up site analytics][5] renders as:
|
||||
For example, the page on [setting up site analytics] renders as:
|
||||
|
||||
<figure markdown>
|
||||
|
||||
[![Social Cards][6]][6]
|
||||
[![Social cards preview]][Social cards preview]
|
||||
|
||||
<figcaption markdown>
|
||||
|
||||
Want to try it out? Copy the current URL and paste it into [Twitter's Card
|
||||
validator][7] to see how social cards look in action.
|
||||
validator] to see how social cards look in action.
|
||||
|
||||
</figcaption>
|
||||
</figure>
|
||||
|
||||
This is a built-in plugin, which means that no third-party plugin needs to be
|
||||
installed, as Material for MkDocs already bundles it. The following options
|
||||
are available:
|
||||
The following configuration options are available:
|
||||
|
||||
`cards_color`{ #cards-color } :material-new-box:
|
||||
`cards_color`{ #cards-color }
|
||||
|
||||
: :octicons-milestone-24: Default: [`primary
|
||||
color`][8]_ – This option specifies which colors to use for the background
|
||||
`fill` and foreground `text` when generating the social card.
|
||||
: :octicons-milestone-24: Default: [primary color][palette.primary] + header
|
||||
text color – This option specifies which colors to use for the background
|
||||
`fill` and foreground `text` when generating the social card:
|
||||
|
||||
``` yaml
|
||||
plugins:
|
||||
- social:
|
||||
cards_color:
|
||||
fill: "#0FF1CE"
|
||||
fill: "#0FF1CE" # (1)
|
||||
text: "#FFFFFF"
|
||||
```
|
||||
|
||||
Note that the values for `fill` and `text` can either be HEX color values
|
||||
(e.g. `#0FF1CE`, must be enclosed in quotes) or CSS color keywords (e.g.
|
||||
`red`, `green`, etc.).
|
||||
1. Colors can either be defined as HEX colors, or as [CSS color keywords].
|
||||
Note that HEX colors must be enclosed in quotes.
|
||||
|
||||
`cards_directory`{ #cards-directory }
|
||||
|
||||
: :octicons-milestone-24: Default: `assets/images/social` – This option
|
||||
specifies where the generated social card images will be written to. It
|
||||
should normally not be necessary to change this option.
|
||||
specifies where the generated social card images will be written to. It's
|
||||
normally not necessary to change this option:
|
||||
|
||||
``` yaml
|
||||
plugins:
|
||||
@ -86,24 +83,23 @@ are available:
|
||||
```
|
||||
|
||||
[Insiders]: ../insiders/index.md
|
||||
[4]: ../insiders/index.md
|
||||
[5]: setting-up-site-analytics.md
|
||||
[6]: ../assets/screenshots/social-cards.png
|
||||
[7]: https://cards-dev.twitter.com/validator
|
||||
[8]: changing-the-colors.md#primary-color
|
||||
[setting up site analytics]: setting-up-site-analytics.md
|
||||
[Social cards preview]: ../assets/screenshots/social-cards.png
|
||||
[Twitter's Card validator]: https://cards-dev.twitter.com/validator
|
||||
[CSS color keywords]: https://developer.mozilla.org/en-US/docs/Web/CSS/color_value#color_keywords
|
||||
|
||||
#### Caching
|
||||
#### Caching <small>recommended</small> { data-toc-label="Caching" }
|
||||
|
||||
When enabled, the [social cards plugin][9] automatically fetches the fonts you
|
||||
define in `mkdocs.yml` from Google Fonts, and uses them to render the text that
|
||||
is displayed on the social card. The font files and generated cards are both
|
||||
The [built-in social cards plugin] automatically fetches the fonts you define
|
||||
in `mkdocs.yml` from Google Fonts, and uses them to render the text that is
|
||||
displayed on the social card. The font files and generated cards are both
|
||||
written to the `.cache` directory, which is used in subsequent builds to detect
|
||||
whether the social cards need to be regenerated. You might want to:
|
||||
|
||||
1. Ignore the `.cache` directory in your project, by adding it to `.gitignore`.
|
||||
2. When building your site for publishing, use a build cache to save the
|
||||
`.cache` directory in between builds. Taking the example from the
|
||||
[publishing guide][10], add the following lines:
|
||||
[publishing guide], add the following lines:
|
||||
|
||||
``` yaml hl_lines="15-18"
|
||||
name: ci
|
||||
@ -128,27 +124,14 @@ whether the social cards need to be regenerated. You might want to:
|
||||
- run: mkdocs gh-deploy --force
|
||||
```
|
||||
|
||||
[9]: #built-in-social-cards
|
||||
[10]: ../publishing-your-site.md#with-github-actions
|
||||
[built-in social cards plugin]: #built-in-social-cards
|
||||
[publishing guide]: ../publishing-your-site.md#with-github-actions
|
||||
|
||||
## Usage
|
||||
#### Meta tags
|
||||
|
||||
If you want to adjust the title or set a custom description for the social card,
|
||||
you can use the [Metadata][11] extension, which takes precedence over the
|
||||
default values.
|
||||
|
||||
- [Changing the title][12]
|
||||
- [Changing the description][13]
|
||||
|
||||
[11]: ../reference/meta-tags.md#metadata
|
||||
[12]: ../reference/meta-tags.md#setting-the-page-title
|
||||
[13]: ../reference/meta-tags.md#setting-the-page-description
|
||||
|
||||
### Using social media meta tags
|
||||
|
||||
The [built-in social cards plugin] generates beautiful image previews for social
|
||||
media during the build and sets all necessary `meta` tags, equivalent to the
|
||||
following two customizations:
|
||||
The [built-in social cards plugin] automatically sets all necessary `meta` tags,
|
||||
equivalent to the following two customizations, which you can set manually when
|
||||
you don't want to use it:
|
||||
|
||||
=== ":material-graph: Open Graph"
|
||||
|
||||
@ -158,7 +141,7 @@ following two customizations:
|
||||
{% if page and page.meta and page.meta.title %}
|
||||
{% set title = title ~ " - " ~ page.meta.title %}
|
||||
{% elif page and page.title and not page.is_homepage %}
|
||||
{% set title = title ~ " - " ~ page.title | striptags %}
|
||||
{% set title = title ~ " - " ~ page.title %}
|
||||
{% endif %}
|
||||
<meta property="og:type" content="website" />
|
||||
<meta property="og:title" content="{{ title }}" />
|
||||
@ -179,11 +162,9 @@ following two customizations:
|
||||
{% if page and page.meta and page.meta.title %}
|
||||
{% set title = title ~ " - " ~ page.meta.title %}
|
||||
{% elif page and page.title and not page.is_homepage %}
|
||||
{% set title = title ~ " - " ~ page.title | striptags %}
|
||||
{% set title = title ~ " - " ~ page.title %}
|
||||
{% endif %}
|
||||
<meta name="twitter:card" content="summary_large_image" />
|
||||
<meta name="twitter:site" content="<username>" />
|
||||
<meta name="twitter:creator" content="<username>" />
|
||||
<meta name="twitter:title" content="{{ title }}" />
|
||||
<meta name="twitter:description" content="{{ config.site_description }}" />
|
||||
<meta name="twitter:image" content="<url>" />
|
||||
@ -192,3 +173,17 @@ following two customizations:
|
||||
|
||||
[Twitter Cards]: https://developer.twitter.com/en/docs/tweets/optimize-with-cards/overview/abouts-cards
|
||||
[built-in social cards plugin]: ../setup/setting-up-social-cards.md#built-in-social-cards
|
||||
|
||||
|
||||
## Usage
|
||||
|
||||
If you want to adjust the title or set a custom description for the social card,
|
||||
you can use the [Metadata] extension, which takes precedence over the
|
||||
default values.
|
||||
|
||||
- [Changing the title]
|
||||
- [Changing the description]
|
||||
|
||||
[Metadata]: extensions/python-markdown.md#metadata
|
||||
[Changing the title]: ../reference/meta-tags.md#setting-the-page-title
|
||||
[Changing the description]: ../reference/meta-tags.md#setting-the-page-description
|
||||
|
||||
@ -14,11 +14,11 @@ can help to discover relevant information faster.
|
||||
### Built-in tags
|
||||
|
||||
[:octicons-heart-fill-24:{ .mdx-heart } Insiders][Insiders]{ .mdx-insiders } ·
|
||||
[:octicons-tag-24: insiders-2.7.0][Insiders] ·
|
||||
:octicons-cpu-24: Plugin ·
|
||||
:octicons-beaker-24: Experimental ·
|
||||
[:octicons-tag-24: insiders-2.7.0][Insiders]
|
||||
:octicons-beaker-24: Experimental
|
||||
|
||||
The [built-in tags plugin][1] adds the ability to categorize any page with tags
|
||||
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`:
|
||||
|
||||
@ -27,15 +27,13 @@ plugins:
|
||||
- tags
|
||||
```
|
||||
|
||||
Note that no third-party plugin[^1] needs to be installed, as Material for
|
||||
MkDocs provides its own implementation to allow for a meaningful integration.
|
||||
The following options are available:
|
||||
The following configuration options are available:
|
||||
|
||||
`tags_file`{ #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
|
||||
index][3] for more information. If this option is specified, tags will
|
||||
index] for more information. If this option is specified, tags will
|
||||
become clickable, pointing to the corresponding section in the tags index:
|
||||
|
||||
``` yaml
|
||||
@ -49,29 +47,18 @@ The following options are available:
|
||||
option is not specified, tags are still rendered and searchable,
|
||||
but without a tags index.
|
||||
|
||||
[^1]:
|
||||
The built-in tags plugin has no affiliation with [mkdocs-plugin-tags][2],
|
||||
another option to add tag support to MkDocs, which has several caveats:
|
||||
it requires a `title` set in the front matter for every page for which tags
|
||||
should be added, doesn't support all syntactic flavors of front matter,
|
||||
doesn't integrate tags in search and doesn't render tags on pages without
|
||||
additional effort. The built-in tags plugin supports all of these
|
||||
features out-of-the-box.
|
||||
|
||||
[Insiders]: ../insiders/index.md
|
||||
[1]: ../insiders/index.md
|
||||
[2]: https://github.com/jldiaz/mkdocs-plugin-tags
|
||||
[3]: #adding-a-tags-index
|
||||
[adding a tags index]: #adding-a-tags-index
|
||||
|
||||
## Usage
|
||||
|
||||
### Adding tags
|
||||
|
||||
If both, the [built-in tags plugin][4] and [Metadata][5] extension are enabled,
|
||||
tags can be added for any page as part of the front matter, e.g. to add the tags
|
||||
`insiders` and `brand new` to this page, add:
|
||||
When both, the [built-in tags plugin] and [Metadata] extension are enabled,
|
||||
tags can be added for a document with custom front matter. Add the following
|
||||
lines at the top of a Markdown file:
|
||||
|
||||
``` yaml
|
||||
``` bash
|
||||
---
|
||||
tags:
|
||||
- insiders
|
||||
@ -87,22 +74,22 @@ following screenshots:
|
||||
|
||||
=== "Tags"
|
||||
|
||||
[![Tags][6]][6]
|
||||
[![Tags preview]][Tags preview]
|
||||
|
||||
=== "Tag search"
|
||||
|
||||
[![Tag search][7]][7]
|
||||
[![Tag search preview]][Tag search preview]
|
||||
|
||||
[4]: #built-in-tags
|
||||
[5]: ../../reference/meta-tags/#metadata
|
||||
[6]: ../assets/screenshots/tags.png
|
||||
[7]: ../assets/screenshots/tags-search.png
|
||||
[built-in tags plugin]: #built-in-tags
|
||||
[Metadata]: extensions/python-markdown.md#metadata
|
||||
[Tags preview]: ../assets/screenshots/tags.png
|
||||
[Tag search preview]: ../assets/screenshots/tags-search.png
|
||||
|
||||
### Adding a tags index
|
||||
|
||||
The [built-in tags plugin][4] allows to define a file to render a [tags
|
||||
index][8], which can be any page that is part of the `nav` section. To add a
|
||||
tags index, create a page, e.g. `tags.md`:
|
||||
The [built-in tags plugin] allows to define a file to render a [tags index]
|
||||
[tags.tags_file], 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
|
||||
@ -118,14 +105,14 @@ arbitrary content before and after the marker:
|
||||
|
||||
[![Tags index][9]][9]
|
||||
|
||||
[8]: #tags_file
|
||||
[tags.tags_file]: #tags-file
|
||||
[9]: ../assets/screenshots/tags-index.png
|
||||
|
||||
### Hiding the tags
|
||||
|
||||
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 by using the
|
||||
[Metadata][10] extension:
|
||||
[Metadata] extension:
|
||||
|
||||
``` bash
|
||||
---
|
||||
@ -136,5 +123,3 @@ hide:
|
||||
# Document title
|
||||
...
|
||||
```
|
||||
|
||||
[10]: ../../reference/meta-tags/#metadata
|
||||
|
||||
@ -32,7 +32,7 @@ extra:
|
||||
|
||||
For each entry, the following settings are available:
|
||||
|
||||
`icon`{ #icon }
|
||||
`icon`{ #social-icon }
|
||||
|
||||
: :octicons-milestone-24: Default: _none_ · :octicons-alert-24: Required –
|
||||
This field must point to a valid icon path referencing [any icon bundled
|
||||
@ -53,7 +53,7 @@ For each entry, the following settings are available:
|
||||
[1]: https://github.com/squidfunk/mkdocs-material/blob/master/src/partials/social.html
|
||||
[2]: https://github.com/squidfunk/mkdocs-material/tree/master/material/.icons
|
||||
|
||||
`link`{ #link }
|
||||
`link`{ #social-link }
|
||||
|
||||
: :octicons-milestone-24: Default: _none_ · :octicons-alert-24: Required –
|
||||
This field must contain a valid relative or absolute URL including the URI
|
||||
@ -77,7 +77,7 @@ For each entry, the following settings are available:
|
||||
link: mailto:<email-address>
|
||||
```
|
||||
|
||||
`name`{ #name }
|
||||
`name`{ #social-name }
|
||||
|
||||
: :octicons-milestone-24: Default: _domain name from_ `link`_, if available_ –
|
||||
This field is used as the link's `title` attribute and can be set to a
|
||||
|
||||
@ -6,21 +6,21 @@ template: overrides/main.html
|
||||
|
||||
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][1]. When deploying a new version, older versions of your
|
||||
to MkDocs, i.e. [mike]. When deploying a new version, older versions of your
|
||||
documentation remain untouched.
|
||||
|
||||
[1]: https://github.com/jimporter/mike
|
||||
[mike]: https://github.com/jimporter/mike
|
||||
|
||||
## Configuration
|
||||
|
||||
### Versioning
|
||||
|
||||
[:octicons-file-code-24: Source][2] ·
|
||||
[:octicons-package-24: Utility][1]
|
||||
[:octicons-tag-24: 7.0.0][version support] ·
|
||||
[:octicons-package-24: Utility][mike]
|
||||
|
||||
[mike][1] 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`:
|
||||
[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:
|
||||
@ -28,22 +28,21 @@ extra:
|
||||
provider: mike
|
||||
```
|
||||
|
||||
This will render a version selector in the header next to the title of your
|
||||
project:
|
||||
This renders a version selector in the header:
|
||||
|
||||
<figure markdown>
|
||||
|
||||
[![Version selection][3]][3]
|
||||
[![Version selector preview]][Version selector preview]
|
||||
|
||||
<figcaption markdown>
|
||||
|
||||
A demo is worth a thousand words — check it out at
|
||||
[squidfunk.github.io/mkdocs-material-example-versioning][4]
|
||||
Check out the versioning example to see it in action –
|
||||
[squidfunk.github.io/mkdocs-material-example-versioning][version example]
|
||||
|
||||
</figcaption>
|
||||
</figure>
|
||||
|
||||
!!! quote "[Why use mike?][5]"
|
||||
!!! 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
|
||||
@ -56,15 +55,10 @@ A demo is worth a thousand words — check it out at
|
||||
to particularly notable versions. This makes it easy to make permalinks to
|
||||
whatever version of the documentation you want to direct people to.
|
||||
|
||||
_Note that you don't need to run_ `mike install-extras` _as noted in the
|
||||
[official documentation][6], as [mike][1] is now natively integrated with
|
||||
Material for MkDocs._
|
||||
|
||||
[2]: https://github.com/squidfunk/mkdocs-material/blob/master/src/partials/header.html
|
||||
[3]: ../assets/screenshots/versioning.png
|
||||
[4]: https://squidfunk.github.io/mkdocs-material-example-versioning/
|
||||
[5]: https://github.com/jimporter/mike#why-use-mike
|
||||
[6]: https://github.com/jimporter/mike#usage
|
||||
[version support]: https://github.com/squidfunk/mkdocs-material/releases/tag/5.2.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
|
||||
|
||||
### Version warning
|
||||
|
||||
|
||||
Loading…
Reference in New Issue
Block a user