Updated documentation

This commit is contained in:
squidfunk 2021-10-10 21:04:22 +02:00
parent a0ff73932f
commit 6acd637cb8
11 changed files with 97 additions and 115 deletions

View File

@ -152,7 +152,7 @@ directory:
MkDocs will now use the new partial when rendering the theme. This can be done
with any file.
### Overriding blocks <small>recommended</small> { data-toc-label="Overriding blocks" }
### Overriding blocks <small>recommended</small> { #overriding-blocks data-toc-label="Overriding blocks" }
Besides overriding partials, it's also possible to override (and extend)
_template blocks_, which are defined inside the templates and wrap specific
@ -216,7 +216,7 @@ with Material for MkDocs_ hint in the footer, add the following line to
{% extends "base.html" %}
{% set extracopyright %}
<!-- Add your additional information here -->
<!-- Add additional copyright information here -->
{% endset %}
```

View File

@ -124,7 +124,7 @@ templates can be shared among multiple pages:
{% endblock %}
```
[5]: customization.md#overriding-blocks-recommended
[5]: customization.md#overriding-blocks
[6]: customization.md#extending-the-theme
## Docker image

View File

@ -19,7 +19,7 @@ In case you're running into problems, consult the [troubleshooting][4] section.
## Installation
### with pip <small>recommended</small> { data-toc-label="with pip" }
### with pip <small>recommended</small> { #with-pip data-toc-label="with pip" }
Material for MkDocs can be installed with `pip`:

View File

@ -105,7 +105,7 @@ extra:
#### on all pages
In order to add custom `meta` tags to your document, you can [extend the theme
][theme extension] and [override the `extrahead` block][override block],
][theme extension] and [override the `extrahead` block][overriding blocks],
e.g. to add indexing policies for search engines via the `robots` property:
``` html
@ -116,7 +116,7 @@ e.g. to add indexing policies for search engines via the `robots` property:
{% endblock %}
```
[override block]: ../customization.md#overriding-blocks-recommended
[overriding blocks]: ../customization.md#overriding-blocks
#### on a single page

View File

@ -4,47 +4,43 @@ template: overrides/main.html
# Adding a comment system
Material for MkDocs is natively integrated with [Disqus][1], a comment system
that provides a wide range of features like social integrations, user profiles,
as well as spam and moderation tools. Of course, other comment systems can be
Material for MkDocs is natively integrated with [Disqus], a comment system that
provides a wide range of features like social integrations, user profiles, as
well as spam and moderation tools. Of course, other comment systems can be
integrated, too.
[1]: https://disqus.com/
[Disqus]: https://disqus.com/
## Configuration
### Disqus
[:octicons-file-code-24: Source][2] ·
[:octicons-tag-24: 1.1.0][Disqus support] ·
:octicons-milestone-24: Default: _none_
First, ensure you've set [`site_url`][3] in `mkdocs.yml`. Then, to integrate
Material for MkDocs with [Disqus][1], create an account and a site giving you a
[shortname][4], and add it to `mkdocs.yml`:
First, ensure you've set [`site_url`][site_url] in `mkdocs.yml`. Then, to
integrate Material for MkDocs with [Disqus], create an account and a site
giving you a [shortname], and add it to `mkdocs.yml`:
``` yaml
extra:
disqus: <shortname>
```
This will insert a comment system on _every page, except the index page_.
This will insert a comment system on every page, except the index page.
[2]: https://github.com/squidfunk/mkdocs-material/blob/master/src/partials/integrations/disqus.html
[3]: https://www.mkdocs.org/user-guide/configuration/#site_url
[4]: https://help.disqus.com/en/articles/1717111-what-s-a-shortname
[Disqus support]: https://github.com/squidfunk/mkdocs-material/releases/tag/1.1.0
[site_url]: https://www.mkdocs.org/user-guide/configuration/#site_url
[shortname]: https://help.disqus.com/en/articles/1717111-what-s-a-shortname
## Customization
### Selective integration
[:octicons-file-code-24: Source][2] ·
:octicons-note-24: Metadata ·
:octicons-mortar-board-24: Difficulty: _easy_
When [Metadata] is enabled, Disqus can be enabled or disabled for a document
with custom front matter. Add the following lines at the top of a Markdown file:
If the [Metadata][5] extension is enabled, you can disable or enable Disqus for
specific pages by adding the following to the front matter of a page:
=== "Enable Disqus"
=== ":octicons-check-circle-fill-16: Enabled"
``` bash
---
@ -55,7 +51,7 @@ specific pages by adding the following to the front matter of a page:
...
```
=== "Disable Disqus"
=== ":octicons-skip-16: Disabled"
``` bash
---
@ -66,15 +62,13 @@ specific pages by adding the following to the front matter of a page:
...
```
[5]: ../../reference/meta-tags/#metadata
[Metadata]: extensions/python-markdown.md#metadata
### Other comment systems
[:octicons-file-code-24: Source][6] ·
:octicons-mortar-board-24: Difficulty: _easy_
In order to integrate another JavaScript-based comment system provider, you can
[extend the theme][7] and [override the `disqus` block][8]:
[extend the theme], create a new `main.html` in `overrides` and [override the
`disqus` block][overriding blocks]:
``` html
{% extends "base.html" %}
@ -84,6 +78,5 @@ In order to integrate another JavaScript-based comment system provider, you can
{% endblock %}
```
[6]: https://github.com/squidfunk/mkdocs-material/blob/master/src/base.html
[7]: ../customization.md#extending-the-theme
[8]: ../customization.md#overriding-blocks-recommended
[extend the theme]: ../customization.md#extending-the-theme
[overriding blocks]: ../customization.md#overriding-blocks

View File

@ -20,7 +20,7 @@ and extendable [cookie consent][extra.consent].
: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 property prefix, add the
out Universal Analytics. Depending on the given property prefix, add the
following lines to `mkdocs.yml`:
=== ":material-google-analytics: Google Analytics 4"

View File

@ -150,7 +150,7 @@ Use them at your own risk._
:octicons-beaker-24: Experimental ·
[:octicons-tag-24: 7.2.0][Search suggestions support]
When _search suggestions_ are enabled, the search will display the likeliest
When search suggestions are enabled, the search will display the likeliest
completion for the last word, saving the user many key strokes by accepting the
suggestion with the ++arrow-right++ key.
@ -177,7 +177,7 @@ Searching for [:octicons-search-24: search su][9] yields ^^search suggestions^^
:octicons-beaker-24: Experimental ·
[:octicons-tag-24: 7.2.0][Search highlighting support]
When _search highlighting_ is enabled and a user clicks on a search result,
When search highlighting is enabled and a user clicks on a search result,
Material for MkDocs will highlight all occurrences after following the link.
Add the following lines to `mkdocs.yml`:
@ -202,7 +202,7 @@ Searching for [:octicons-search-24: code blocks][12] yields:
:octicons-beaker-24: Experimental ·
[:octicons-tag-24: 7.2.0][Search highlighting support]
When _search sharing_ is activated, a :material-share-variant: share button is
When search sharing is activated, a :material-share-variant: share button is
rendered next to the reset button, which allows to deep link to the current
search query and result. Add the following lines to `mkdocs.yml`:
@ -439,7 +439,7 @@ and must return the processed query string to be submitted to the search index.
[23]: https://github.com/squidfunk/mkdocs-material/blob/master/src/assets/javascripts/integrations/search/transform/index.ts
[24]: ../customization.md#extending-the-theme
[25]: ../customization.md#overriding-blocks-recommended
[25]: ../customization.md#overriding-blocks
### Custom search

View File

@ -30,7 +30,12 @@ MkDocs can generate beautiful social cards automatically, using the [colors]
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`:
First, ensure you've set [`site_url`][site_url] in `mkdocs.yml`.[^2] Then, add
the following lines to `mkdocs.yml` to enable the plugin:
[^2]:
When using this plugin, the [`site_url`][site_url] setting is mandatory, as
social preview images don't work with relative URLs.
``` yaml
plugins:
@ -83,12 +88,14 @@ The following configuration options are available:
```
[Insiders]: ../insiders/index.md
[site_url]: https://www.mkdocs.org/user-guide/configuration/#site_url
[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
[meta tags]: #meta-tags
[CSS color keywords]: https://developer.mozilla.org/en-US/docs/Web/CSS/color_value#color_keywords
#### Caching <small>recommended</small> { data-toc-label="Caching" }
#### Caching <small>recommended</small> { #caching data-toc-label="Caching" }
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

View File

@ -15,9 +15,8 @@ configured via `mkdocs.yml`.
### Social links
:octicons-hash-24: Setting ·
:octicons-milestone-24: Default: _none_ ·
[:octicons-tag-24: 1.0.0][Social links 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
footer of your project documentation. Add a list of social links in `mkdocs.yml`
@ -36,7 +35,8 @@ For each entry, the following settings are available:
: :octicons-milestone-24: Default: _none_ · :octicons-alert-24: Required
This field must point to a valid icon path referencing [any icon bundled
with the theme][2], or the build will not succeed. Some popular choices:
with the theme][custom icons], or the build will not succeed. Some popular
choices:
* :fontawesome-brands-behance: `fontawesome/brands/behance`
* :fontawesome-brands-docker: `fontawesome/brands/docker`
@ -50,8 +50,7 @@ For each entry, the following settings are available:
* :fontawesome-brands-twitter: `fontawesome/brands/twitter`
[Social links support]: https://github.com/squidfunk/mkdocs-material/releases/tag/1.0.0
[1]: https://github.com/squidfunk/mkdocs-material/blob/master/src/partials/social.html
[2]: https://github.com/squidfunk/mkdocs-material/tree/master/material/.icons
[custom icons]: https://github.com/squidfunk/mkdocs-material/tree/master/material/.icons
`link`{ #social-link }
@ -59,7 +58,7 @@ For each entry, the following settings are available:
This field must contain a valid relative or absolute URL including the URI
scheme. All URI schemes are supported, including `mailto` and `bitcoin`:
=== "Twitter"
=== ":fontawesome-brands-twitter: Twitter"
``` yaml
extra:
@ -68,7 +67,7 @@ For each entry, the following settings are available:
link: https://twitter.com/squidfunk
```
=== "Email address"
=== ":octicons-mail-16: Email"
``` yaml
extra:
@ -93,9 +92,8 @@ For each entry, the following settings are available:
### Copyright notice
:octicons-hash-24: Setting ·
:octicons-milestone-24: Default: _none_ ·
[:octicons-tag-24: 0.1.0][Copyright notice support]
[:octicons-tag-24: 0.1.0][Copyright notice support] ·
:octicons-milestone-24: Default: _none_
A custom copyright banner can be rendered as part of the footer, which is
displayed next to the social links. It can be defined as part of `mkdocs.yml`:
@ -109,9 +107,8 @@ copyright: Copyright &copy; 2016 - 2020 Martin Donath
### Generator notice
:octicons-hash-24: Setting ·
:octicons-milestone-24: Default: `true` ·
[:octicons-tag-24: 7.3.0][Generator notice support]
[:octicons-tag-24: 7.3.0][Generator notice support] ·
:octicons-milestone-24: Default: `true`
The footer displays a _Made with Material for MkDocs_ notice to denote how
the site was generated. The notice can be removed with the following setting
@ -127,25 +124,24 @@ extra:
The subtle __Made with Material for MkDocs__ hint in the footer is one of
the reasons why this project is so popular, as it tells the user how the
site is generated, helping new users to discover this project. Before
removing it, please consider that you're enjoying the benefits of
@squidfunk's work for free, as this project is Open Source and has a
permissive license. Thousands of hours went into this project, most of them
without any financial return. Thus, if you remove this notice, please
consider [sponsoring][4] the project. __Thank you__
:octicons-heart-fill-24:{ .mdx-heart .mdx-insiders }
removing please consider that you're enjoying the benefits of @squidfunk's
work for free, as this project is Open Source and has a permissive license.
Thousands of hours went into this project, most of them
without any financial return.
Thus, if you remove this notice, please consider [sponsoring][Insiders] the
project. __Thank you__ :octicons-heart-fill-24:{ .mdx-heart .mdx-insiders }
[Generator notice support]: https://github.com/squidfunk/mkdocs-material/releases/tag/7.3.0
[Insiders]: ../insiders/index.md
## Customization
### Custom icons
[:octicons-file-code-24: Source][2] ·
:octicons-mortar-board-24: Difficulty: _easy_
The social links feature uses the standard [icon integration][5] of Material for
The social links feature uses the standard [icon integration] of Material for
MkDocs. If you want to use custom icons, follow the guide explaining how to
add [additional icons][6].
add [additional icons].
[5]: changing-the-logo-and-icons.md#icons
[6]: changing-the-logo-and-icons.md#additional-icons
[icon integration]: extensions/python-markdown-extensions.md#emoji
[additional icons]: changing-the-logo-and-icons.md#additional-icons

View File

@ -6,20 +6,20 @@ template: overrides/main.html
Material for MkDocs' header can be customized to show an announcement bar that
disappears upon scrolling, and provides some options for further configuration.
It also includes the [search bar][1] and a place to display your project's
[git repository][2], as explained in those dedicated guides.
It also includes the [search bar] and a place to display your project's
[git repository], as explained in those dedicated guides.
[1]: setting-up-site-search.md
[2]: adding-a-git-repository.md
[search bar]: setting-up-site-search.md
[git repository]: adding-a-git-repository.md
## Configuration
### Automatic hiding
:octicons-unlock-24: Feature flag ·
[:octicons-tag-24: 6.2.0][Automatic hiding support]
[:octicons-tag-24: 6.2.0][Automatic hiding support] ·
:octicons-unlock-24: Feature flag
When _autohiding_ is enabled, the header is automatically hidden when the
When autohiding is enabled, the header is automatically hidden when the
user scrolls past a certain threshold, leaving more space for content. Add the
following lines to `mkdocs.yml`:
@ -31,28 +31,25 @@ theme:
[Automatic hiding support]: https://github.com/squidfunk/mkdocs-material/releases/tag/6.2.0
## Customization
### Announcement bar
:octicons-file-symlink-file-24: Customization ·
[:octicons-tag-24: 5.0.0][Announcement bar support]
[:octicons-tag-24: 5.0.0][Announcement bar support] ·
:octicons-file-symlink-file-24: Customization
Material for MkDocs includes an announcement bar, which is the perfect place to
display project news or other important information to the user. When the user
scrolls past the header, the bar will automatically disappear. In order to add
an announcement bar, [extend the theme][4] and [override the `announce`
block][5], which is empty by default:
an announcement bar, [extend the theme] and [override the `announce`
block][overriding blocks], which is empty by default:
``` html
{% extends "base.html" %}
{% block announce %}
<!-- Add your announcement here, including arbitrary HTML -->
<!-- Add announcement here, including arbitrary HTML -->
{% endblock %}
```
[Announcement bar support]: https://github.com/squidfunk/mkdocs-material/releases/tag/6.2.0
[4]: ../customization.md#extending-the-theme
[5]: ../customization.md#overriding-blocks-recommended
[extend the theme]: ../customization.md#extending-the-theme
[overriding blocks]: ../customization.md#overriding-blocks

View File

@ -63,12 +63,12 @@ Check out the versioning example to see it in action
### Version warning
[:octicons-heart-fill-24:{ .mdx-heart } Insiders][Insiders]{ .mdx-insiders } ·
:octicons-file-symlink-file-24: Customization ·
[:octicons-tag-24: insiders-2.5.0][Insiders]
[:octicons-tag-24: insiders-2.5.0][Insiders] ·
:octicons-file-symlink-file-24: Customization
If you're using versioning, you might want to display a warning when the user
visits any other version than the latest version. Using [theme extension][8],
you can [define the `outdated` block][9]:
visits any other version than the latest version. Using [theme extension],
you can [override the `outdated` block][overriding blocks]:
``` html
{% extends "base.html" %}
@ -89,11 +89,11 @@ you can [define the `outdated` block][9]:
This will render a version warning above the header:
[![Version warning][10]][10]
[![Version warning preview]][Version warning preview]
By default, the default version is identified by the `latest` alias. If you
wish to set another alias as the latest version, e.g. `stable`, add the
following to `mkdocs.yml`:
The default version is identified by the `latest` alias. If you wish to set
another alias as the latest version, e.g. `stable`, add the following lines
to `mkdocs.yml`:
``` yaml
extra:
@ -101,14 +101,13 @@ extra:
default: stable
```
Make sure that this matches the [default version][11].
Make sure that this matches the [default version].
[Insiders]: ../insiders/index.md
[7]: ../insiders/index.md
[8]: ../customization.md#extending-the-theme
[9]: ../customization.md#overriding-blocks-recommended
[10]: ../assets/screenshots/version-warning.png
[11]: #setting-a-default-version
[theme extension]: ../customization.md#extending-the-theme
[overriding blocks]: ../customization.md#overriding-blocks
[Version warning preview]: ../assets/screenshots/version-warning.png
[default version]: #setting-a-default-version
### Stay on page
@ -135,21 +134,11 @@ the current page:
docs.example.com/0.1/bar/ -> docs.example.com/0.2/
```
<figure markdown>
<figcaption markdown>
A demo is worth a thousand words — check it out at
[squidfunk.github.io/mkdocs-material-example-versioning][4]
</figcaption>
</figure>
## Usage
While this section outlines the basic workflow for publishing new versions,
it's best to check out the [official documentation][6] to make yourself familar
with [mike][1].
it's best to check out [mike's documentation][mike] to make yourself familar
with its mechanics.
### Publishing a new version
@ -169,15 +158,15 @@ e.g.:
### Setting a default version
When starting with [mike][1], a good idea is to set an alias as a default
version, e.g. `latest`, and when publishing a new version, always update the
alias to point to the latest version:
When starting with [mike], a good idea is to set an alias as a default version,
e.g. `latest`, and when publishing a new version, always update the alias to
point to the latest version:
```
mike set-default --push latest
```
When publishing a new version, [mike][1] will create a redirect in the root of
When publishing a new version, [mike] will create a redirect in the root of
your project documentation to the version associated with the alias:
_docs.example.com_ :octicons-arrow-right-24: _docs.example.com/0.1_