diff --git a/docs/customization.md b/docs/customization.md
index 90a6b598b..f015f307b 100644
--- a/docs/customization.md
+++ b/docs/customization.md
@@ -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 recommended { data-toc-label="Overriding blocks" }
+### Overriding blocks recommended { #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 %}
-
+
{% endset %}
```
diff --git a/docs/deprecations.md b/docs/deprecations.md
index 5fdeb3304..6b7a3d767 100644
--- a/docs/deprecations.md
+++ b/docs/deprecations.md
@@ -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
diff --git a/docs/getting-started.md b/docs/getting-started.md
index 8ca7810be..237936081 100644
--- a/docs/getting-started.md
+++ b/docs/getting-started.md
@@ -19,7 +19,7 @@ In case you're running into problems, consult the [troubleshooting][4] section.
## Installation
-### with pip recommended { data-toc-label="with pip" }
+### with pip recommended { #with-pip data-toc-label="with pip" }
Material for MkDocs can be installed with `pip`:
diff --git a/docs/reference/meta-tags.md b/docs/reference/meta-tags.md
index 9186e0dd8..46292adfe 100644
--- a/docs/reference/meta-tags.md
+++ b/docs/reference/meta-tags.md
@@ -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
diff --git a/docs/setup/adding-a-comment-system.md b/docs/setup/adding-a-comment-system.md
index 2f41ec4e5..d8af9efcd 100644
--- a/docs/setup/adding-a-comment-system.md
+++ b/docs/setup/adding-a-comment-system.md
@@ -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:
```
-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
diff --git a/docs/setup/setting-up-site-analytics.md b/docs/setup/setting-up-site-analytics.md
index d451face2..0d1812b65 100644
--- a/docs/setup/setting-up-site-analytics.md
+++ b/docs/setup/setting-up-site-analytics.md
@@ -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"
diff --git a/docs/setup/setting-up-site-search.md b/docs/setup/setting-up-site-search.md
index 5c9210deb..d8b1ebf00 100644
--- a/docs/setup/setting-up-site-search.md
+++ b/docs/setup/setting-up-site-search.md
@@ -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
diff --git a/docs/setup/setting-up-social-cards.md b/docs/setup/setting-up-social-cards.md
index f19b4838a..14427e41e 100644
--- a/docs/setup/setting-up-social-cards.md
+++ b/docs/setup/setting-up-social-cards.md
@@ -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 recommended { data-toc-label="Caching" }
+#### Caching recommended { #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
diff --git a/docs/setup/setting-up-the-footer.md b/docs/setup/setting-up-the-footer.md
index 90d14fe63..649b0065b 100644
--- a/docs/setup/setting-up-the-footer.md
+++ b/docs/setup/setting-up-the-footer.md
@@ -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 © 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
diff --git a/docs/setup/setting-up-the-header.md b/docs/setup/setting-up-the-header.md
index 19832ff09..c9d741fea 100644
--- a/docs/setup/setting-up-the-header.md
+++ b/docs/setup/setting-up-the-header.md
@@ -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 %}
-
+
{% 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
diff --git a/docs/setup/setting-up-versioning.md b/docs/setup/setting-up-versioning.md
index d15129eb8..37c07c1a4 100644
--- a/docs/setup/setting-up-versioning.md
+++ b/docs/setup/setting-up-versioning.md
@@ -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/
```
-
-
-
-A demo is worth a thousand words — check it out at
-[squidfunk.github.io/mkdocs-material-example-versioning][4]
-
-
-
-
-
## 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_