Cool_Tools/mkdocs-material
1
0
Fork 0
mirror of https://github.com/squidfunk/mkdocs-material.git synced 2024-11-24 07:30:12 +01:00
Code Issues Releases Wiki Activity

Merge pull request #3093 from squidfunk/docs/restructure-docs

Browse Source 
Restructure documentation
This commit is contained in:
Martin Donath 2021-10-10 22:35:39 +02:00 committed by GitHub
commit 77c62c9b55
No known key found for this signature in database
GPG Key ID: 4AEE18F83AFDEB23
62 changed files with 3114 additions and 2717 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

2
CHANGELOG
View File

@ -138,7 +138,7 @@ mkdocs-material-7.1.11+insiders-2.11.1 (2021-07-20)
mkdocs-material-7.1.11+insiders-2.11.0 (2021-07-18)
* Improved Mermaid.js intergration, now stable
* Improved Mermaid.js integration, now stable
* Added support for sequence diagrams
* Added support for entity relationship diagrams
* Added support for cookie consent configuration

2
docs/blog/2021/excluding-content-from-search.md
View File

@ -14,7 +14,7 @@ __The latest Insiders release brings three new simple ways to exclude
dedicated parts of a document from the search index, allowing for more
fine-grained control.__
<aside class="mdx-author" markdown="1">
<aside class="mdx-author" markdown>
![@squidfunk][1]
<span>__Martin Donath__ · @squidfunk</span>

10
docs/blog/2021/search-better-faster-smaller.md
View File

@ -14,7 +14,7 @@ __This is the story of how we managed to completely rebuild client-side search,
delivering a significantly better user experience while making it faster and
smaller at the same time.__
<aside class="mdx-author" markdown="1">
<aside class="mdx-author" markdown>
![@squidfunk][1]
<span>__Martin Donath__ · @squidfunk</span>
@ -230,11 +230,11 @@ search previews appear not to include any occurrence of any of the search
terms. This was due to the fact that search previews were [truncated after a
maximum of 320 characters][15], as can be seen here:
<figure markdown="1">
<figure markdown>
![Search previews][16]
<figcaption markdown="1">
<figcaption markdown>
The first two results look like they're not relevant, as they don't seem to
include the query string the user just searched for. Yet, they are.
@ -499,7 +499,7 @@ digit `\d`, which leaves version numbers discoverable. Searching for
[:octicons-search-24: 7.2.6][28] brings up the [7.2.6][29] release notes.
[28]: ?q=7.2.6
[29]: ../../changelog.md#726-_-september-1-2021
[29]: ../../changelog/index.md#726-_-september-1-2021
#### HTML/XML tags
@ -578,7 +578,7 @@ itself, and one with a very massive corpus of Markdown files with more than
800,000 words – a size most documentation projects will likely never
reach:
<figure markdown="1">
<figure markdown>
| | Before | Now | Relative |
| ----------------------- | -------: | -------------: | -----------: |

0
docs/changelog.md → docs/changelog/index.md
View File

94
docs/creating-your-site.md
View File

@ -4,7 +4,7 @@ template: overrides/main.html
# Creating your site
After you've [installed][1] Material for MkDocs, you can bootstrap your project
After you've [installed] Material for MkDocs, you can bootstrap your project
documentation using the `mkdocs` executable. Go to the directory where you want
your project to be located and enter:
@ -35,14 +35,14 @@ This will create the following structure:
└─ mkdocs.yml
```
[1]: getting-started.md
[installed]: getting-started.md
## Configuration
### Minimal configuration
Simply add the following lines to `mkdocs.yml` to enable the theme. Note that
since there are several [installation methods][2], configuration might be
since there are several [installation methods], minimal configuration might be
slightly different:
=== "pip, docker"
@ -77,53 +77,53 @@ slightly different:
logo: logo
```
_If you cloned Material for MkDocs from GitHub, you must list all of the themes'
defaults, because_ [`mkdocs_theme.yml`][3] _is not loaded automatically as
[described in the official documentation][4]._
When you clone from GitHub, you must list all of the themes' defaults
explicitly, because [`mkdocs_theme.yml`][mkdocs_theme.yml] is not
loaded automatically as described in the [custom theme guide].
[2]: getting-started.md#installation
[3]: https://github.com/squidfunk/mkdocs-material/blob/master/src/mkdocs_theme.yml
[4]: https://www.mkdocs.org/user-guide/custom-themes/#creating-a-custom-theme
[installation methods]: getting-started.md#installation
[mkdocs_theme.yml]: https://github.com/squidfunk/mkdocs-material/blob/master/src/mkdocs_theme.yml
[custom theme guide]: https://www.mkdocs.org/user-guide/custom-themes/#creating-a-custom-theme
### Advanced configuration
Material for MkDocs comes with many configuration options. The _setup_ section
Material for MkDocs comes with many configuration options. The setup section
explains in great detail how to configure and customize colors, fonts, icons
and much more:
<div class="mdx-columns" markdown="1">
<div class="mdx-columns" markdown>
- [Changing the colors][5]
- [Changing the fonts][6]
- [Changing the language][7]
- [Changing the logo and icons][8]
- [Setting up navigation][9]
- [Setting up site search][10]
- [Setting up site analytics][11]
- [Setting up social cards][12]
- [Setting up tags][13]
- [Setting up versioning][14]
- [Setting up the header][15]
- [Setting up the footer][16]
- [Adding a git repository][17]
- [Adding a comment system][18]
- [Changing the colors]
- [Changing the fonts]
- [Changing the language]
- [Changing the logo and icons]
- [Setting up navigation]
- [Setting up site search]
- [Setting up site analytics]
- [Setting up social cards]
- [Setting up tags]
- [Setting up versioning]
- [Setting up the header]
- [Setting up the footer]
- [Adding a git repository]
- [Adding a comment system]
</div>
[5]: setup/changing-the-colors.md
[6]: setup/changing-the-fonts.md
[7]: setup/changing-the-language.md
[8]: setup/changing-the-logo-and-icons.md
[9]: setup/setting-up-navigation.md
[10]: setup/setting-up-site-search.md
[11]: setup/setting-up-site-analytics.md
[12]: setup/setting-up-social-cards.md
[13]: setup/setting-up-tags.md
[14]: setup/setting-up-versioning.md
[15]: setup/setting-up-the-header.md
[16]: setup/setting-up-the-footer.md
[17]: setup/adding-a-git-repository.md
[18]: setup/adding-a-comment-system.md
[Changing the colors]: setup/changing-the-colors.md
[Changing the fonts]: setup/changing-the-fonts.md
[Changing the language]: setup/changing-the-language.md
[Changing the logo and icons]: setup/changing-the-logo-and-icons.md
[Setting up navigation]: setup/setting-up-navigation.md
[Setting up site search]: setup/setting-up-site-search.md
[Setting up site analytics]: setup/setting-up-site-analytics.md
[Setting up social cards]: setup/setting-up-social-cards.md
[Setting up tags]: setup/setting-up-tags.md
[Setting up versioning]: setup/setting-up-versioning.md
[Setting up the header]: setup/setting-up-the-header.md
[Setting up the footer]: setup/setting-up-the-footer.md
[Adding a git repository]: setup/adding-a-git-repository.md
[Adding a comment system]: setup/adding-a-comment-system.md
## Previewing as you write
@ -149,12 +149,12 @@ If you're running Material for MkDocs from within Docker, use:
docker run --rm -it -p 8000:8000 -v "%cd%":/docs squidfunk/mkdocs-material
```
Point your browser to [localhost:8000][19] and you should see:
Point your browser to [localhost:8000][live preview] and you should see:
[![Creating your site][20]][20]
[![Creating your site]][Creating your site]
[19]: http://localhost:8000
[20]: assets/screenshots/creating-your-site.png
[live preview]: http://localhost:8000
[Creating your site]: assets/screenshots/creating-your-site.png
## Building your site
@ -167,8 +167,8 @@ mkdocs build
The contents of this directory make up your project documentation. There's no
need for operating a database or server, as it is completely self-contained.
The site can be hosted on [GitHub Pages][21], [GitLab Pages][22], a CDN of your
choice or your private web space.
The site can be hosted on [GitHub Pages], [GitLab Pages], a CDN of your choice
or your private web space.
[21]: publishing-your-site.md#github-pages
[22]: publishing-your-site.md#gitlab-pages
[GitHub Pages]: publishing-your-site.md#github-pages
[GitLab pages]: publishing-your-site.md#gitlab-pages

122
docs/customization.md
View File

@ -11,11 +11,11 @@ necessary to preserve your brand's style.
## Adding assets
[MkDocs][1] provides several ways to customize a theme. In order to make a few
tweaks to Material for MkDocs, you can just add your stylesheets and JavaScript
files to the `docs` directory.
[MkDocs] provides several ways to customize a theme. In order to make a few
small tweaks to Material for MkDocs, you can just CSS and JavaScript files to
the `docs` directory.
[1]: https://www.mkdocs.org
[MkDocs]: https://www.mkdocs.org
### Additional CSS
@ -31,23 +31,17 @@ new stylesheet file in the `docs` directory:
└─ mkdocs.yml
```
Then, add the following line to `mkdocs.yml`:
Then, add the following lines to `mkdocs.yml`:
``` yaml
extra_css:
- stylesheets/extra.css
```
Spin up the [live preview server][2] and start typing your changes in your
additional stylesheet file – you should see them almost instantly after saving.
[2]: creating-your-site.md#previewing-as-you-write
### Additional JavaScript
The same is true for additional JavaScript. If you want to integrate another
syntax highlighter or add some custom logic to your theme, create a new
JavaScript file in the `docs` directory:
If you want to integrate another syntax highlighter or add some custom logic to
your theme, create a new JavaScript file in the `docs` directory:
``` sh
.
@ -57,30 +51,27 @@ JavaScript file in the `docs` directory:
└─ mkdocs.yml
```
Then, add the following line to `mkdocs.yml`:
Then, add the following lines to `mkdocs.yml`:
``` yaml
extra_javascript:
- javascripts/extra.js
```
Further assistance can be found in the [MkDocs documentation][3].
[3]: https://www.mkdocs.org/user-guide/styling-your-docs/#customizing-a-theme
## Extending the theme
If you want to alter the HTML source (e.g. add or remove some parts), you can
extend the theme. MkDocs supports [theme extension][4], an easy way to override
extend the theme. MkDocs supports [theme extension], an easy way to override
parts of Material for MkDocs without forking from git. This ensures that you
can update to the latest version more easily.
[4]: https://www.mkdocs.org/user-guide/styling-your-docs/#using-the-theme-custom_dir
[theme extension]: https://www.mkdocs.org/user-guide/styling-your-docs/#using-the-theme-custom_dir
### Setup and theme structure
Enable Material for MkDocs as usual in `mkdocs.yml`, and create a new folder
for `overrides` which you then reference using the `custom_dir` key:
for `overrides` which you then reference using the [`custom_dir`][custom_dir]
setting:
``` yaml
theme:
@ -90,16 +81,15 @@ theme:
!!! warning "Theme extension prerequisites"
As the `custom_dir` variable is used for the theme extension process,
Material for MkDocs needs to be installed via `pip` and referenced with the
`name` parameter in `mkdocs.yml`. It will not work when cloning from `git`.
As the [`custom_dir`][custom_dir] setting is used for the theme extension
process, Material for MkDocs needs to be installed via `pip` and referenced
with the [`name`][name] setting in `mkdocs.yml`. It will not work when
cloning from `git`.
The structure in the `overrides` directory must mirror the directory structure
of the original theme, as any file in the `overrides` directory will replace the
file with the same name which is part of the original theme. Besides, further
assets may also be put in the `overrides` directory.
The directory layout of the theme is as follows:
assets may also be put in the `overrides` directory:
``` sh
.
@ -123,8 +113,7 @@ The directory layout of the theme is as follows:
│ ├─ search.html # Search box
│ ├─ social.html # Social links
│ ├─ source.html # Repository information
│ ├─ source-date.html # Last updated date
│ ├─ source-link.html # Link to source file
│ ├─ source-file.html # Source file information
│ ├─ tabs.html # Tabs navigation
│ ├─ tabs-item.html # Tabs navigation item
│ ├─ toc.html # Table of contents
@ -134,11 +123,14 @@ The directory layout of the theme is as follows:
└─ main.html # Default page
```
[custom_dir]: https://www.mkdocs.org/user-guide/configuration/#custom_dir
[name]: https://www.mkdocs.org/user-guide/configuration/#name
### Overriding partials
In order to override a partial, we can replace it with a file of the same name
and location in the `overrides` directory. For example, to replace the original
`footer.html`, create a `footer.html` file in the `overrides/partials`
`footer.html` partial, create a new `footer.html` partial in the `overrides`
directory:
``` sh
@ -152,12 +144,12 @@ 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
features. To override a block, create a `main.html` file inside the `overrides`
directory:
template blocks, which are defined inside the templates and wrap specific
features. In order to set up block overrides, create a `main.html` file inside
the `overrides` directory:
``` sh
.
@ -166,7 +158,7 @@ directory:
└─ mkdocs.yml
```
Then, e.g. to override the site title, add the following line to `main.html`:
Then, e.g. to override the site title, add the following lines to `main.html`:
``` html
{% extends "base.html" %}
@ -176,7 +168,7 @@ Then, e.g. to override the site title, add the following line to `main.html`:
{% endblock %}
```
Material for MkDocs provides the following template blocks:
The following template blocks are provided by the theme:
| Block name | Purpose |
|:------------------|:------------------------------------------------|
@ -194,16 +186,11 @@ Material for MkDocs provides the following template blocks:
| `libs` | Wraps the JavaScript libraries (header) |
| `outdated` | Wraps the version warning |
| `scripts` | Wraps the JavaScript application (footer) |
| `source` | Wraps the linked source files |
| `site_meta` | Wraps the meta tags in the document head |
| `site_nav` | Wraps the site navigation and table of contents |
| `styles` | Wraps the stylesheets (also extra sources) |
| `styles` | Wraps the style sheets (also extra sources) |
| `tabs` | Wraps the tabs navigation (if available) |
For more on this topic refer to the [MkDocs documentation][5].
[5]: https://www.mkdocs.org/user-guide/styling-your-docs/#overriding-template-blocks
#### Additional variables
Besides template blocks, Material for MkDocs provides extra variables for parts
@ -216,11 +203,11 @@ 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 %}
```
Material for MkDocs provides the following additional variables:
The following template variables are provided by the theme:
| Block name | Purpose |
|:------------------|:------------------------------------------------|
@ -228,25 +215,25 @@ Material for MkDocs provides the following additional variables:
## Theme development
Material for MkDocs is built on top of [TypeScript][6], [RxJS][7] and [SASS][8],
and uses a lean, custom build process to put everything together.[^1] If you
want to make more fundamental changes, it may be necessary to make the
adjustments directly in the source of the theme and recompile it.
Material for MkDocs is built on top of [TypeScript], [RxJS] and [SASS], and
uses a lean, custom build process to put everything together.[^1] If you want
to make more fundamental changes, it may be necessary to make the adjustments
directly in the source of the theme and recompile it.
[^1]:
Prior to version 7.0, the build was based on Webpack. This led to broken
builds due to frequent incompatibilities with loaders and plugins, so we
decided to swap Webpack for a leaner custom solution which is now based on
[RxJS][7] as the application itself. This enabled us to remove more than
500 dependencies (~30% less).
Prior to :octicons-tag-24: 7.0.0 the build was based on Webpack, resulting
in occasional broken builds due to incompatibilities with loaders and
plugins. Therefore, we decided to swap Webpack for a leaner solution which
is now based on [RxJS] as the application itself. This allowed for the
pruning of more than 500 dependencies (~30% less).
[6]: https://www.typescriptlang.org/
[7]: https://github.com/ReactiveX/rxjs
[8]: https://sass-lang.com
[TypeScript]: https://www.typescriptlang.org/
[RxJS]: https://github.com/ReactiveX/rxjs
[SASS]: https://sass-lang.com
### Environment setup
In order to start development on Material for MkDocs, a [Node.js][9] version of
In order to start development on Material for MkDocs, a [Node.js] version of
at least 14 is required. First, clone the repository:
```
@ -263,7 +250,7 @@ pip install mkdocs-redirects
npm install
```
[9]: https://nodejs.org
[Node.js]: https://nodejs.org
### Development mode
@ -273,14 +260,14 @@ Start the watcher with:
npm start
```
Then, in a second session, start the MkDocs live preview server with:
Then, in a second terminal window, start the MkDocs live preview server with:
```
mkdocs serve
```
Point your browser to [localhost:8000][10] and you should see this documentation
in front of you.
Point your browser to [localhost:8000][live preview] and you should see this
very documentation in front of you.
!!! warning "Automatically generated files"
@ -288,7 +275,7 @@ in front of you.
directory are automatically generated from the `src` directory and will be
overwritten when the theme is built.
[10]: http://localhost:8000
[live preview]: http://localhost:8000
### Building the theme
@ -298,10 +285,7 @@ When you're finished making your changes, you can build the theme by invoking:
npm run build
```
This triggers the production-level compilation and minification of all
stylesheets and JavaScript sources. When the command exits, the final files are
located in the `material` directory. Add the `theme_dir` variable pointing to
the aforementioned directory in the original `mkdocs.yml`.
Now you can run `mkdocs build` and you should see your documentation with your
changes to the original theme.
This triggers the production-level compilation and minification of all style
sheets and JavaScript files. After the command exits, the compiled files are
located in the `material` directory. When running `mkdocs build`, you should
now see your changes to the original theme.

31
docs/data-privacy.md
View File

@ -1,31 +0,0 @@
---
template: overrides/main.html
---
# Data privacy
In itself, Material for MkDocs does not perform any tracking and adheres to the
[General Data Protection Regulation][1] (GDPR), but it integrates with some
third-party services that may not.
[1]: https://en.wikipedia.org/wiki/General_Data_Protection_Regulation
## Third-party services
### Google Fonts
Material for MkDocs makes fonts [configurable][2] by relying on Google Fonts
CDN, which may be in breach with GDPR. The usage of Google's CDN can be [easily
disabled][3] via `mkdocs.yml`.
[2]: setup/changing-the-fonts.md
[3]: setup/changing-the-fonts.md#disabling-font-loading
### Google Analytics and Disqus
Material for MkDocs comes with optional [Google Analytics][4] and [Disqus][5]
integrations, both of which must be enabled explicitly, so there's no immediate
action if you don't use those.
[4]: setup/setting-up-site-analytics.md#google-analytics
[5]: setup/adding-a-comment-system.md#disqus

2
docs/deprecations.md
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

55
docs/getting-started.md
View File

@ -5,21 +5,18 @@ title: Getting started
# Getting started
Material for MkDocs is a theme for [MkDocs][1], a static site generator geared
Material for MkDocs is a theme for [MkDocs], a static site generator geared
towards (technical) project documentation. If you're familiar with Python, you
can install Material for MkDocs with [`pip`][2], the Python package manager.
If not, we recommended using [`docker`][3].
can install Material for MkDocs with [`pip`][pip], the Python package manager.
If not, we recommended using [`docker`][docker].
In case you're running into problems, consult the [troubleshooting][4] section.
[1]: https://www.mkdocs.org
[2]: #with-pip-recommended
[3]: #with-docker
[4]: troubleshooting.md
[MkDocs]: https://www.mkdocs.org
[pip]: #with-pip
[docker]: #with-docker
## 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`:
@ -28,17 +25,17 @@ pip install mkdocs-material
```
This will automatically install compatible versions of all dependencies:
[MkDocs][1], [Markdown][5], [Pygments][6] and [Python Markdown Extensions][7].
Material for MkDocs always strives to support the latest versions, so there's
no need to install those packages separately.
[MkDocs], [Markdown], [Pygments] and [Python Markdown Extensions]. Material for
MkDocs always strives to support the latest versions, so there's no need to
install those packages separately.
[5]: https://python-markdown.github.io/
[6]: https://pygments.org/
[7]: https://facelessuser.github.io/pymdown-extensions/
[Markdown]: https://python-markdown.github.io/
[Pygments]: https://pygments.org/
[Python Markdown Extensions]: https://facelessuser.github.io/pymdown-extensions/
### with docker
The official [Docker image][8] is a great way to get up and running in a few
The official [Docker image] is a great way to get up and running in a few
minutes, as it comes with all dependencies pre-installed. Pull the image for the
`latest` version with:
@ -52,12 +49,12 @@ covered in the following sections.
The following plugins are bundled with the Docker image:
- [mkdocs-minify-plugin][9]
- [mkdocs-redirects][10]
- [mkdocs-minify-plugin]
- [mkdocs-redirects]
[8]: https://hub.docker.com/r/squidfunk/mkdocs-material/
[9]: https://github.com/byrnereese/mkdocs-minify-plugin
[10]: https://github.com/datarobot/mkdocs-redirects
[Docker image]: https://hub.docker.com/r/squidfunk/mkdocs-material/
[mkdocs-minify-plugin]: https://github.com/byrnereese/mkdocs-minify-plugin
[mkdocs-redirects]: https://github.com/datarobot/mkdocs-redirects
??? question "How to add plugins to the Docker image?"
@ -82,19 +79,19 @@ The following plugins are bundled with the Docker image:
!!! info ":material-apple: Apple Silicon (M1) and :fontawesome-brands-raspberry-pi: Raspberry Pi"
The official Docker image is only available for `linux/amd64`. We recommend
the [third-party image][11] by @afritzler if you want to run Material for
MkDocs via Docker on `arm64` or `armv7`, as it is automatically built on
every release:
the [third-party image] by @afritzler if you want to run Material for MkDocs
via Docker on `arm64` or `armv7`, as it is automatically built on every
release:
```
docker pull ghcr.io/afritzler/mkdocs-material
```
[11]: https://github.com/afritzler/mkdocs-material
[third-party image]: https://github.com/afritzler/mkdocs-material
### with git
Material for MkDocs can be directly used from [GitHub][12] by cloning the
Material for MkDocs can be directly used from [GitHub] by cloning the
repository into a subfolder of your project root which might be useful if you
want to use the very latest version:
@ -106,7 +103,7 @@ The theme will reside in the folder `mkdocs-material/material`. When cloning
from `git`, you must install all required dependencies yourself:
```
pip install -r mkdocs-material/requirements.txt
pip install -e mkdocs-material
```
[12]: https://github.com/squidfunk/mkdocs-material
[GitHub]: https://github.com/squidfunk/mkdocs-material

10
docs/insiders/getting-started.md
View File

@ -7,13 +7,13 @@ title: Switching to Insiders
Material for MkDocs Insiders is a fully compatible drop-in replacement for
Material for MkDocs, and can be installed similar to the public version using
[`pip`][1], [`docker`][2] or [`git`][3]. When you sponsor @squidfunk, your
account is added to the list of collaborators of the private Insiders
[`pip`][pip], [`docker`][docker] or [`git`][git]. When you sponsor @squidfunk,
your account is added to the list of collaborators of the private Insiders
repository.
[1]: #with-pip-recommended
[2]: #with-docker
[3]: #with-git
[pip]: #with-pip
[docker]: #with-docker
[git]: #with-git
## Requirements

18
docs/insiders/index.md
View File

@ -10,11 +10,11 @@ that _new features are first exclusively released to sponsors_ as part of
__Insiders__. Read on to learn [how sponsorship works][1], and how easy it is
to [get access to Insiders][2].
<figure class="mdx-video" markdown="1">
<figure class="mdx-video" markdown>
<div class="mdx-video__inner">
<iframe src="https://streamable.com/e/ihhxw0" allowfullscreen></iframe>
</div>
<figcaption markdown="1">
<figcaption markdown>
The official documentation is built with Insiders
[squidfunk.github.io/mkdocs-material][3]
@ -100,7 +100,7 @@ You can cancel your sponsorship anytime.[^4]
<hr />
<div class="mdx-premium" markdown="1">
<div class="mdx-premium" markdown>
**Special thanks** to our **premium sponsors**:
@ -135,7 +135,7 @@ You can cancel your sponsorship anytime.[^4]
The following features are currently exclusively available to sponsors:
<div class="mdx-columns" markdown="1">
<div class="mdx-columns" markdown>
- [x] [Brand new search plugin :material-new-box:][35]
- [x] [Rich search previews :material-new-box:][36]
@ -150,7 +150,7 @@ The following features are currently exclusively available to sponsors:
- [x] [Stay on page when switching versions][28]
- [x] [Version warning][26]
- [x] [Custom admonition icons][31]
- [x] [Code block annotations][25]
- [x] [Code annotations][25]
- [x] [Anchor tracking ][24]
- [x] [Mermaid.js integration][27]
@ -173,7 +173,7 @@ the public for general availability.
#### $ 4,000 – Ghost Pepper
- [x] [Anchor tracking][24]
- [x] [Code block annotations][25]
- [x] [Code annotations][25]
- [x] [Version warning][26]
[24]: ../setup/setting-up-navigation.md#anchor-tracking
@ -197,8 +197,8 @@ the public for general availability.
- [x] [Linking content tabs][32]
[30]: ../setup/setting-up-site-search.md#search-boosting
[31]: ../reference/admonitions.md#changing-the-icons
[32]: ../reference/content-tabs.md#linking-content-tabs
[31]: ../reference/admonitions.md#admonition-icons
[32]: ../reference/content-tabs.md#linked-content-tabs
#### $ 7,000 – Royal Gold
@ -240,7 +240,7 @@ the public for general availability.
[21]: ../setup/setting-up-navigation.md#sticky-navigation-tabs
[22]: ../setup/setting-up-navigation.md#section-index-pages
[23]: ../setup/setting-up-the-footer.md#remove-generator
[23]: ../setup/setting-up-the-footer.md#generator-notice
#### $ 2,500 – Biquinho Vermelho

52
docs/publishing-your-site.md
View File

@ -10,15 +10,15 @@ makes this ridiculously simple.
## GitHub Pages
If you're already hosting your code on GitHub, [GitHub Pages][1] is certainly
If you're already hosting your code on GitHub, [GitHub Pages] is certainly
the most convenient way to publish your project documentation. It's free of
charge and pretty easy to set up.
[1]: https://pages.github.com/
[GitHub Pages]: https://pages.github.com/
### with GitHub Actions
Using [GitHub Actions][2] you can automate the deployment of your project
Using [GitHub Actions] you can automate the deployment of your project
documentation. At the root of your repository, create a new GitHub Actions
workflow, e.g. `.github/workflows/ci.yml`, and copy and paste the following
contents:
@ -49,7 +49,7 @@ contents:
2. At some point, GitHub renamed `master` to `main`. If your default branch
is named `master`, you can safely remove `main`, vice versa.
3. This is the place to install further [MkDocs plugins][3] or Markdown
3. This is the place to install further [MkDocs plugins] or Markdown
extensions with `pip` to be used during the build:
``` sh
@ -80,24 +80,24 @@ contents:
- run: pip install git+https://${GH_TOKEN}@github.com/squidfunk/mkdocs-material-insiders.git
- run: mkdocs gh-deploy --force
env:
GH_TOKEN: ${{ secrets.GH_TOKEN }}
GH_TOKEN: ${{ secrets.GH_TOKEN }} # (1)
```
1. Remember to set the `GH_TOKEN` environment variable to the value of your
[personal access token] when deploying [Insiders], which can be done
using [GitHub secrets].
Now, when a new commit is pushed to either the `master` or `main` branches,
the static site is automatically built and deployed. Push your changes to see
the workflow in action.
Your documentation should shortly appear at `<username>.github.io/<repository>`.
_Remember to set the_ `GH_TOKEN` _environment variable to the value of your
[personal access token][4] when deploying [Insiders][5], which can be done
using [secrets][6]._
[2]: https://github.com/features/actions
[3]: https://github.com/mkdocs/mkdocs/wiki/MkDocs-Plugins
[4]: https://docs.github.com/en/github/authenticating-to-github/creating-a-personal-access-token
[5]: insiders/index.md
[6]: https://docs.github.com/en/actions/configuring-and-managing-workflows/creating-and-storing-encrypted-secrets
[GitHub Actions]: https://github.com/features/actions
[MkDocs plugins]: https://github.com/mkdocs/mkdocs/wiki/MkDocs-Plugins
[personal access token]: https://docs.github.com/en/github/authenticating-to-github/creating-a-personal-access-token
[Insiders]: insiders/index.md
[GitHub secrets]: https://docs.github.com/en/actions/configuring-and-managing-workflows/creating-and-storing-encrypted-secrets
### with MkDocs
@ -110,10 +110,10 @@ mkdocs gh-deploy --force
## GitLab Pages
If you're hosting your code on GitLab, deploying to [GitLab Pages][7] can be
done by using the [GitLab CI][8] task runner. At the root of your repository,
create a task definition named `.gitlab-ci.yml` and copy and paste the
following contents:
If you're hosting your code on GitLab, deploying to [GitLab Pages] can be done
by using the [GitLab CI] task runner. At the root of your repository, create a
task definition named `.gitlab-ci.yml` and copy and paste the following
contents:
=== "Material for MkDocs"
@ -139,7 +139,7 @@ following contents:
stage: deploy
only:
- master
script:
script: # (1)
- pip install git+https://${GH_TOKEN}@github.com/squidfunk/mkdocs-material-insiders.git
- mkdocs build --site-dir public
artifacts:
@ -147,16 +147,16 @@ following contents:
- public
```
1. Remember to set the `GH_TOKEN` environment variable to the value of your
[personal access token] when deploying [Insiders], which can be done
using [masked custom variables].
Now, when a new commit is pushed to `master`, the static site is automatically
built and deployed. Commit and push the file to your repository to see the
workflow in action.
Your documentation should shortly appear at `<username>.gitlab.io/<repository>`.
_Remember to set the_ `GH_TOKEN` _environment variable to the value of your
[personal access token][4] when deploying [Insiders][5], which can be done
using [masked custom variables][9]._
[7]: https://gitlab.com/pages
[8]: https://docs.gitlab.com/ee/ci/
[9]: https://docs.gitlab.com/ee/ci/variables/#create-a-custom-variable-in-the-ui
[GitLab Pages]: https://gitlab.com/pages
[GitLab CI]: https://docs.gitlab.com/ee/ci/
[masked custom variables]: https://docs.gitlab.com/ee/ci/variables/#create-a-custom-variable-in-the-ui

65
docs/reference/abbreviations.md
View File

@ -4,50 +4,38 @@ template: overrides/main.html
# Abbreviations
Technical documentation often incurs the usage of a lot of acronyms, which may
Technical documentation often incurs the usage of many acronyms, which may
need additional explanation, especially for new user of your project. For these
matters, Material for MkDocs uses a combination of Markdown extensions to
enable site-wide glossaries.
## Configuration
### Abbreviations
[:octicons-file-code-24: Source][1] · [:octicons-workflow-24: Extension][2]
The [Abbreviations][2] extension, which is part of the standard Markdown
library, allows to __add additional content to parts of the text which are then
shown on hover__, e.g. for glossaries:
This configuration enables abbreviations and allows to build a simple
project-wide glossary, sourcing definitions from a central location. Add the
following line to `mkdocs.yml`:
``` yaml
markdown_extensions:
- abbr
```
[1]: https://github.com/squidfunk/mkdocs-material/blob/master/src/assets/stylesheets/main/_typeset.scss
[2]: https://python-markdown.github.io/extensions/abbreviations/
### Snippets
The [Snippets][3] extension, which is part of [Python Markdown Extensions][4],
allows to __insert content from other files__ or other, regular content, and can
be enabled via `mkdocs.yml`:
``` yaml
markdown_extensions:
- pymdownx.snippets
```
[3]: https://facelessuser.github.io/pymdown-extensions/extensions/snippets/
[4]: https://facelessuser.github.io/pymdown-extensions/
See additional configuration options:
- [Abbreviations]
- [Snippets]
[Abbreviations]: ../setup/extensions/python-markdown.md#abbreviations
[Snippets]: ../setup/extensions/python-markdown-extensions.md#snippets
## Usage
### Adding abbreviations
When the [Abbreviations][5] extension is enabled, abbreviations can be defined
with a special syntax similar to URLs and [footnotes][6] at any point in the
Markdown document.
Abbreviations can be defined by using a special syntax similar to URLs and
[footnotes], starting with a `*` and immediately followed by the term or
acronym to be associated in square brackets.
_Example_:
@ -65,18 +53,23 @@ The HTML specification is maintained by the W3C.
*[HTML]: Hyper Text Markup Language
*[W3C]: World Wide Web Consortium
[5]: #abbreviations_1
[6]: footnotes.md
[footnotes]: footnotes.md
### Adding a glossary
When [Snippets][7] is enabled, content from other files can be embedded, which
is especially useful to include abbreviations from a central file – a glossary –
and embed them into any other file.
The [Snippets] extension can be used to implement a simple glossary by moving
all abbreviations in a dedicated file[^1], and embedding it with the
[`--8<--` notation][Snippets notation] at the end of each document.
[^1]:
It's highly recommended to put the Markdown file containing the
abbreviations outside of the `docs` folder (here, a folder with the name
`includes` is used), as MkDocs might otherwise complain about an
unreferenced file.
_Example_:
=== "`docs/page.md`"
=== ":octicons-file-code-16: docs/example.md"
```` markdown
The HTML specification is maintained by the W3C.
@ -84,7 +77,7 @@ _Example_:
--8<-- "includes/abbreviations.md"
````
=== "`includes/abbreviations.md`"
=== ":octicons-file-code-16: includes/abbreviations.md"
```` markdown
*[HTML]: Hyper Text Markup Language
@ -95,8 +88,4 @@ _Result_:
The HTML specification is maintained by the W3C.
_Remember to locate the Markdown file containing the definitions outside of the_
`docs` _folder (here_ `includes` _is used), or MkDocs may complain about an
unreferenced file._
[7]: #snippets
[Snippets notation]: https://facelessuser.github.io/pymdown-extensions/extensions/snippets/#snippets-notation

784
docs/reference/admonitions.md
View File

@ -11,396 +11,49 @@ inclusion and nesting of arbitrary content.
## Configuration
### Admonition
[:octicons-file-code-24: Source][1] · [:octicons-workflow-24: Extension][2]
The [Admonition][2] extension, which is part of the standard Markdown
library, is integrated with Material for MkDocs and can be enabled via
This configuration enables admonitions, allows to make them collapsible and to
nest arbitrary content inside admonitions. Add the following lines to
`mkdocs.yml`:
``` yaml
markdown_extensions:
- admonition
```
[1]: https://github.com/squidfunk/mkdocs-material/blob/master/src/assets/stylesheets/main/extensions/markdown/_admonition.scss
[2]: https://python-markdown.github.io/extensions/admonition/
### Details
[:octicons-file-code-24: Source][3] · [:octicons-workflow-24: Extension][4]
The [Details][4] extension, which is part of [Python Markdown Extensions][5],
adds the ability to __make admonitions collapsible__. It can be enabled via
`mkdocs.yml`:
``` yaml
markdown_extensions:
- pymdownx.details
```
[3]: https://github.com/squidfunk/mkdocs-material/blob/master/src/assets/stylesheets/main/extensions/pymdownx/_details.scss
[4]: https://facelessuser.github.io/pymdown-extensions/extensions/details/
[5]: https://facelessuser.github.io/pymdown-extensions/
### SuperFences
The [SuperFences][6] extension, which is also part of [Python Markdown
Extensions][5], allows for the __nesting of code and content blocks inside
admonitions__, and is therefore strongly recommended:
``` yaml
markdown_extensions:
- pymdownx.superfences
```
[6]: https://facelessuser.github.io/pymdown-extensions/extensions/superfences/
## Usage
See additional configuration options:
Admonitions follow a simple syntax: a block must start with `!!!`, followed
by a single keyword which is used as the [type qualifier][7] of the block. The
content of the block then follows on the next line, indented by four spaces.
- [Admonition]
- [Details]
- [SuperFences]
_Example_:
[Admonition]: ../setup/extensions/python-markdown.md#admonition
[Details]: ../setup/extensions/python-markdown-extensions.md#details
[SuperFences]: ../setup/extensions/python-markdown-extensions.md#superfences
``` markdown
!!! note
Lorem ipsum dolor sit amet, consectetur adipiscing elit. Nulla et euismod
nulla. Curabitur feugiat, tortor non consequat finibus, justo purus auctor
massa, nec semper lorem quam in massa.
```
### Admonition icons
_Result_:
!!! note
Lorem ipsum dolor sit amet, consectetur adipiscing elit. Nulla et euismod
nulla. Curabitur feugiat, tortor non consequat finibus, justo purus auctor
massa, nec semper lorem quam in massa.
[7]: #supported-types
### Changing the title
By default, the title will equal the type qualifier in titlecase. However, it
can be changed by adding a quoted string containing valid Markdown (including
links, formatting, ...) after the type qualifier.
_Example_:
``` markdown
!!! note "Phasellus posuere in sem ut cursus"
Lorem ipsum dolor sit amet, consectetur adipiscing elit. Nulla et euismod
nulla. Curabitur feugiat, tortor non consequat finibus, justo purus auctor
massa, nec semper lorem quam in massa.
```
_Result_:
!!! note "Phasellus posuere in sem ut cursus"
Lorem ipsum dolor sit amet, consectetur adipiscing elit. Nulla et euismod
nulla. Curabitur feugiat, tortor non consequat finibus, justo purus auctor
massa, nec semper lorem quam in massa.
### Removing the title
Similar to [changing the title][8], the icon and title can be omitted entirely
by adding an empty string directly after the type qualifier. Note that this
will not work for [collapsible blocks][9].
_Example_:
``` markdown
!!! note ""
Lorem ipsum dolor sit amet, consectetur adipiscing elit. Nulla et euismod
nulla. Curabitur feugiat, tortor non consequat finibus, justo purus auctor
massa, nec semper lorem quam in massa.
```
_Result_:
!!! note ""
Lorem ipsum dolor sit amet, consectetur adipiscing elit. Nulla et euismod
nulla. Curabitur feugiat, tortor non consequat finibus, justo purus auctor
massa, nec semper lorem quam in massa.
[8]: #changing-the-title
[9]: #collapsible-blocks
### Embedded content
Admonitions can contain all kinds of text content, including headlines, lists,
paragraphs and other blocks. While the parser from the standard Markdown library
doesn't account for nested blocks, the [SuperFences][10] extension adds the
ability to nest arbitrary content inside admonitions.
_Example_:
``` markdown
!!! note
Lorem ipsum dolor sit amet, consectetur adipiscing elit. Nulla et euismod
nulla. Curabitur feugiat, tortor non consequat finibus, justo purus auctor
massa, nec semper lorem quam in massa.
``` python
def bubble_sort(items):
for i in range(len(items)):
for j in range(len(items) - 1 - i):
if items[j] > items[j + 1]:
items[j], items[j + 1] = items[j + 1], items[j]
```
Nunc eu odio eleifend, blandit leo a, volutpat sapien. Phasellus posuere in
sem ut cursus. Nullam sit amet tincidunt ipsum, sit amet elementum turpis.
Etiam ipsum quam, mattis in purus vitae, lacinia fermentum enim.
```
_Result_:
!!! note
Lorem ipsum dolor sit amet, consectetur adipiscing elit. Nulla et euismod
nulla. Curabitur feugiat, tortor non consequat finibus, justo purus auctor
massa, nec semper lorem quam in massa.
``` python
def bubble_sort(items):
for i in range(len(items)):
for j in range(len(items) - 1 - i):
if items[j] > items[j + 1]:
items[j], items[j + 1] = items[j + 1], items[j]
```
Nunc eu odio eleifend, blandit leo a, volutpat sapien. Phasellus posuere in
sem ut cursus. Nullam sit amet tincidunt ipsum, sit amet elementum turpis.
Etiam ipsum quam, mattis in purus vitae, lacinia fermentum enim.
[10]: #superfences
### Collapsible blocks
The [Details][11] extension adds support for rendering collapsible admonition
blocks. This is useful for FAQs or content that is of secondary nature. A
details block follows the syntax and semantics of admonition blocks, but must
start with `???`.
_Example_:
``` markdown
??? note
Lorem ipsum dolor sit amet, consectetur adipiscing elit. Nulla et euismod
nulla. Curabitur feugiat, tortor non consequat finibus, justo purus auctor
massa, nec semper lorem quam in massa.
```
_Result_:
??? note
Lorem ipsum dolor sit amet, consectetur adipiscing elit. Nulla et euismod
nulla. Curabitur feugiat, tortor non consequat finibus, justo purus auctor
massa, nec semper lorem quam in massa.
Adding a `+` after `???` will render the block as open on page load:
_Example_:
``` markdown
???+ note
Lorem ipsum dolor sit amet, consectetur adipiscing elit. Nulla et euismod
nulla. Curabitur feugiat, tortor non consequat finibus, justo purus auctor
massa, nec semper lorem quam in massa.
```
_Result_:
???+ note
Lorem ipsum dolor sit amet, consectetur adipiscing elit. Nulla et euismod
nulla. Curabitur feugiat, tortor non consequat finibus, justo purus auctor
massa, nec semper lorem quam in massa.
[11]: #details
### Inline blocks
[:octicons-file-code-24: Source][12] ·
:octicons-beaker-24: Experimental
Admonitions and [Details][11] can also be rendered as inline blocks (i.e.
sidebars), placing them to the right using the `inline` + `end` modifiers, or
to the left using only the `inline` modifier.
__Important__: Admonitions that use the `inline` modifiers _must_ be declared
prior to the content block you want to place them beside. If there's
insufficient space to render the admonition next to the block, the admonition
will stretch to the full width of the viewport, e.g. on mobile viewports.
=== "inline end"
_Example_ / _Result_:
!!! info inline end
Lorem ipsum dolor sit amet, consectetur adipiscing elit. Nulla et
euismod nulla. Curabitur feugiat, tortor non consequat finibus, justo
purus auctor massa, nec semper lorem quam in massa.
``` markdown
!!! info inline end
Lorem ipsum dolor sit amet, consectetur
adipiscing elit. Nulla et euismod nulla.
Curabitur feugiat, tortor non consequat
finibus, justo purus auctor massa, nec
semper lorem quam in massa.
```
Use `inline end` to align to the right (left for rtl languages).
=== "inline"
_Example_ / _Result_:
!!! info inline
Lorem ipsum dolor sit amet, consectetur adipiscing elit. Nulla et
euismod nulla. Curabitur feugiat, tortor non consequat finibus, justo
purus auctor massa, nec semper lorem quam in massa.
``` markdown
!!! info inline
Lorem ipsum dolor sit amet, consectetur
adipiscing elit. Nulla et euismod nulla.
Curabitur feugiat, tortor non consequat
finibus, justo purus auctor massa, nec
semper lorem quam in massa.
```
Use `inline` to align to the left (right for rtl languages).
[12]: https://github.com/squidfunk/mkdocs-material/blob/master/src/assets/stylesheets/main/_modifiers.scss
### Supported types
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
Lorem ipsum dolor sit amet, consectetur adipiscing elit. Nulla et
euismod nulla. Curabitur feugiat, tortor non consequat finibus, justo
purus auctor massa, nec semper lorem quam in massa.
`abstract`{ #abstract }, `summary`, `tldr`
: !!! abstract
Lorem ipsum dolor sit amet, consectetur adipiscing elit. Nulla et
euismod nulla. Curabitur feugiat, tortor non consequat finibus, justo
purus auctor massa, nec semper lorem quam in massa.
`info`{ #info }, `todo`
: !!! info
Lorem ipsum dolor sit amet, consectetur adipiscing elit. Nulla et
euismod nulla. Curabitur feugiat, tortor non consequat finibus, justo
purus auctor massa, nec semper lorem quam in massa.
`tip`{ #tip }, `hint`, `important`
: !!! tip
Lorem ipsum dolor sit amet, consectetur adipiscing elit. Nulla et
euismod nulla. Curabitur feugiat, tortor non consequat finibus, justo
purus auctor massa, nec semper lorem quam in massa.
`success`{ #success }, `check`, `done`
: !!! success
Lorem ipsum dolor sit amet, consectetur adipiscing elit. Nulla et
euismod nulla. Curabitur feugiat, tortor non consequat finibus, justo
purus auctor massa, nec semper lorem quam in massa.
`question`{ #question }, `help`, `faq`
: !!! question
Lorem ipsum dolor sit amet, consectetur adipiscing elit. Nulla et
euismod nulla. Curabitur feugiat, tortor non consequat finibus, justo
purus auctor massa, nec semper lorem quam in massa.
`warning`{ #warning }, `caution`, `attention`
: !!! warning
Lorem ipsum dolor sit amet, consectetur adipiscing elit. Nulla et
euismod nulla. Curabitur feugiat, tortor non consequat finibus, justo
purus auctor massa, nec semper lorem quam in massa.
`failure`{ #failure }, `fail`, `missing`
: !!! failure
Lorem ipsum dolor sit amet, consectetur adipiscing elit. Nulla et
euismod nulla. Curabitur feugiat, tortor non consequat finibus, justo
purus auctor massa, nec semper lorem quam in massa.
`danger`{ #danger }, `error`
: !!! danger
Lorem ipsum dolor sit amet, consectetur adipiscing elit. Nulla et
euismod nulla. Curabitur feugiat, tortor non consequat finibus, justo
purus auctor massa, nec semper lorem quam in massa.
`bug`{ #bug }
: !!! bug
Lorem ipsum dolor sit amet, consectetur adipiscing elit. Nulla et
euismod nulla. Curabitur feugiat, tortor non consequat finibus, justo
purus auctor massa, nec semper lorem quam in massa.
`example`{ #example }
: !!! example
Lorem ipsum dolor sit amet, consectetur adipiscing elit. Nulla et
euismod nulla. Curabitur feugiat, tortor non consequat finibus, justo
purus auctor massa, nec semper lorem quam in massa.
`quote`{ #quote }, `cite`
: !!! quote
Lorem ipsum dolor sit amet, consectetur adipiscing elit. Nulla et
euismod nulla. Curabitur feugiat, tortor non consequat finibus, justo
purus auctor massa, nec semper lorem quam in massa.
[^1]:
The `seealso` qualifier was originally adapted from the `readthedocs` theme,
in order to make it easier for authors to migrate to Material for MkDocs.
However, when the title is omitted, the admonition extension will render it
as `Seealso`, which is incorrect English. For this reason, it was deprecated
as of 7.1.5 and will be removed in 8.x.
### Changing the icons
[:octicons-file-code-24: Source][13] ·
[:octicons-heart-fill-24:{ .mdx-heart } Insiders only][13]{ .mdx-insiders }
[:octicons-heart-fill-24:{ .mdx-heart } Insiders][Insiders]{ .mdx-insiders } ·
[:octicons-tag-24: insiders-2.4.0][Insiders]
Each of the supported admonition types has a distinct icon, which can be changed
to any icon bundled with the theme. Just set the name of the admonition type to
a valid icon in `mkdocs.yml`:
to any icon bundled with the theme, or even a [custom icon]. Add the following
lines to `mkdocs.yml`:
=== "Octicons"
``` yaml
theme:
icon:
admonition:
<type>: <icon> # (1)
```
1. Set `<type`> to any of the [supported types] and `<icon>` to any valid icon
shortcode, which you can find by using the [icon search].
??? example "Example: using alternative icon sets"
=== ":octicons-mark-github-16: Octicons"
_Example_:
@ -424,10 +77,10 @@ a valid icon in `mkdocs.yml`:
_Result_:
[![Admonition with Octicons icons][14]][14]
[![Octicons]][Octicons]
=== "FontAwesome"
=== ":fontawesome-brands-font-awesome: FontAwesome"
_Example_:
@ -451,44 +104,311 @@ a valid icon in `mkdocs.yml`:
_Result_:
[![Admonition with FontAwesome icons][15]][15]
[![FontAwesome]][FontAwesome]
[13]: ../insiders/index.md
[14]: ../assets/screenshots/admonition-octicons.png
[15]: ../assets/screenshots/admonition-fontawesome.png
[Insiders]: ../insiders/index.md
[custom icon]: icons-emojis.md#additional-icons
[supported types]: #supported-types
[icon search]: icons-emojis.md#search
[Octicons]: ../assets/screenshots/admonition-octicons.png
[FontAwesome]: ../assets/screenshots/admonition-fontawesome.png
## Usage
Admonitions follow a simple syntax: a block starts with `!!!`, followed by a
single keyword used as a [type qualifier]. The content of the block follows on
the next line, indented by four spaces.
_Example_:
``` markdown
!!! note
Lorem ipsum dolor sit amet, consectetur adipiscing elit. Nulla et euismod
nulla. Curabitur feugiat, tortor non consequat finibus, justo purus auctor
massa, nec semper lorem quam in massa.
```
_Result_:
!!! note
Lorem ipsum dolor sit amet, consectetur adipiscing elit. Nulla et euismod
nulla. Curabitur feugiat, tortor non consequat finibus, justo purus auctor
massa, nec semper lorem quam in massa.
[type qualifier]: #supported-types
### Changing the title
By default, the title will equal the type qualifier in titlecase. However, it
can be changed by adding a quoted string containing valid Markdown (including
links, formatting, ...) after the type qualifier.
_Example_:
``` markdown
!!! note "Phasellus posuere in sem ut cursus"
Lorem ipsum dolor sit amet, consectetur adipiscing elit. Nulla et euismod
nulla. Curabitur feugiat, tortor non consequat finibus, justo purus auctor
massa, nec semper lorem quam in massa.
```
_Result_:
!!! note "Phasellus posuere in sem ut cursus"
Lorem ipsum dolor sit amet, consectetur adipiscing elit. Nulla et euismod
nulla. Curabitur feugiat, tortor non consequat finibus, justo purus auctor
massa, nec semper lorem quam in massa.
### Removing the title
Similar to [changing the title], the icon and title can be omitted entirely by
adding an empty string directly after the type qualifier. Note that this will
not work for [collapsible blocks].
_Example_:
``` markdown
!!! note ""
Lorem ipsum dolor sit amet, consectetur adipiscing elit. Nulla et euismod
nulla. Curabitur feugiat, tortor non consequat finibus, justo purus auctor
massa, nec semper lorem quam in massa.
```
_Result_:
!!! note ""
Lorem ipsum dolor sit amet, consectetur adipiscing elit. Nulla et euismod
nulla. Curabitur feugiat, tortor non consequat finibus, justo purus auctor
massa, nec semper lorem quam in massa.
[changing the title]: #changing-the-title
[collapsible blocks]: #collapsible-blocks
### Collapsible blocks
When [Details] is enabled and an admonition block is started with `???` instead
of `!!!`, the admonition is rendered as a collapsible block with a small toggle
on the right side.
_Example_:
``` markdown
??? note
Lorem ipsum dolor sit amet, consectetur adipiscing elit. Nulla et euismod
nulla. Curabitur feugiat, tortor non consequat finibus, justo purus auctor
massa, nec semper lorem quam in massa.
```
_Result_:
??? note
Lorem ipsum dolor sit amet, consectetur adipiscing elit. Nulla et euismod
nulla. Curabitur feugiat, tortor non consequat finibus, justo purus auctor
massa, nec semper lorem quam in massa.
Adding a `+` after the `???` token will render the block as open.
_Example_:
``` markdown
???+ note
Lorem ipsum dolor sit amet, consectetur adipiscing elit. Nulla et euismod
nulla. Curabitur feugiat, tortor non consequat finibus, justo purus auctor
massa, nec semper lorem quam in massa.
```
_Result_:
???+ note
Lorem ipsum dolor sit amet, consectetur adipiscing elit. Nulla et euismod
nulla. Curabitur feugiat, tortor non consequat finibus, justo purus auctor
massa, nec semper lorem quam in massa.
### Inline blocks
[:octicons-tag-24: 7.0.0][Inline support] ·
:octicons-beaker-24: Experimental
Admonitions can also be rendered as inline blocks (i.e. for sidebars), placing
them to the right using the `inline` + `end` modifiers, or to the left using
only the `inline` modifier.
=== ":octicons-arrow-right-16: inline end"
_Example_ / _Result_:
!!! info inline end
Lorem ipsum dolor sit amet, consectetur adipiscing elit. Nulla et
euismod nulla. Curabitur feugiat, tortor non consequat finibus, justo
purus auctor massa, nec semper lorem quam in massa.
``` markdown
!!! info inline end
Lorem ipsum dolor sit amet, consectetur
adipiscing elit. Nulla et euismod nulla.
Curabitur feugiat, tortor non consequat
finibus, justo purus auctor massa, nec
semper lorem quam in massa.
```
Use `inline end` to align to the right (left for rtl languages).
=== ":octicons-arrow-left-16: inline"
_Example_ / _Result_:
!!! info inline
Lorem ipsum dolor sit amet, consectetur adipiscing elit. Nulla et
euismod nulla. Curabitur feugiat, tortor non consequat finibus, justo
purus auctor massa, nec semper lorem quam in massa.
``` markdown
!!! info inline
Lorem ipsum dolor sit amet, consectetur
adipiscing elit. Nulla et euismod nulla.
Curabitur feugiat, tortor non consequat
finibus, justo purus auctor massa, nec
semper lorem quam in massa.
```
Use `inline` to align to the left (right for rtl languages).
__Important__: Admonitions that use the `inline` modifiers _must_ be declared
prior to the content block you want to place them beside. If there's
insufficient space to render the admonition next to the block, the admonition
will stretch to the full width of the viewport, e.g. on mobile viewports.
[Inline support]: https://github.com/squidfunk/mkdocs-material/releases/tag/7.0.0
### Supported types
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`{ #type-note }, ~~`seealso`~~ [^1]
: !!! note
Lorem ipsum dolor sit amet, consectetur adipiscing elit. Nulla et
euismod nulla. Curabitur feugiat, tortor non consequat finibus, justo
purus auctor massa, nec semper lorem quam in massa.
`abstract`{ #type-abstract }, `summary`, `tldr`
: !!! abstract
Lorem ipsum dolor sit amet, consectetur adipiscing elit. Nulla et
euismod nulla. Curabitur feugiat, tortor non consequat finibus, justo
purus auctor massa, nec semper lorem quam in massa.
`info`{ #type-info }, `todo`
: !!! info
Lorem ipsum dolor sit amet, consectetur adipiscing elit. Nulla et
euismod nulla. Curabitur feugiat, tortor non consequat finibus, justo
purus auctor massa, nec semper lorem quam in massa.
`tip`{ #type-tip }, `hint`, `important`
: !!! tip
Lorem ipsum dolor sit amet, consectetur adipiscing elit. Nulla et
euismod nulla. Curabitur feugiat, tortor non consequat finibus, justo
purus auctor massa, nec semper lorem quam in massa.
`success`{ #type-success }, `check`, `done`
: !!! success
Lorem ipsum dolor sit amet, consectetur adipiscing elit. Nulla et
euismod nulla. Curabitur feugiat, tortor non consequat finibus, justo
purus auctor massa, nec semper lorem quam in massa.
`question`{ #type-question }, `help`, `faq`
: !!! question
Lorem ipsum dolor sit amet, consectetur adipiscing elit. Nulla et
euismod nulla. Curabitur feugiat, tortor non consequat finibus, justo
purus auctor massa, nec semper lorem quam in massa.
`warning`{ #type-warning }, `caution`, `attention`
: !!! warning
Lorem ipsum dolor sit amet, consectetur adipiscing elit. Nulla et
euismod nulla. Curabitur feugiat, tortor non consequat finibus, justo
purus auctor massa, nec semper lorem quam in massa.
`failure`{ #type-failure }, `fail`, `missing`
: !!! failure
Lorem ipsum dolor sit amet, consectetur adipiscing elit. Nulla et
euismod nulla. Curabitur feugiat, tortor non consequat finibus, justo
purus auctor massa, nec semper lorem quam in massa.
`danger`{ #type-danger }, `error`
: !!! danger
Lorem ipsum dolor sit amet, consectetur adipiscing elit. Nulla et
euismod nulla. Curabitur feugiat, tortor non consequat finibus, justo
purus auctor massa, nec semper lorem quam in massa.
`bug`{ #type-bug }
: !!! bug
Lorem ipsum dolor sit amet, consectetur adipiscing elit. Nulla et
euismod nulla. Curabitur feugiat, tortor non consequat finibus, justo
purus auctor massa, nec semper lorem quam in massa.
`example`{ #type-example }
: !!! example
Lorem ipsum dolor sit amet, consectetur adipiscing elit. Nulla et
euismod nulla. Curabitur feugiat, tortor non consequat finibus, justo
purus auctor massa, nec semper lorem quam in massa.
`quote`{ #type-quote }, `cite`
: !!! quote
Lorem ipsum dolor sit amet, consectetur adipiscing elit. Nulla et
euismod nulla. Curabitur feugiat, tortor non consequat finibus, justo
purus auctor massa, nec semper lorem quam in massa.
[^1]:
The `seealso` qualifier was originally adapted from the `readthedocs` theme,
in order to make it easier for authors to migrate to Material for MkDocs.
However, when the title is omitted, the admonition extension will render it
as `Seealso`, which is incorrect English. For this reason, it was deprecated
in :octicons-tag-24: 7.1.5 and will be removed in :octicons-tag-24: 8.0.0.
## Customization
### Custom admonitions
If you want to add a custom admonition type, all you need is a color and an
`svg` icon. Copy the icon's `svg` code from the [`.icons`][16] folder and add the
following CSS to an [additional stylesheet][17]:
``` css
:root {
--md-admonition-icon--pied-piper: url('data:image/svg+xml;charset=utf-8,<svg xmlns="http://www.w3.org/2000/svg" viewBox="0 0 576 512"><path d="M244 246c-3.2-2-6.3-2.9-10.1-2.9-6.6 0-12.6 3.2-19.3 3.7l1.7 4.9zm135.9 197.9c-19 0-64.1 9.5-79.9 19.8l6.9 45.1c35.7 6.1 70.1 3.6 106-9.8-4.8-10-23.5-55.1-33-55.1zM340.8 177c6.6 2.8 11.5 9.2 22.7 22.1 2-1.4 7.5-5.2 7.5-8.6 0-4.9-11.8-13.2-13.2-23 11.2-5.7 25.2-6 37.6-8.9 68.1-16.4 116.3-52.9 146.8-116.7C548.3 29.3 554 16.1 554.6 2l-2 2.6c-28.4 50-33 63.2-81.3 100-31.9 24.4-69.2 40.2-106.6 54.6l-6.3-.3v-21.8c-19.6 1.6-19.7-14.6-31.6-23-18.7 20.6-31.6 40.8-58.9 51.1-12.7 4.8-19.6 10-25.9 21.8 34.9-16.4 91.2-13.5 98.8-10zM555.5 0l-.6 1.1-.3.9.6-.6zm-59.2 382.1c-33.9-56.9-75.3-118.4-150-115.5l-.3-6c-1.1-13.5 32.8 3.2 35.1-31l-14.4 7.2c-19.8-45.7-8.6-54.3-65.5-54.3-14.7 0-26.7 1.7-41.4 4.6 2.9 18.6 2.2 36.7-10.9 50.3l19.5 5.5c-1.7 3.2-2.9 6.3-2.9 9.8 0 21 42.8 2.9 42.8 33.6 0 18.4-36.8 60.1-54.9 60.1-8 0-53.7-50-53.4-60.1l.3-4.6 52.3-11.5c13-2.6 12.3-22.7-2.9-22.7-3.7 0-43.1 9.2-49.4 10.6-2-5.2-7.5-14.1-13.8-14.1-3.2 0-6.3 3.2-9.5 4-9.2 2.6-31 2.9-21.5 20.1L15.9 298.5c-5.5 1.1-8.9 6.3-8.9 11.8 0 6 5.5 10.9 11.5 10.9 8 0 131.3-28.4 147.4-32.2 2.6 3.2 4.6 6.3 7.8 8.6 20.1 14.4 59.8 85.9 76.4 85.9 24.1 0 58-22.4 71.3-41.9 3.2-4.3 6.9-7.5 12.4-6.9.6 13.8-31.6 34.2-33 43.7-1.4 10.2-1 35.2-.3 41.1 26.7 8.1 52-3.6 77.9-2.9 4.3-21 10.6-41.9 9.8-63.5l-.3-9.5c-1.4-34.2-10.9-38.5-34.8-58.6-1.1-1.1-2.6-2.6-3.7-4 2.2-1.4 1.1-1 4.6-1.7 88.5 0 56.3 183.6 111.5 229.9 33.1-15 72.5-27.9 103.5-47.2-29-25.6-52.6-45.7-72.7-79.9zm-196.2 46.1v27.2l11.8-3.4-2.9-23.8zm-68.7-150.4l24.1 61.2 21-13.8-31.3-50.9zm84.4 154.9l2 12.4c9-1.5 58.4-6.6 58.4-14.1 0-1.4-.6-3.2-.9-4.6-26.8 0-36.9 3.8-59.5 6.3z"/></svg>')
}
.md-typeset .admonition.pied-piper,
.md-typeset details.pied-piper {
border-color: rgb(43, 155, 70);
}
.md-typeset .pied-piper > .admonition-title,
.md-typeset .pied-piper > summary {
background-color: rgba(43, 155, 70, 0.1);
border-color: rgb(43, 155, 70);
}
.md-typeset .pied-piper > .admonition-title::before,
.md-typeset .pied-piper > summary::before {
background-color: rgb(43, 155, 70);
-webkit-mask-image: var(--md-admonition-icon--pied-piper);
mask-image: var(--md-admonition-icon--pied-piper);
}
```
You should now be able to create an admonition of the `pied-piper` type. Note
that you can also use this technique to override existing admonition icons or
colors. [You can even add animations][18].
`*.svg` icon. Copy the icon's code from the [`.icons`][custom icons] folder
and add the following CSS to an [additional style sheet]:
<style>
:root {
@ -513,12 +433,45 @@ colors. [You can even add animations][18].
_Example_:
``` markdown
!!! pied-piper "Pied Piper"
Lorem ipsum dolor sit amet, consectetur adipiscing elit. Nulla et euismod
nulla. Curabitur feugiat, tortor non consequat finibus, justo purus auctor
massa, nec semper lorem quam in massa.
```
=== ":octicons-file-code-16: docs/example.md"
``` markdown
!!! pied-piper "Pied Piper"
Lorem ipsum dolor sit amet, consectetur adipiscing elit. Nulla et
euismod nulla. Curabitur feugiat, tortor non consequat finibus, justo
purus auctor massa, nec semper lorem quam in massa.
```
=== ":octicons-file-code-16: docs/stylesheets/extra.css"
``` css
:root {
--md-admonition-icon--pied-piper: url('data:image/svg+xml;charset=utf-8,<svg xmlns="http://www.w3.org/2000/svg" viewBox="0 0 576 512"><path d="M244 246c-3.2-2-6.3-2.9-10.1-2.9-6.6 0-12.6 3.2-19.3 3.7l1.7 4.9zm135.9 197.9c-19 0-64.1 9.5-79.9 19.8l6.9 45.1c35.7 6.1 70.1 3.6 106-9.8-4.8-10-23.5-55.1-33-55.1zM340.8 177c6.6 2.8 11.5 9.2 22.7 22.1 2-1.4 7.5-5.2 7.5-8.6 0-4.9-11.8-13.2-13.2-23 11.2-5.7 25.2-6 37.6-8.9 68.1-16.4 116.3-52.9 146.8-116.7C548.3 29.3 554 16.1 554.6 2l-2 2.6c-28.4 50-33 63.2-81.3 100-31.9 24.4-69.2 40.2-106.6 54.6l-6.3-.3v-21.8c-19.6 1.6-19.7-14.6-31.6-23-18.7 20.6-31.6 40.8-58.9 51.1-12.7 4.8-19.6 10-25.9 21.8 34.9-16.4 91.2-13.5 98.8-10zM555.5 0l-.6 1.1-.3.9.6-.6zm-59.2 382.1c-33.9-56.9-75.3-118.4-150-115.5l-.3-6c-1.1-13.5 32.8 3.2 35.1-31l-14.4 7.2c-19.8-45.7-8.6-54.3-65.5-54.3-14.7 0-26.7 1.7-41.4 4.6 2.9 18.6 2.2 36.7-10.9 50.3l19.5 5.5c-1.7 3.2-2.9 6.3-2.9 9.8 0 21 42.8 2.9 42.8 33.6 0 18.4-36.8 60.1-54.9 60.1-8 0-53.7-50-53.4-60.1l.3-4.6 52.3-11.5c13-2.6 12.3-22.7-2.9-22.7-3.7 0-43.1 9.2-49.4 10.6-2-5.2-7.5-14.1-13.8-14.1-3.2 0-6.3 3.2-9.5 4-9.2 2.6-31 2.9-21.5 20.1L15.9 298.5c-5.5 1.1-8.9 6.3-8.9 11.8 0 6 5.5 10.9 11.5 10.9 8 0 131.3-28.4 147.4-32.2 2.6 3.2 4.6 6.3 7.8 8.6 20.1 14.4 59.8 85.9 76.4 85.9 24.1 0 58-22.4 71.3-41.9 3.2-4.3 6.9-7.5 12.4-6.9.6 13.8-31.6 34.2-33 43.7-1.4 10.2-1 35.2-.3 41.1 26.7 8.1 52-3.6 77.9-2.9 4.3-21 10.6-41.9 9.8-63.5l-.3-9.5c-1.4-34.2-10.9-38.5-34.8-58.6-1.1-1.1-2.6-2.6-3.7-4 2.2-1.4 1.1-1 4.6-1.7 88.5 0 56.3 183.6 111.5 229.9 33.1-15 72.5-27.9 103.5-47.2-29-25.6-52.6-45.7-72.7-79.9zm-196.2 46.1v27.2l11.8-3.4-2.9-23.8zm-68.7-150.4l24.1 61.2 21-13.8-31.3-50.9zm84.4 154.9l2 12.4c9-1.5 58.4-6.6 58.4-14.1 0-1.4-.6-3.2-.9-4.6-26.8 0-36.9 3.8-59.5 6.3z"/></svg>')
}
.md-typeset .admonition.pied-piper,
.md-typeset details.pied-piper {
border-color: rgb(43, 155, 70);
}
.md-typeset .pied-piper > .admonition-title,
.md-typeset .pied-piper > summary {
background-color: rgba(43, 155, 70, 0.1);
border-color: rgb(43, 155, 70);
}
.md-typeset .pied-piper > .admonition-title::before,
.md-typeset .pied-piper > summary::before {
background-color: rgb(43, 155, 70);
-webkit-mask-image: var(--md-admonition-icon--pied-piper);
mask-image: var(--md-admonition-icon--pied-piper);
}
```
=== ":octicons-file-code-16: mkdocs.yml"
``` yaml
extra_css:
- stylesheets/extra.css
```
_Result_:
@ -528,6 +481,5 @@ _Result_:
nulla. Curabitur feugiat, tortor non consequat finibus, justo purus auctor
massa, nec semper lorem quam in massa.
[16]: https://github.com/squidfunk/mkdocs-material/tree/master/material/.icons
[17]: ../customization.md#additional-css
[18]: icons-emojis.md#with-animations
[custom icons]: https://github.com/squidfunk/mkdocs-material/tree/master/material/.icons
[additional style sheet]: ../customization.md#additional-css

55
docs/reference/buttons.md
View File

@ -10,74 +10,75 @@ useful for documents or landing pages with dedicated _call-to-actions_.
## Configuration
### Attribute List
The [Attribute List][1] extension, which is part of the standard Markdown
library, allows to __add HTML attributes and CSS classes to Markdown elements__,
and can be enabled via `mkdocs.yml`
This configuration allows to add attributes to all inline- and block-level
elements with a simple syntax, turning any link into a button. Add the
following lines to `mkdocs.yml`:
``` yaml
markdown_extensions:
- attr_list
```
[1]: https://python-markdown.github.io/extensions/attr_list/
See additional configuration options:
- [Attribute Lists]
[Attribute Lists]: ../setup/extensions/python-markdown.md#attribute-lists
## Usage
### Adding buttons
When the [Attribute List][2] extension is enabled, any clickable element can be
converted into a button by adding the `.md-button` CSS class, which will receive
the selected [primary color][3].
In order to render a link as a button, suffix it with curly braces and add the
`.md-button` class selector to it. The button will receive the selected
[primary color] and [accent color] if active.
_Example_:
``` markdown
[Subscribe to our mailing list](#){ .md-button }
[Subscribe to our newsletter](#){ .md-button }
```
_Result_:
[Subscribe to our mailing list][4]{ .md-button }
[Subscribe to our newsletter][Demo]{ .md-button }
[2]: #attribute-list
[3]: ../setup/changing-the-colors.md#primary-color
[4]: javascript:alert$.next("Done!")
[primary color]: ../setup/changing-the-colors.md#primary-color
[accent color]: ../setup/changing-the-colors.md#accent-color
[Demo]: javascript:alert$.next("Demo")
### Adding primary buttons
If you want to display a filled, primary button (like on the [landing page][5]
of Material for MkDocs), add both the `.md-button` and `.md-button--primary`
CSS classes.
If you want to display a filled, primary button (like on the [landing page]
of Material for MkDocs), add both, the `.md-button` and `.md-button--primary`
CSS class selectors.
_Example_:
``` markdown
[Subscribe to our mailing list](#){ .md-button .md-button--primary }
[Subscribe to our newsletter](#){ .md-button .md-button--primary }
```
_Result_:
[Subscribe to our mailing list][4]{ .md-button .md-button--primary }
[Subscribe to our newsletter][Demo]{ .md-button .md-button--primary }
[5]: ../index.md
[landing page]: ../index.md
### Adding icon buttons
Of course, icons can be added to both types of buttons by using the [regular
icon syntax][6] and referencing a valid path to [any icon bundled with the
theme][7].
Of course, icons can be added to all types of buttons by using the [icon syntax]
together with any valid icon shortcode, which can be easily found with a few keystrokes through the [icon search].
_Example_:
``` markdown
[Submit :fontawesome-solid-paper-plane:](#){ .md-button .md-button--primary }
[Send :fontawesome-solid-paper-plane:](#){ .md-button .md-button--primary }
```
_Result_:
[Submit :fontawesome-solid-paper-plane:][4]{ .md-button .md-button--primary }
[Send :fontawesome-solid-paper-plane:][Demo]{ .md-button .md-button--primary }
[6]: icons-emojis.md#using-icons
[7]: icons-emojis.md#search
[icon syntax]: icons-emojis.md#using-icons
[icon search]: icons-emojis.md#search

504
docs/reference/code-blocks.md
View File

@ -6,191 +6,89 @@ template: overrides/main.html
Code blocks and examples are an essential part of technical project
documentation. Material for MkDocs provides different ways to set up syntax
highlighting for code blocks, either during build time using [Pygments][1] or
highlighting for code blocks, either during build time using [Pygments] or
during runtime using a JavaScript syntax highlighter.
[1]: https://pygments.org
[Pygments]: https://pygments.org
## Configuration
### Highlight
This configuration enables syntax highlighting on code blocks and inline code
blocks, and allows to include source code directly from other files. Add the
following lines to `mkdocs.yml`:
[:octicons-file-code-24: Source][2] · [:octicons-workflow-24: Extension][3] ·
:octicons-zap-24: Supersedes: [CodeHilite][4]
The [Highlight][3] extension, which is part of [Python Markdown Extensions][5],
integrates with Material for MkDocs and provides several options for
configuring syntax highlighting of code blocks:
`use_pygments`{ #use-pygments }
: :octicons-milestone-24: Default: `true` – This option allows to control
whether highlighting should be carried out during build time by
[Pygments][1] or runtime with a JavaScript highlighter. Remember to add the
necessary [additional stylesheets][6] and [JavaScript][7] if you want to
use the latter:
=== "Pygments"
``` yaml
markdown_extensions:
``` yaml
markdown_extensions:
- pymdownx.highlight
- pymdownx.superfences
```
=== "JavaScript"
``` yaml
markdown_extensions:
- pymdownx.highlight:
use_pygments: false
```
??? example "Syntax highlighting with Highlight.js"
[Highlight.js][8] can be integrated by creating an [additional
JavaScript][7] file initializing the highlighter and including the
respective stylesheet and JavaScript from a [CDN][9] serving
Highlight.js in `mkdocs.yml`:
=== "`docs/javascripts/config.js`"
``` js
document$.subscribe(() => {
hljs.highlightAll()
})
```
=== "`mkdocs.yml`"
``` yaml
extra_javascript:
- https://cdnjs.cloudflare.com/ajax/libs/highlight.js/10.7.2/highlight.min.js
- javascripts/config.js
extra_css:
- https://cdnjs.cloudflare.com/ajax/libs/highlight.js/10.7.2/styles/default.min.css
```
Note that Highlight.js has no affiliation with the Highlight extension.
`linenums`{ #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
code blocks, consult the section on [adding line numbers][10] later in this
document, which also contains some tips on working with line numbers:
``` yaml
markdown_extensions:
- pymdownx.highlight:
linenums: true
```
`linenums_style`{ #linenums-style }
: :octicons-milestone-24: Default: `table` – The Highlight extension provides
three ways to add line numbers, all of which are supported by Material for
MkDocs. While `table` wraps a code block in a table, `inline` and
`pymdownx-inline` render line numbers as part of the line itself:
``` yaml
markdown_extensions:
- pymdownx.highlight:
linenums_style: pymdownx-inline
```
Note that `inline` will put line numbers next to the actual code, which
means that they will be included when selecting text with the cursor or
copying a code block to the clipboard. Thus, the usage of `table` or
`pymdownx-inline` is recommended.
_Material for MkDocs doesn't provide official support for the other options of
this extension, so they may be supported but might yield unexpected results.
Use them at your own risk._
[2]: https://github.com/squidfunk/mkdocs-material/blob/master/src/assets/stylesheets/main/extensions/pymdownx/_highlight.scss
[3]: https://facelessuser.github.io/pymdown-extensions/extensions/highlight/
[4]: https://python-markdown.github.io/extensions/code_hilite/
[5]: https://facelessuser.github.io/pymdown-extensions/
[6]: ../customization.md#additional-css
[7]: ../customization.md#additional-javascript
[8]: https://highlightjs.org/
[9]: https://cdnjs.com/libraries/highlight.js/
[10]: #adding-line-numbers
### InlineHilite
[:octicons-file-code-24: Source][2] · [:octicons-workflow-24: Extension][11]
The [InlineHilite][11] extension, which is part of [Python Markdown
Extensions][5] also integrates with Material for MkDocs and adds support for
__syntax highlighting of inline code blocks__. It's built on top of the
[Highlight][3] extension and can be enabled via `mkdocs.yml`:
``` yaml
markdown_extensions:
- pymdownx.inlinehilite
```
See the section on [inline code blocks][12] for usage information.
[11]: https://facelessuser.github.io/pymdown-extensions/extensions/inlinehilite/
[12]: #highlighting-inline-code-blocks
### Keys
[:octicons-file-code-24: Source][13] · [:octicons-workflow-24: Extension][14]
The [Keys][14] extension, which is part of [Python Markdown Extensions][5],
allows for inserting __keyboard keys__, e.g. ++ctrl+alt+delete++ , and
can be enabled via `mkdocs.yml`:
``` yaml
markdown_extensions:
- pymdownx.keys
```
[13]: https://github.com/squidfunk/mkdocs-material/blob/master/src/assets/stylesheets/main/extensions/pymdownx/_keys.scss
[14]: https://facelessuser.github.io/pymdown-extensions/extensions/keys/
### SuperFences
The [SuperFences][15] extension, which is also part of [Python Markdown
Extensions][5], allows for the __nesting of code blocks inside other blocks__,
and is therefore strongly recommended:
``` yaml
markdown_extensions:
- pymdownx.superfences
```
[15]: https://facelessuser.github.io/pymdown-extensions/extensions/superfences/
### Snippets
The [Snippets][16] extension, which is also part of [Python Markdown
Extensions][5], allows to __insert content from other files__ or other, regular
content, and can be enabled via `mkdocs.yml`:
``` yaml
markdown_extensions:
- pymdownx.snippets
```
[16]: https://facelessuser.github.io/pymdown-extensions/extensions/snippets/
See additional configuration options:
- [Highlight]
- [InlineHilite]
- [SuperFences]
- [Snippets]
[Highlight]: ../setup/extensions/python-markdown-extensions.md#highlight
[InlineHilite]: ../setup/extensions/python-markdown-extensions.md#inlinehilite
[SuperFences]: ../setup/extensions/python-markdown-extensions.md#superfences
[Snippets]: ../setup/extensions/python-markdown-extensions.md#snippets
### Code annotations
[:octicons-heart-fill-24:{ .mdx-heart } Insiders][Insiders]{ .mdx-insiders } ·
[:octicons-tag-24: insiders-2.2.0][Insiders] ·
:octicons-unlock-24: Feature flag ·
:octicons-beaker-24: Experimental
Code annotations offer a comfortable and friendly way to attach arbitrary
content to specific sections of code blocks by adding numeric markers in block
and inline comments in the language of the code block. Add the following to
`mkdocs.yml` to enable them globally:
``` yaml
theme:
features:
- content.code.annotate # (1)
```
1. :man_raising_hand: I'm a code annotation! I can contain `code`, __formatted
text__, images, ... basically anything that can be expressed in Markdown.
??? info "Enabling code annotations for a specific code block"
If you don't want to enable code annotations globally, because you don't
like the automatic inlining behavior, you can enable them for a specific
code block by using a slightly different syntax based on the
[Attribute Lists] extension:
```` yaml
``` { .yaml .annotate }
# Code block content
```
````
Note that the language shortcode which has to come first must now also be
prefixed by a `.`.
[Insiders]: ../insiders/index.md
[Attribute Lists]: ../setup/extensions/python-markdown.md#attribute-lists
## Usage
This section discusses how to use different syntax highlighting features with
[Pygments][1] – the default highlighter – so they don't apply when using
[Pygments] – the default highlighter – so they don't apply when using
a JavaScript syntax highlighter.
### Specifying the language
Code blocks must be enclosed with two separate lines containing three backticks.
To add code highlighting to those blocks, add the language short name directly
after the opening block. See the [list of available lexers][17] to find the
short name for a given language.
To add syntax highlighting to those blocks, add the language shortcode directly
after the opening block. See the [list of available lexers] to find the
shortcode for a given language.
_Example_:
@ -206,117 +104,50 @@ _Result_:
import tensorflow as tf
```
[17]: https://pygments.org/docs/lexers/
[list of available lexers]: https://pygments.org/docs/lexers/
### Adding annotations
[:octicons-file-code-24: Source][18] ·
:octicons-beaker-24: Experimental ·
[:octicons-heart-fill-24:{ .mdx-heart } Insiders only][18]{ .mdx-insiders }
Code annotations can be placed anywhere in a code block where a comment for the
language of the block can be placed, e.g. for JavaScript in `#!js // ...` and
`#!js /* ... */`, for YAML in `#!yaml # ...`, etc.[^1]
Annotations offer a comfortable and friendly way to attach explanations to
arbitrary sections of code blocks by adding simple markers within block/inline
comments that refer to items of a list following the code block, i.e. `(1)`,
`(2)`, etc. Material for MkDocs detaches the list from the flow of the document,
injects the content of each list item into a tooltip, and links each list marker
to the corresponding tooltip.
[^1]:
Code annotations require syntax highlighting with [Pygments] – they're
currently not compatible with JavaScript syntax highlighters. Support will
be added at a later point, allowing to always place code annotations at the
end of lines.
In order to opt-in to annotation support, a slightly different syntax is
required – just add the respective [language short code][17] and the `.annotate`
class, after the three backticks. Alternatively, if you want to enable annotations
globally, add the following to `mkdocs.yml`:
_Example_:
```` markdown
``` yaml
theme:
features:
- content.code.annotate # (1)
```
1. :man_raising_hand: I'm a code annotation! I can contain `code`, __formatted
text__, images, ... basically anything that can be expressed in Markdown.
````
_Result_:
``` yaml
theme:
features:
- content.code.annotate
- content.code.annotate # (1)
```
Note that annotations can be __placed anywhere__ in a code block where a comment
for the language can be placed, which for JavaScript is `// (1)` and
`/* (2) */`, for Yaml `# (3)`, etc.
_Example_:
```` markdown
``` js
document$.subscribe(function() { // (1)
var tables = document.querySelectorAll(/* (2) */ "article table")
tables.forEach(function(table) {
new Tablesort(table)
})
})
```
1. ...
2. ...
````
_Result_:
``` js
document$.subscribe(function() { // (1)
var tables = document.querySelectorAll(/* (2) */ "article table")
tables.forEach(function(table) {
new Tablesort(table) // (3)
})
})
```
1. Annotations can contain __arbitrary content__ which is shown when the marker
is focussed, including any kind of formatting, links, admonitions, details,
and even diagrams:
``` mermaid
graph LR
A[I'm] --> B{a} --> C[diagram];
```
:octicons-light-bulb-16:
**Tip:** You can use ++tab++ to navigate annotations.
2. Annotations can be __placed anywhere__ in a code block were a comment for the
underlying language can be placed.
=== "Python"
``` python
# (1)
```
=== "JavaScript"
``` js
// (2)
/* (2) */
```
=== "Lua"
``` lua
-- (3)
```
_We're working on a solution for languages without comments, which will be
available shortly._
1. Of course, this can be combined with [line numbers][10], highlighting and
all other code block related features.
_Annotations require syntax highlighting with [Pygments][26] – they're currently
not compatible with other JavaScript-based syntax highlighters. Support may be
added later on._
[18]: ../insiders/index.md
[19]: ../assets/screenshots/annotations.png
[20]: https://squidfunk.github.io/mkdocs-material-insiders/reference/code-blocks/#adding-annotations
1. :man_raising_hand: I'm a code annotation! I can contain `code`, __formatted
text__, images, ... basically anything that can be expressed in Markdown.
### Adding line numbers
Line numbers can be added to a code block by using the `linenums="<start>"`
option directly after the short name, whereas `<start>` represents the starting
option directly after the shortcode, whereas `<start>` represents the starting
line number. A code block can start from a line number other than `1`, which
allows splitting large code blocks for readability.
allows to split large code blocks for readability.
_Example_:
@ -343,60 +174,65 @@ def bubble_sort(items):
### Highlighting specific lines
Specific lines can be highlighted by passing the line numbers to the `hl_lines`
argument placed right after the language short name. Note that line counts start
at `1`, regardless of the starting line number specified as part of `linenums`.
argument placed right after the language shortcode. Note that line counts start
at `1`, regardless of the starting line number specified as part of
[`linenums`][Adding line numbers].
_Example_:
=== "Line numbers"
```` markdown
``` python hl_lines="2 3"
def bubble_sort(items):
_Example_:
```` markdown
``` python hl_lines="2 3"
def bubble_sort(items):
for i in range(len(items)):
for j in range(len(items) - 1 - i):
if items[j] > items[j + 1]:
items[j], items[j + 1] = items[j + 1], items[j]
```
````
```
````
_Result_:
_Result_:
``` python hl_lines="2 3"
def bubble_sort(items):
``` python linenums="1" hl_lines="2 3"
def bubble_sort(items):
for i in range(len(items)):
for j in range(len(items) - 1 - i):
if items[j] > items[j + 1]:
items[j], items[j + 1] = items[j + 1], items[j]
```
```
Line ranges can also be used for conveniently specifying multiple lines.
=== "Line number ranges"
_Example_:
_Example_:
```` markdown
``` python hl_lines="2-5"
def bubble_sort(items):
```` markdown
``` python hl_lines="2-5"
def bubble_sort(items):
for i in range(len(items)):
for j in range(len(items) - 1 - i):
if items[j] > items[j + 1]:
items[j], items[j + 1] = items[j + 1], items[j]
```
````
```
````
_Result_:
_Result_:
``` python hl_lines="2-5"
def bubble_sort(items):
``` python linenums="1" hl_lines="2-5"
def bubble_sort(items):
for i in range(len(items)):
for j in range(len(items) - 1 - i):
if items[j] > items[j + 1]:
items[j], items[j + 1] = items[j + 1], items[j]
```
```
[Adding line numbers]: #adding-line-numbers
### Highlighting inline code blocks
When [InlineHilite][21] is enabled, inline code blocks can be highlighted by
prefixing them with a shebang-like sequence, i.e. `#!`, directly followed by
the [language short name][17].
When [InlineHilite] is enabled, syntax highlighting can be applied to inline
code blocks by prefixing them with a shebang, i.e. `#!`, directly followed by
the corresponding [language shortcode][list of available lexers].
_Example_:
@ -408,33 +244,11 @@ _Result_:
The `#!python range()` function is used to generate a sequence of numbers.
[21]: #inlinehilite
### Adding keyboard keys
When [Keys][22] is enabled, keyboard keys can be rendered with a simple syntax.
Consult the [Python Markdown Extensions][14] documentation to learn about all
available key codes.
_Example_:
``` markdown
++ctrl+alt+del++
```
_Result_:
++ctrl+alt+del++
[22]: #keys
### Embedding external files
_Also known as transcludes or file transclusion in [MultiMarkdown][23]_.
When [Snippets][24] is enabled, content from other files can be embedded, which
is especially useful to reference and embed the contents of source files
directly into your project documentation.
When [Snippets] is enabled, content from other files (including source files)
can be embedded by using the [`--8<--` notation][Snippets notation] directly
from within a code block:
_Example_:
@ -450,23 +264,15 @@ _Result_:
last 4 years
```
Note that [Snippets][24] is not limited to code blocks, but can be used anywhere
from a document to move repeating content to separate files, which is also
explained in the [official documentation][16].
[23]: https://fletcher.github.io/MultiMarkdown-5/transclusion.html
[24]: #snippets
[Snippets notation]: https://facelessuser.github.io/pymdown-extensions/extensions/snippets/#snippets-notation
## Customization
### Custom syntax theme
[:octicons-file-code-24: Source][25] ·
:octicons-mortar-board-24: Difficulty: _easy_
If [Pygments][26] is used, Material for MkDocs provides the [styles for code
blocks][25], which are built with a custom and well-balanced palette that works
equally well for both [color schemes][27]:
If [Pygments] is used, Material for MkDocs provides the [styles for code blocks]
[colors], which are built with a custom and well-balanced palette that works
equally well for both [color schemes]:
- :material-checkbox-blank-circle:{ style="color: var(--md-code-hl-number-color) " } `--md-code-hl-number-color`
- :material-checkbox-blank-circle:{ style="color: var(--md-code-hl-special-color) " } `--md-code-hl-special-color`
@ -488,29 +294,45 @@ Code block foreground, background and line highlight colors are defined via:
- :material-checkbox-blank-circle:{ style="color: var(--md-code-hl-color) " } `--md-code-hl-color`
Let's say you want to change the color of `#!js "strings"`. While there are
several [types of string tokens][28], Material for MkDocs assigns a single color
to most of them.
several [types of string tokens], they use the same color. You can assign
a new color by using an [additional style sheet]:
Create an [additional stylesheet][6], and add:
=== ":octicons-file-code-16: docs/stylesheets/extra.css"
``` css
:root > * {
``` css
:root > * {
--md-code-hl-string-color: #0FF1CE;
}
```
}
```
If you want to tweak a specific type of string, i.e. ``#!js `backticks` ``, you
can lookup the specific class name in the [syntax theme definition][29], and
override it as part of your additional stylesheet:
=== ":octicons-file-code-16: mkdocs.yml"
``` css
.highlight .sb {
``` yaml
extra_css:
- stylesheets/extra.css
```
If you want to tweak a specific type of string, e.g. ``#!js `backticks` ``, you
can lookup the specific CSS class name in the [syntax theme definition], and
override it as part of your [additional style sheet]:
=== ":octicons-file-code-16: docs/stylesheets/extra.css"
``` css
.highlight .sb {
color: #0FF1CE;
}
```
}
```
[25]: https://github.com/squidfunk/mkdocs-material/blob/master/src/assets/stylesheets/main/_colors.scss#
[26]: #use-pygments
[27]: ../setup/changing-the-colors.md#color-scheme
[28]: https://pygments.org/docs/tokens/#literals
[29]: https://github.com/squidfunk/mkdocs-material/blob/master/src/assets/stylesheets/main/extensions/pymdownx/_highlight.scss
=== ":octicons-file-code-16: mkdocs.yml"
``` yaml
extra_css:
- stylesheets/extra.css
```
[colors]: https://github.com/squidfunk/mkdocs-material/blob/master/src/assets/stylesheets/main/_colors.scss
[color schemes]: ../setup/changing-the-colors.md#color-scheme
[types of string tokens]: https://pygments.org/docs/tokens/#literals
[additional style sheet]: ../customization.md#additional-css
[syntax theme definition]: https://github.com/squidfunk/mkdocs-material/blob/master/src/assets/stylesheets/main/extensions/pymdownx/_highlight.scss

130
docs/reference/content-tabs.md
View File

@ -11,53 +11,59 @@ grouping code blocks and other content.
## Configuration
### Tabbed
[:octicons-file-code-24: Source][1] · [:octicons-workflow-24: Extension][2]
The [Tabbed][2] extension, which is part of [Python Markdown Extensions][3],
integrates with Material for MkDocs and can be enabled via `mkdocs.yml`:
=== "Modern"
``` yaml
markdown_extensions:
- pymdownx.tabbed:
alternate_style: true # (1)
```
1. As of 7.3.1, support was added for the new [`alternate_style`][12] flag,
which has much better behavior on smaller screen sizes, as content tabs
are now scrollable and will overflow instead of break across multiple
lines.
__The legacy style will be deprecated with the next major release.__
[12]: https://facelessuser.github.io/pymdown-extensions/extensions/tabbed/#alternate-style
=== "Legacy"
``` yaml
markdown_extensions:
- pymdownx.tabbed
```
[1]: https://github.com/squidfunk/mkdocs-material/blob/master/src/assets/stylesheets/main/extensions/pymdownx/_tabbed.scss
[2]: https://facelessuser.github.io/pymdown-extensions/extensions/tabbed/
[3]: https://facelessuser.github.io/pymdown-extensions/
### SuperFences
The [SuperFences][4] extension, which is also part of [Python Markdown
Extensions][3], allows for the __nesting of code and content blocks inside
tabs__, and is therefore strongly recommended:
This configuration enables content tabs, and allows to nest arbitrary content
inside content tabs, including code blocks and ... more content tabs! Add the
following lines to `mkdocs.yml`:
``` yaml
markdown_extensions:
- pymdownx.superfences
- pymdownx.tabbed:
alternate_style: true
```
[4]: https://facelessuser.github.io/pymdown-extensions/extensions/superfences/
See additional configuration options:
- [SuperFences]
- [Tabbed]
[SuperFences]: ../setup/extensions/python-markdown-extensions.md#superfences
[Tabbed]: ../setup/extensions/python-markdown-extensions.md#tabbed
### Linked content tabs
[:octicons-heart-fill-24:{ .mdx-heart } Insiders][Insiders]{ .mdx-insiders } ·
[:octicons-tag-24: insiders-2.9.0][Insiders] ·
:octicons-unlock-24: Feature flag ·
:octicons-beaker-24: Experimental
When enabled, all content tabs across the whole documentation site will be
linked and switch to the same label when the user clicks on a tab. Add the
following lines to `mkdocs.yml`:
``` yaml
theme:
features:
- content.tabs.link
```
Content tabs are linked based on their label, not offset. This means that all
tabs with the same label will be activated when a user clicks a content tab
regardless of order inside a container. Furthermore, this feature is fully
integrated with [instant loading] and persisted across page loads.
=== ":octicons-check-circle-fill-16: Enabled"
[![content.tabs.link enabled]][content.tabs.link enabled]
=== ":octicons-skip-16: Disabled"
[![content.tabs.link disabled]][content.tabs.link disabled]
[Insiders]: ../insiders/index.md
[instant loading]: ../setup/setting-up-navigation.md#instant-loading
[content.tabs.link enabled]: ../assets/screenshots/content-tabs-link.png
[content.tabs.link disabled]: ../assets/screenshots/content-tabs.png
## Usage
@ -153,45 +159,11 @@ _Result_:
2. Donec vitae suscipit est
3. Nulla tempor lobortis orci
### Linking content tabs
[:octicons-file-code-24: Source][5] ·
:octicons-beaker-24: Experimental ·
[:octicons-heart-fill-24:{ .mdx-heart } Insiders only][5]{ .mdx-insiders }
When _linking_ is enabled, all content tabs on a page will be linked and show
the same active tab when the user clicks on a label. Add the following lines
to `mkdocs.yml`:
``` yaml
theme:
features:
- content.tabs.link
```
Content tabs are linked based on their label, not offset. This means that all
tabs with the same label will be activated when a user clicks a content tab
regardless of order inside a container. Furthermore, this feature is fully
integrated with [instant loading][6] and persisted across page loads.
=== "With linking"
[![With linking][7]][7]
=== "Without linking"
[![Without linking][8]][8]
[5]: ../insiders/index.md
[6]: ../setup/setting-up-navigation.md#instant-loading
[7]: ../assets/screenshots/content-tabs-link.png
[8]: ../assets/screenshots/content-tabs.png
### Embedded content
When [SuperFences][9] is enabled, content tabs can contain arbitrary nested
When [SuperFences] is enabled, content tabs can contain arbitrary nested
content, including further content tabs, and can be nested in other blocks like
[admonitions][10], [details][11] or blockquotes:
[admonitions] or blockquotes:
_Example_:
@ -267,6 +239,4 @@ _Result_:
2. Donec vitae suscipit est
3. Nulla tempor lobortis orci
[9]: #superfences
[10]: admonitions.md
[11]: admonitions.md#details
[admonitions]: admonitions.md

50
docs/reference/data-tables.md
View File

@ -6,15 +6,27 @@ template: overrides/main.html
Material for MkDocs defines default styles for data tables – an excellent way
of rendering tabular data in project documentation. Furthermore, customizations
like [sortable tables][1] can be achieved with a third-party library and some
[additional JavaScript][2].
like [sortable tables] can be achieved with a third-party library and some
[additional JavaScript].
[1]: #sortable-tables
[2]: ../customization.md#additional-javascript
[sortable tables]: #sortable-tables
[additional JavaScript]: ../customization.md#additional-javascript
## Configuration
None.
This configuration enables Markdown table support, which should normally be
enabled by default, but to be sure, add the following lines to `mkdocs.yml`:
``` yaml
markdown_extensions:
- tables
```
See additional configuration options:
- [Tables]
[Tables]: ../setup/extensions/python-markdown.md#tables
## Usage
@ -22,7 +34,7 @@ None.
Data tables can be used at any position in your project documentation and can
contain arbitrary Markdown, including inline code blocks, as well as [icons and
emojis][3].
emojis].
_Example_:
@ -42,12 +54,12 @@ _Result_:
| `PUT` | :material-check-all: Update resource |
| `DELETE` | :material-close: Delete resource |
[3]: icons-emojis.md
[icons and emojis]: icons-emojis.md
### Column alignment
If you want to align a specific column to the `left`, `center` or `right`, you
can use the [regular Markdown syntax][4] placing `:` characters at the beginning
can use the [regular Markdown syntax] placing `:` characters at the beginning
and/or end of the divider.
=== "Left"
@ -110,17 +122,17 @@ and/or end of the divider.
| `PUT` | :material-check-all: Update resource |
| `DELETE` | :material-close: Delete resource |
[4]: https://www.markdownguide.org/extended-syntax/#tables
[regular Markdown syntax]: https://www.markdownguide.org/extended-syntax/#tables
## Customization
### Sortable tables
If you want to make data tables sortable, you can add [tablesort][5], which is
If you want to make data tables sortable, you can add [tablesort], which is
natively integrated with Material for MkDocs and will also work with [instant
loading][6] via [additional JavaScript][2]:
loading] via [additional JavaScript]:
=== "`docs/javascripts/tables.js`"
=== ":octicons-file-code-16: docs/javascripts/tablesort.js"
``` js
document$.subscribe(function() {
@ -131,17 +143,17 @@ loading][6] via [additional JavaScript][2]:
})
```
=== "`mkdocs.yml`"
=== ":octicons-file-code-16: mkdocs.yml"
``` yaml
extra_javascript:
- https://cdnjs.cloudflare.com/ajax/libs/tablesort/5.2.1/tablesort.min.js
- javascripts/tables.js
- javascripts/tablesort.js
```
_Note that [tablesort][5] provides alternative comparison implementations like
numbers, dates, filesizes and month names. See the official documentation for
more information._
Note that [tablesort] provides alternative comparison implementations like
numbers, filesizes, dates and month names. See the [tablesort documentation]
[tablesort] for more information.
_Example_:
@ -167,5 +179,5 @@ _Result_:
new Tablesort(tables.item(tables.length - 1));
</script>
[5]: http://tristen.ca/tablesort/demo/
[6]: ../setup/setting-up-navigation.md#instant-loading
[tablesort]: http://tristen.ca/tablesort/demo/
[instant loading]: ../setup/setting-up-navigation.md#instant-loading

83
docs/reference/diagrams.md
View File

@ -6,22 +6,20 @@ template: overrides/main.html
Diagrams help to communicate complex relationships and interconnections between
different technical components, and are a great addition to project
documentation. Material for MkDocs integrates with [Mermaid.js][1], a very
documentation. Material for MkDocs integrates with [Mermaid.js], a very
popular and flexible solution for drawing diagrams.
[1]: https://mermaid-js.github.io/mermaid/
[Mermaid.js]: https://mermaid-js.github.io/mermaid/
## Configuration
### SuperFences
[:octicons-heart-fill-24:{ .mdx-heart } Insiders][Insiders]{ .mdx-insiders } ·
[:octicons-tag-24: insiders-1.15.0][Insiders] ·
:octicons-beaker-24: Experimental
[:octicons-file-code-24: Source][2] ·
:octicons-beaker-24: Experimental ·
[:octicons-heart-fill-24:{ .mdx-heart } Insiders only][2]{ .mdx-insiders }
The [SuperFences][3] extension, which is part of [Python Markdown
Extensions][4], allows for adding __custom fences__, which can be used to
render [Mermaid.js][1] diagrams with zero effort:
This configuration enables native support for [Mermaid.js] diagrams. Material
for MkDocs will automatically initialize the JavaScript runtime when a page
includes a `mermaid` code block:
``` yaml
markdown_extensions:
@ -32,51 +30,28 @@ markdown_extensions:
format: !!python/name:pymdownx.superfences.fence_code_format
```
No further configuration is necessary. Material for MkDocs will automatically
load and initialize the [Mermaid.js][1] runtime when a page includes a [fenced
`mermaid` block][5]. Furthermore:
No further configuration is necessary. Advantages over a custom integration:
- [x] Works with [instant loading][6] without any additional effort
- [x] Works with [instant loading] without any additional effort
- [x] Diagrams automatically use fonts and colors defined in `mkdocs.yml`[^1]
- [x] Fonts and colors can be customized with [additional stylesheets][7]
- [x] Support for both, light and dark color schemes
_While it's also possible to integrate [Mermaid.js][1] using existing
third-party plugins[^2], the new native integration is recommended as it
ensures interoperability with all Material for MkDocs features._
- [x] Fonts and colors can be customized with [additional style sheets]
- [x] Support for both, light and dark color schemes – _try it on this page!_
[^1]:
While all [Mermaid.js][1] features should work out-of-the-box, Material for
MkDocs will currently adjust the fonts and colors for flow charts, sequence
diagrams, class diagams, state diagrams and entity relationship diagrams.
While all [Mermaid.js] features should work out-of-the-box, Material for
MkDocs will currently only adjust the fonts and colors for flowcharts,
sequence diagrams, class diagams, state diagrams and entity relationship
diagrams.
[^2]:
If you don't want to use the native integration, [mkdocs-mermaid2-plugin][8]
might be a good alternative. However, note that this plugin cannot be used
in conjunction with the [mkdocs-minify-plugin][9] and doesn't adapt to
dark mode.
[2]: ../insiders/index.md
[3]: https://facelessuser.github.io/pymdown-extensions/extensions/superfences/
[4]: https://facelessuser.github.io/pymdown-extensions/
[5]: #usage
[6]: ../setup/setting-up-navigation.md#instant-loading
[7]: ../customization.md#additional-css
[8]: https://github.com/fralau/mkdocs-mermaid2-plugin
[9]: https://github.com/byrnereese/mkdocs-minify-plugin
[Insiders]: ../insiders/index.md
[instant loading]: ../setup/setting-up-navigation.md#instant-loading
[additional style sheets]: ../customization.md#additional-css
## Usage
Mermaid diagrams are written as [code blocks][10] with the help of the
[SuperFences][11] extension. They must be enclosed with two separate lines
containing three backticks.
[10]: code-blocks.md
[11]: #superfences
### Using flowcharts
[Flowcharts][12] are diagrams that represent workflows or processes. The steps
[Flowcharts] are diagrams that represent workflows or processes. The steps
are rendered as nodes of various kinds and are connected by edges, describing
the necessary order of steps.
@ -104,11 +79,11 @@ graph LR
B ---->|No| E[Yay!];
```
[12]: https://mermaid-js.github.io/mermaid/#/flowchart
[Flowcharts]: https://mermaid-js.github.io/mermaid/#/flowchart
### Using sequence diagrams
[Sequence diagrams][13] describe a specific scenario as sequential interactions
[Sequence diagrams] describe a specific scenario as sequential interactions
between multiple objects or actors, including the messages that are exchanged
between those actors.
@ -142,11 +117,11 @@ sequenceDiagram
Bob-->>John: Jolly good!
```
[13]: https://mermaid-js.github.io/mermaid/#/sequenceDiagram
[Sequence diagrams]: https://mermaid-js.github.io/mermaid/#/sequenceDiagram
### Using state diagrams
[State diagrams][14] are a great tool to describe the behavior of a system,
[State diagrams] are a great tool to describe the behavior of a system,
decomposing it into a finite number of states, and transitions between those
states.
@ -194,11 +169,11 @@ stateDiagram-v2
}
```
[14]: https://mermaid-js.github.io/mermaid/#/stateDiagram
[State diagrams]: https://mermaid-js.github.io/mermaid/#/stateDiagram
### Using class diagrams
[Class diagrams][15] are central to object oriented programing, describing the
[Class diagrams] are central to object oriented programing, describing the
structure of a system by modelling entities as classes and relationships between
them.
@ -266,11 +241,11 @@ classDiagram
}
```
[15]: https://mermaid-js.github.io/mermaid/#/classDiagram
[Class diagrams]: https://mermaid-js.github.io/mermaid/#/classDiagram
### Using entity-relationship diagrams
An [entity-relationship diagram][16] is composed of entity types and specifies
An [entity-relationship diagram] is composed of entity types and specifies
relationships that exist between entities. It describes inter-related things in
a specific domain of knowledge.
@ -294,4 +269,4 @@ erDiagram
CUSTOMER }|..|{ DELIVERY-ADDRESS : uses
```
[16]: https://mermaid-js.github.io/mermaid/#/entityRelationshipDiagram
[entity-relationship diagram]: https://mermaid-js.github.io/mermaid/#/entityRelationshipDiagram

27
docs/reference/footnotes.md
View File

@ -4,19 +4,15 @@ template: overrides/main.html
# Footnotes
Footnotes are a great way to add references to supplemental or additional
information for a specific section of a document without interrupting the
document flow. Material for MkDocs provides the ability to insert inline
footnotes and render them at the bottom of the page.
Footnotes are a great way to add supplemental or additional information to a
specific word, phrase or sentence without interrupting the flow of a document.
Material for MkDocs provides the ability to define, reference and render
footnotes.
## Configuration
### Footnotes
[:octicons-file-code-24: Source][1] · [:octicons-workflow-24: Extension][2]
The [Footnotes][2] extension, which is part of the standard Markdown library,
adds the ability to add inline footnotes to a document and can be enabled via
This configuration adds the ability to define inline footnotes, which are then
rendered below all Markdown content of a document. Add the following lines to
`mkdocs.yml`:
``` yaml
@ -24,8 +20,11 @@ markdown_extensions:
- footnotes
```
[1]: https://github.com/squidfunk/mkdocs-material/blob/master/src/assets/stylesheets/main/extensions/markdown/_footnotes.scss
[2]: https://python-markdown.github.io/extensions/footnotes/
See additional configuration options:
- [Footnotes]
[Footnotes]: ../setup/extensions/python-markdown.md#footnotes
## Usage
@ -54,7 +53,7 @@ reference is automatically added.
#### on a single line
Short statements can be written on the same line.
Short footnotes can be written on the same line.
_Example_:
@ -83,7 +82,7 @@ _Example_:
_Result_:
[^2]:
[^2]:
Lorem ipsum dolor sit amet, consectetur adipiscing elit. Nulla et euismod
nulla. Curabitur feugiat, tortor non consequat finibus, justo purus
auctor massa, nec semper lorem quam in massa.

146
docs/reference/formatting.md
View File

@ -6,117 +6,42 @@ template: overrides/main.html
Material for MkDocs provides support for several HTML elements that can be used
to highlight sections of a document or apply specific formatting. Additionally,
[Critic Markup][1] is supported, adding the ability to display suggested changes
[Critic Markup] is supported, adding the ability to display suggested changes
for a document.
[1]: http://criticmarkup.com/
[Critic Markup]: https://github.com/CriticMarkup/CriticMarkup-toolkit
## Configuration
### Critic
[:octicons-file-code-24: Source][2] · [:octicons-workflow-24: Extension][3]
The [Critic][3] extension, which is part of [Python Markdown Extensions][4],
allows for the __usage of [Critic Markup][1] to highlight changes__ in a
document, and can be enabled via `mkdocs.yml`:
This configuration enables support for keyboard keys, tracking changes in
documents, defining sub- and superscript and highlighting text. Add the
following lines to `mkdocs.yml`:
``` yaml
markdown_extensions:
- pymdownx.critic
```
The following options are supported:
`mode`{ #mode }
: :octicons-milestone-24: Default: `view` – This option defines how the markup
should be parsed, i.e. whether to just `view` all suggest changes, or
alternatively `accept` or `reject` them:
=== "View changes"
``` yaml
markdown_extensions:
- pymdownx.critic:
mode: view
```
=== "Accept changes"
``` yaml
markdown_extensions:
- pymdownx.critic:
mode: accept
```
=== "Reject changes"
``` yaml
markdown_extensions:
- pymdownx.critic:
mode: reject
```
[2]: https://github.com/squidfunk/mkdocs-material/blob/master/src/assets/stylesheets/main/extensions/pymdownx/_critic.scss
[3]: https://facelessuser.github.io/pymdown-extensions/extensions/critic/
[4]: https://facelessuser.github.io/pymdown-extensions/
### BetterEm
The [BetterEm][5] extension, which is part of [Python Markdown Extensions][4],
improves the handling of Markup to emphasize text (e.g. __bold__ and _italic_),
and can be enabled via `mkdocs.yml`:
``` yaml
markdown_extensions:
- pymdownx.betterem:
smart_enable: all
```
[5]: https://facelessuser.github.io/pymdown-extensions/extensions/betterem/
### Caret, Mark & Tilde
The [Caret][6], [Mark][7] and [Tilde][8] extensions, which are part of [Python
Markdown Extensions][4], allow for the __highlighting of text__, as well as
__handling sub- and superscripts__:
``` yaml
markdown_extensions:
- pymdownx.caret
- pymdownx.keys
- pymdownx.mark
- pymdownx.tilde
```
[6]: https://facelessuser.github.io/pymdown-extensions/extensions/caret/
[7]: https://facelessuser.github.io/pymdown-extensions/extensions/mark/
[8]: https://facelessuser.github.io/pymdown-extensions/extensions/tilde/
See additional configuration options:
### SmartSymbols
- [Critic]
- [Caret, Mark & Tilde]
- [Keys]
The [SmartSymbols][9] extension, which is also part of [Python Markdown
Extensions][4], __converts special characters into their corresponding
symbols__, and can be enabled via `mkdocs.yml`:
``` yaml
markdown_extensions:
- pymdownx.smartsymbols
```
See the [official documentation][9] for a list of supported symbols.
[9]: https://facelessuser.github.io/pymdown-extensions/extensions/smartsymbols/
[Critic]: ../setup/extensions/python-markdown-extensions.md#critic
[Caret, Mark & Tilde]: ../setup/extensions/python-markdown-extensions.md#caret-mark-tilde
[Keys]: ../setup/extensions/python-markdown-extensions.md#keys
## Usage
### Highlighting changes
When [Critic][10] is enabled, [Critic Markup][1] can be used, which adds the
ability to _highlight suggested changes_, as well as add _inline comments_ to a
document:
[10]: #critic
When [Critic] is enabled, [Critic Markup] can be used, which adds the ability to
highlight suggested changes, as well as add inline comments to a document.
_Example_:
@ -127,7 +52,7 @@ possible {>>and comments can be added inline<<}.
{==
Formatting can also be applied to blocks, by putting the opening and closing
Formatting can also be applied to blocks by putting the opening and closing
tags on separate lines and adding new lines between the tags and the content.
==}
@ -144,7 +69,7 @@ Text can be <del class="critic">deleted</del> and replacement text
<div>
<mark class="critic block">
<p>
Formatting can also be applied to blocks, by putting the opening and
Formatting can also be applied to blocks by putting the opening and
closing tags on separate lines and adding new lines between the tags and
the content.
</p>
@ -153,9 +78,9 @@ Text can be <del class="critic">deleted</del> and replacement text
### Highlighting text
When the [Caret, Mark & Tilde][11] extensions are enabled, text can be
highlighted with a nicer syntax than using the corresponding `mark`, `ins` and
`del` HTML tags:
When [Caret, Mark & Tilde] are enabled, text can be highlighted with a simple
syntax, which is more convenient that directly using the corresponding
[`mark`][mark], [`ins`][ins] and [`del`][del] HTML tags.
_Example_:
@ -171,13 +96,15 @@ _Result_:
- ^^This was inserted^^
- ~~This was deleted~~
[11]: #caret-mark-tilde
[mark]: https://developer.mozilla.org/en-US/docs/Web/HTML/Element/mark
[ins]: https://developer.mozilla.org/en-US/docs/Web/HTML/Element/ins
[del]: https://developer.mozilla.org/en-US/docs/Web/HTML/Element/del
### Sub- and superscripts
When the [Caret & Tilde][11] extensions are enabled, text can be sub- and
superscripted with a nicer syntax than using the corresponding `sub` and `sup`
HTML tags:
When [Caret & Tilde][Caret, Mark & Tilde] are enabled, text can be sub- and
superscripted with a simple syntax, which is more convenient that directly
using the corresponding [`sub`][sub] and [`sup`][sup] HTML tags:
_Example_:
@ -191,4 +118,23 @@ _Result_:
- H~2~0
- A^T^A
[11]: #caret-mark-tilde
[sub]: https://developer.mozilla.org/en-US/docs/Web/HTML/Element/sub
[sup]: https://developer.mozilla.org/en-US/docs/Web/HTML/Element/sup
### Adding keyboard keys
When [Keys] is enabled, keyboard keys can be rendered with a simple syntax.
Consult the [Python Markdown Extensions] documentation to learn about all
available shortcodes.
_Example_:
``` markdown
++ctrl+alt+del++
```
_Result_:
++ctrl+alt+del++
[Python Markdown Extensions]: https://facelessuser.github.io/pymdown-extensions/extensions/keys/#extendingmodifying-key-map-index

206
docs/reference/icons-emojis.md
View File

@ -5,9 +5,11 @@ template: overrides/main.html
# Icons + Emojis
One of the best features of Material for MkDocs is the possibility to use [more
than 8.000 icons][1] and thousands of emojis in your project documentation
with practically zero additional effort. Furthermore, custom icons can be added
and used in `mkdocs.yml`, documents and templates.
than 8.000 icons][icon search] and thousands of emojis in your project
documentation with practically zero additional effort. Moreover, custom icons
can be added and used in `mkdocs.yml`, documents and templates.
[icon search]: #search
## Search
@ -24,19 +26,15 @@ and used in `mkdocs.yml`, documents and templates.
</div>
<small>
:octicons-light-bulb-16:
**Tip:** Enter some keywords to find the perfect icon or emoji and click on
the shortcode to copy it to your clipboard.
**Tip:** Enter some keywords to find icons and emojis and click on the
shortcode to copy it to your clipboard.
</small>
## Configuration
### Emoji
[:octicons-file-code-24: Source][2] · [:octicons-workflow-24: Extension][3]
The [Emoji][3] extension, which is part of [Python Markdown Extensions][4],
adds the ability to __integrate emojis and icons__ in the `*.svg` file format,
which are inlined when [building your site][5]:
This configuration enables the use of icons and emojis by using simple
shortcodes which can be discovered through the [icon search]. Add the following
lines to `mkdocs.yml`:
``` yaml
markdown_extensions:
@ -47,44 +45,28 @@ markdown_extensions:
The following icon sets are bundled with Material for MkDocs:
- :material-material-design: – [Material Design][6]
- :fontawesome-brands-font-awesome-flag: – [FontAwesome][7]
- :octicons-mark-github-16: – [Octicons][8]
- :material-material-design: – [Material Design]
- :fontawesome-brands-font-awesome: – [FontAwesome]
- :octicons-mark-github-16: – [Octicons]
You can also add [additional icons][9]. When using emojis, it's recommended to
consult the official documentation of [Python Markdown Extensions][3] to learn
about configuration options.
See additional configuration options:
[1]: icons-emojis.md#search
[2]: https://github.com/squidfunk/mkdocs-material/blob/master/src/assets/stylesheets/main/extensions/pymdownx/_emoji.scss
[3]: https://facelessuser.github.io/pymdown-extensions/extensions/emoji/
[4]: https://facelessuser.github.io/pymdown-extensions/
[5]: ../creating-your-site.md#building-your-site
[6]: https://materialdesignicons.com/
[7]: https://fontawesome.com/icons?d=gallery&m=free
[8]: https://octicons.github.com/
[9]: ../setup/changing-the-logo-and-icons.md#additional-icons
- [Emoji]
- [Emoji with custom icons]
### Attribute List
The [Attribute List][10] extension, which is part of the standard Markdown
library, allows to __add HTML attributes and CSS classes to Markdown elements__,
and can be enabled via `mkdocs.yml`
``` yaml
markdown_extensions:
- attr_list
```
[10]: https://python-markdown.github.io/extensions/attr_list/
[Material Design]: https://materialdesignicons.com/
[FontAwesome]: https://fontawesome.com/icons?d=gallery&m=free
[Octicons]: https://octicons.github.com/
[Emoji]: ../setup/extensions/python-markdown-extensions.md#emoji
[Emoji with custom icons]: ../setup/extensions/python-markdown-extensions.md#custom-icons
## Usage
### Using emojis
Emojis can be integrated in Markdown by putting the shortcode of the emoji
between two colons. If you're using [Twemoji][11] (recommended), you can look up
the shortcodes at [Emojipedia][12].
between two colons. If you're using [Twemoji] (recommended), you can look up
the shortcodes at [Emojipedia].
_Example_:
@ -96,54 +78,40 @@ _Result_:
:smile:
[11]: https://twemoji.twitter.com/
[12]: https://emojipedia.org/twitter/
[Twemoji]: https://twemoji.twitter.com/
[Emojipedia]: https://emojipedia.org/twitter/
### Using icons
When [Emoji][13] is enabled, icons can be used similar to emojis, by referencing
When [Emoji] is enabled, icons can be used similar to emojis, by referencing
a valid path to any icon bundled with the theme, which are located in the
[`.icons`][1] directory, and replacing `/` with `-`:
[`.icons`][custom icons] directory, and replacing `/` with `-`:
_Example_:
```
- :material-account-circle: – `.icons/material/account-circle.svg`
- :fontawesome-regular-laugh-wink: – `.icons/fontawesome/regular/laugh-wink.svg`
- :octicons-repo-push-16: – `.icons/octicons/repo-push-16.svg`
- :material-account-circle: – `material/account-circle.svg`
- :fontawesome-regular-laugh-wink: – `fontawesome/regular/laugh-wink.svg`
- :octicons-repo-push-16: – `octicons/repo-push-16.svg`
```
_Result_:
- :material-account-circle: – [`.icons/material/account-circle.svg`][14]
- :fontawesome-regular-laugh-wink: – [`.icons/fontawesome/regular/laugh-wink.svg`][15]
- :octicons-repo-push-16: – [`.icons/octicons/repo-push-16.svg`][16]
- :material-account-circle: – [`material/account-circle.svg`][icon Material]
- :fontawesome-regular-laugh-wink: – [`fontawesome/regular/laugh-wink.svg`][icon FontAwesome]
- :octicons-repo-push-16: – [`octicons/repo-push-16.svg`][icon Octicons]
[13]: #emoji
[14]: https://raw.githubusercontent.com/squidfunk/mkdocs-material/master/material/.icons/material/account-circle.svg
[15]: https://raw.githubusercontent.com/squidfunk/mkdocs-material/master/material/.icons/fontawesome/regular/laugh-wink.svg
[16]: https://raw.githubusercontent.com/squidfunk/mkdocs-material/master/material/.icons/octicons/repo-push-16.svg
[custom icons]: https://github.com/squidfunk/mkdocs-material/tree/master/material/.icons
[icon Material]: https://raw.githubusercontent.com/squidfunk/mkdocs-material/master/material/.icons/material/account-circle.svg
[icon FontAwesome]: https://raw.githubusercontent.com/squidfunk/mkdocs-material/master/material/.icons/fontawesome/regular/laugh-wink.svg
[icon Octicons]: https://raw.githubusercontent.com/squidfunk/mkdocs-material/master/material/.icons/octicons/repo-push-16.svg
#### with colors
When the [Attribute List][17] extension is enabled, custom CSS classes and
attributes can be added to icons by suffixing the icon with a special syntax.
While HTML and CSS allow to use [inline styles][18], it's always best to add
an [additional stylesheet][19] and put styles into dedicated CSS classes:
``` css
.medium {
color: #00AB6C;
}
.twitter {
color: #1DA1F2;
}
.facebook {
color: #4267B2;
}
```
Then, simply add the CSS class to the icon.
When [Attribute Lists] is enabled, custom CSS classes can be added to icons by
suffixing the icon with a special syntax. While HTML allows to use
[inline styles], it's always recommended to add an [additional style sheet] and
move declarations into dedicated CSS classes.
<style>
.medium {
@ -159,11 +127,34 @@ Then, simply add the CSS class to the icon.
_Example_:
``` markdown
- :fontawesome-brands-medium:{ .medium } – Medium
- :fontawesome-brands-twitter:{ .twitter } – Twitter
- :fontawesome-brands-facebook:{ .facebook } – Facebook
```
=== ":octicons-file-code-16: docs/example.md"
``` markdown
- :fontawesome-brands-medium:{ .medium } – Medium
- :fontawesome-brands-twitter:{ .twitter } – Twitter
- :fontawesome-brands-facebook:{ .facebook } – Facebook
```
=== ":octicons-file-code-16: docs/stylesheets/extra.css"
``` css
.medium {
color: #00AB6C;
}
.twitter {
color: #1DA1F2;
}
.facebook {
color: #4267B2;
}
```
=== ":octicons-file-code-16: mkdocs.yml"
``` yaml
extra_css:
- stylesheets/extra.css
```
_Result_:
@ -171,52 +162,61 @@ _Result_:
- :fontawesome-brands-twitter:{ .twitter } – Twitter
- :fontawesome-brands-facebook:{ .facebook } – Facebook
[17]: #attribute-list
[18]: https://developer.mozilla.org/en-US/docs/Web/HTML/Global_attributes/style
[19]: ../customization.md#additional-css
[Attribute Lists]: ../setup/extensions/python-markdown.md#attribute-lists
[inline styles]: https://developer.mozilla.org/en-US/docs/Web/HTML/Global_attributes/style
[additional style sheet]: ../customization.md#additional-css
#### with animations
Similar to adding [colors][20], it's just as easy to add [CSS animations][21] to
icons by using an [additional stylesheet][6], defining a `#!css @keyframes` rule
and adding the dedicated CSS class to the icon:
Similar to adding [colors], it's just as easy to add [animations] to icons by
using an [additional style sheet], defining a `@keyframes` rule and adding a
dedicated CSS class to the icon.
``` css
@keyframes heart {
_Example_:
=== ":octicons-file-code-16: docs/example.md"
``` markdown
:octicons-heart-fill-24:{ .heart }
```
=== ":octicons-file-code-16: docs/stylesheets/extra.css"
``` css
@keyframes heart {
0%, 40%, 80%, 100% {
transform: scale(1);
}
20%, 60% {
transform: scale(1.15);
}
}
.heart {
}
.heart {
animation: heart 1000ms infinite;
}
```
}
```
Then, simply add the CSS class to the icon.
=== ":octicons-file-code-16: mkdocs.yml"
_Example_:
``` markdown
:octicons-heart-fill-24:{ .heart }
```
``` yaml
extra_css:
- stylesheets/extra.css
```
_Result_:
:octicons-heart-fill-24:{ .mdx-heart }
[20]: #with-colors
[21]: https://developer.mozilla.org/en-US/docs/Web/CSS/animation
[colors]: #with-colors
[animations]: https://developer.mozilla.org/en-US/docs/Web/CSS/animation
## Customization
### Using icons in templates
When you're [extending the theme][22] with partials or blocks, you can simply
reference any icon that's [bundled with the theme][1] with Jinja's
[`include`][23] function and wrap it with the `twemoji` class:
When you're [extending the theme] with partials or blocks, you can simply
reference any icon that's [bundled with the theme][icon search] with Jinja's
[`include`][include] function and wrap it with the `.twemoji` CSS class:
``` html
<span class="twemoji">
@ -226,5 +226,5 @@ reference any icon that's [bundled with the theme][1] with Jinja's
This is exactly what Material for MkDocs does in its templates.
[22]: ../customization.md#extending-the-theme
[23]: https://jinja.palletsprojects.com/en/2.11.x/templates/#include
[extending the theme]: ../customization.md#extending-the-theme
[include]: https://jinja.palletsprojects.com/en/2.11.x/templates/#include

81
docs/reference/images.md
View File

@ -6,32 +6,36 @@ template: overrides/main.html
While images are first-class citizens of Markdown and part of the core syntax,
it can be difficult to work with them. Material for MkDocs makes working with
images more comfortable by providing styles for alignment and image captions.
[1]: https://www.markdownguide.org/basic-syntax/#images-1
images more comfortable, providing styles for image alignment and image
captions.
## Configuration
### Attribute List
The [Attribute List][2] extension, which is part of the standard Markdown
library, allows to __add HTML attributes and CSS classes to Markdown elements__,
and can be enabled via `mkdocs.yml`
This configuration adds the ability to align images, add captions to images
(rendering them as figures), and mark large images for lazy-loading. Add the
following lines to `mkdocs.yml`:
``` yaml
markdown_extensions:
- attr_list
- md_in_html
```
[2]: https://python-markdown.github.io/extensions/attr_list/
See additional configuration options:
- [Attribute Lists]
- [Markdown in HTML]
[Attribute Lists]: ../setup/extensions/python-markdown.md#attribute-lists
[Markdown in HTML]: ../setup/extensions/python-markdown.md#markdown-in-html
## Usage
### Image alignment
When the [Attribute List][3] extension is enabled, images can be aligned by
adding the respective alignment directions via the `align` attribute, i.e.
`align=left` or `align=right`
When [Attribute Lists] is enabled, images can be aligned by adding the
respective alignment directions via the `align` attribute, i.e. `align=left` or
`align=right`:
=== "Left"
@ -65,48 +69,61 @@ adding the respective alignment directions via the `align` attribute, i.e.
nulla. Curabitur feugiat, tortor non consequat finibus, justo purus auctor
massa, nec semper lorem quam in massa.
_If there's insufficient space to render the text next to the image, the image
will stretch to the full width of the viewport, e.g. on mobile viewports._
If there's insufficient space to render the text next to the image, the image
will stretch to the full width of the viewport, e.g. on mobile viewports.
[3]: #attribute-list
??? question "Why is there no centered alignment?"
The [`align`][align] attribute doesn't allow for centered alignment, which
is why this option is not supported by Material for MkDocs.[^1] Instead,
the [image captions] syntax can be used, as captions are optional.
[^1]:
You might also realize that the [`align`][align] attribute has been
deprecated as of HTML5, so why use it anyways? The main reason is
portability – it's still supported by all browsers and clients, and is very
unlikely to be completely removed, as many older websites still use it. This
ensures a consistent appearance when a Markdown file with these attributes
is viewed outside of a website generated by Material for MkDocs.
[align]: https://developer.mozilla.org/en-US/docs/Web/HTML/Element/img#deprecated_attributes
[image captions]: #image-captions
### Image captions
Sadly, the Markdown syntax doesn't provide native support for image captions,
but it's always possible to resort to HTML. Using `figure` and `figcaption`, captions can be added to images.
but it's always possible to use HTML. Using `figure` and `figcaption`, captions
can be added to images.
_Example_:
```html
<figure>
<img src="https://dummyimage.com/600x400/eee/aaa" width="300" />
<figure markdown> <!-- (1) -->
![Dummy image](https://dummyimage.com/600x400/){ width="300" }
<figcaption>Image caption</figcaption>
</figure>
```
1. :man_raising_hand: Remember to enable the [Markdown in HTML] extension.
_Result_:
<figure>
<img src="https://dummyimage.com/600x400/f5f5f5/aaaaaa&text=–%20Image%20–" width="300" />
<figure markdown>
![Dummy image]{ width="300" }
<figcaption>Image caption</figcaption>
</figure>
[Dummy image]: https://dummyimage.com/600x400/f5f5f5/aaaaaa&text=–%20Image%20–
[Markdown in HTML]: ../setup/extensions/python-markdown.md#markdown-in-html
### Image lazy-loading
Modern browsers provide [native support for lazy-loading images][4] through the
`loading` attribute, which degrades to eager-loading in browsers without
support. As with [image alignment][5], if the [Attribute List][3] extension is
enabled, images can be lazy-loaded by adding `loading=lazy`.
_Example_:
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:
``` markdown
![Placeholder](https://dummyimage.com/600x400/eee/aaa){ loading=lazy }
```
_Result_:
![Placeholder](https://dummyimage.com/600x400/f5f5f5/aaaaaa&text=–%20Image%20–){ loading=lazy width=300 }
[4]: https://caniuse.com/#feat=loading-lazy-attr
[5]: #image-alignment
[lazy-loading]: https://caniuse.com/#feat=loading-lazy-attr

78
docs/reference/lists.md
View File

@ -11,64 +11,31 @@ are supported through extensions.
## Configuration
### Definition List
[:octicons-file-code-24: Source][1] · [:octicons-workflow-24: Extension][2]
The [Definition List][2] extension, which is part of the standard Markdown
library, adds the ability to add definitions lists to a document and can be
enabled via `mkdocs.yml`:
This configuration enables the use of definition lists and tasks lists, which
are both not part of the standard Markdown syntax. Add the following lines to
`mkdocs.yml`:
``` yaml
markdown_extensions:
- def_list
```
[1]: https://github.com/squidfunk/mkdocs-material/blob/master/src/assets/stylesheets/main/_typeset.scss
[2]: https://python-markdown.github.io/extensions/definition_lists/
### Tasklist
[:octicons-file-code-24: Source][3] · [:octicons-workflow-24: Extension][4]
The [Tasklist][4] extension, which is part of [Python Markdown Extensions][5],
adds support for lists with styled checkboxes, and provides several options for
configuring the style:
`custom_checkbox`{ #custom-checkbox }
: :octicons-milestone-24: Default: `false` · This option toggles the rendering
style of checkboxes, replacing native checkbox styles with beautiful icons,
and is therefore _strongly recommended_:
``` yaml
markdown_extensions:
- pymdownx.tasklist:
custom_checkbox: true
```
```
`clickable_checkbox`{ #clickable-checkbox }
See additional configuration options:
: :octicons-milestone-24: Default: `false` · This option toggles whether
checkboxes are clickable. As the state is not persisted, the use of this
option is _rather discouraged_ from a user experience perspective:
- [Definition Lists]
- [Tasklist]
``` yaml
markdown_extensions:
- pymdownx.tasklist:
clickable_checkbox: true
```
[3]: https://github.com/squidfunk/mkdocs-material/blob/master/src/assets/stylesheets/main/extensions/pymdownx/_tasklist.scss
[4]: https://facelessuser.github.io/pymdown-extensions/extensions/tasklist/
[5]: https://facelessuser.github.io/pymdown-extensions/
[Definition Lists]: ../setup/extensions/python-markdown.md#definition-lists
[Tasklist]: ../setup/extensions/python-markdown-extensions.md#tasklist
## Usage
### Using unordered lists
An unordered list can be written by prefixing a line with a `-`, `*` or `+`
list marker, all of which can be used interchangeably. Furthermore, all flavors
Unordered lists can be written by prefixing a line with a `-`, `*` or `+` list
marker, all of which can be used interchangeably. Furthermore, all flavors
of lists can be nested inside each other.
_Example_:
@ -95,7 +62,7 @@ _Result_:
### Using ordered lists
An ordered list must start with a number immediately followed by a dot. The
Ordered lists must start with a number immediately followed by a dot. The
numbers do not need to be consecutive and can be all set to `1.`, as they will
be re-numbered when rendered.
@ -137,18 +104,19 @@ _Result_:
### Using definition lists
[Definition lists][6] are a ideal for describing arbitrary key-value pairs, e.g.
the parameters of functions or modules, as used within this documentation to
describe extension or plugin parameters.
When [Definition Lists] is enabled, lists of arbitrary key-value pairs, e.g. the
parameters of functions or modules, can be enumerated with a simple syntax.
_Example_:
``` markdown
`Lorem ipsum dolor sit amet`
: Sed sagittis eleifend rutrum. Donec vitae suscipit est. Nullam tempus
tellus non sem sollicitudin, quis rutrum leo facilisis.
`Cras arcu libero`
: Aliquam metus eros, pretium sed nulla venenatis, faucibus auctor ex. Proin
ut eros sed sapien ullamcorper consequat. Nunc ligula ante.
@ -160,10 +128,12 @@ _Example_:
_Result_:
`Lorem ipsum dolor sit amet`
: Sed sagittis eleifend rutrum. Donec vitae suscipit est. Nullam tempus
tellus non sem sollicitudin, quis rutrum leo facilisis.
`Cras arcu libero`
: Aliquam metus eros, pretium sed nulla venenatis, faucibus auctor ex. Proin
ut eros sed sapien ullamcorper consequat. Nunc ligula ante.
@ -171,13 +141,11 @@ _Result_:
Nam vulputate tincidunt fringilla.
Nullam dignissim ultrices urna non auctor.
[6]: #definition-list
### Using task lists
### Using tasklists
When the [Tasklist][7] extension is enabled, unordered list items can be
prefixed with `[ ]` to render an unchecked or `[x]` to render a checked
checkbox.
When [Tasklist] is enabled, unordered list items can be prefixed with `[ ]` to
render an unchecked checkbox or `[x]` to render a checked checkbox, allowing
for the definition of task lists.
_Example_:
@ -198,5 +166,3 @@ _Result_:
* [x] In scelerisque nibh non dolor mollis congue sed et metus
* [ ] Praesent sed risus massa
- [ ] Aenean pretium efficitur erat, donec pharetra, ligula non scelerisque
[7]: #tasklist

67
docs/reference/mathjax.md
View File

@ -4,37 +4,23 @@ template: overrides/main.html
# MathJax
[MathJax][1] is a beautiful and accessible way to display _mathematical content_
in the browser, allows for writing formulas in different notations, including
[LaTeX][2], [MathML][3] and [AsciiMath][4], and can be easily integrated with
[MathJax] is a beautiful and accessible way to display mathematical content
in the browser, adds support for mathematical typesetting in different notations
(e.g. [LaTeX], [MathML], [AsciiMath]), and can be easily integrated with
Material for MkDocs.
[1]: https://www.mathjax.org/
[2]: https://en.wikibooks.org/wiki/LaTeX/Mathematics
[3]: https://en.wikipedia.org/wiki/MathML
[4]: http://asciimath.org/
[MathJax]: https://www.mathjax.org/
[LaTeX]: https://en.wikibooks.org/wiki/LaTeX/Mathematics
[MathML]: https://en.wikipedia.org/wiki/MathML
[AsciiMath]: http://asciimath.org/
## Configuration
### Arithmatex
This configuration enables support for rendering block and inline block
equations through [MathJax]. Create a configuration file and add the following
lines to `mkdocs.yml`:
[:octicons-file-code-24: Source][5] · [:octicons-workflow-24: Extension][6]
The [Arithmatex][6] extension, which is part of of [Python Markdown
Extensions][7], allows the rendering of block and inline block equations, and
can be enabled via `mkdocs.yml`:
``` yaml
markdown_extensions:
- pymdownx.arithmatex:
generic: true
```
Besides enabling the extension in `mkdocs.yml`, a MathJax configuration and
the JavaScript runtime need to be included, which can be done with [additional
JavaScript][8]:
=== "docs/javascripts/config.js"
=== ":octicons-file-code-16: docs/javascripts/mathjax.js"
``` js
window.MathJax = {
@ -50,31 +36,32 @@ JavaScript][8]:
}
};
document$.subscribe(() => {
document$.subscribe(() => { // (1)
MathJax.typesetPromise()
})
```
=== "mkdocs.yml"
1. This integrates MathJax with [instant loading].
=== ":octicons-file-code-16: mkdocs.yml"
``` yaml
markdown_extensions:
- pymdownx.arithmatex:
generic: true
extra_javascript:
- javascripts/config.js
- javascripts/mathjax.js
- https://polyfill.io/v3/polyfill.min.js?features=es6
- https://cdn.jsdelivr.net/npm/mathjax@3/es5/tex-mml-chtml.js
```
_MathJax can be configured in many different ways, for which Material for MkDocs
might not provide native support. See the [official documentation][6] for more
information._
See additional configuration options:
!!! tip "Using MathJax with [instant loading][9]"
- [Arithmatex]
There's no additional effort necessary to integrate _MathJax 3_ with
[instant loading][9] – it's expected to work straight away. However, a
previous version of this document explained how to integrate Material for
MkDocs with _MathJax 2_, which doesn't exhibit this behavior. It's therefore
highly recommended to switch to _MathJax 3_.
[Arithmatex]: ../setup/extensions/python-markdown-extensions.md#arithmatex
[instant loading]: ../setup/setting-up-navigation.md#instant-loading
<script src="https://polyfill.io/v3/polyfill.min.js?features=es6"></script>
<script id="MathJax-script" async src="https://cdn.jsdelivr.net/npm/mathjax@3/es5/tex-mml-chtml.js"></script>
@ -93,12 +80,6 @@ information._
};
</script>
[5]: https://github.com/squidfunk/mkdocs-material/blob/master/src/assets/stylesheets/main/extensions/pymdownx/_arithmatex.scss
[6]: https://facelessuser.github.io/pymdown-extensions/extensions/arithmatex/
[7]: https://facelessuser.github.io/pymdown-extensions/extensions/
[8]: ../customization.md#additional-javascript
[9]: ../setup/setting-up-navigation.md#instant-loading
## Usage
### Using block syntax

154
docs/reference/meta-tags.md
View File

@ -6,57 +6,59 @@ template: overrides/main.html
In HTML, `meta` tags allow to provide additional metadata for a document, e.g.
page titles and descriptions, additional assets to be loaded, and [Open Graph]
[1] data. While arbitrary metadata can always be added via [customization][2],
metadata. While arbitrary `meta` tags can always be added via [customization],
some common `meta` tags can be configured.
[1]: https://ogp.me/
[2]: #customization
[Open Graph]: https://ogp.me/
[customization]: #customization
## Configuration
### Metadata
The [Metadata][3] extension, which is part of the standard Markdown library,
adds the ability to add [front matter][4] to a document and can be enabled via
`mkdocs.yml`:
This configuration adds support for setting custom page titles and descriptions
in [front matter], as well as for using custom metadata in templates. Add the
following lines to `mkdocs.yml`:
``` yaml
markdown_extensions:
- meta
```
Front matter is written as a series of key-value pairs at the beginning of the
Markdown document, delimited by a blank line which ends the YAML context.
See additional configuration options:
[3]: https://python-markdown.github.io/extensions/meta_data/
[4]: https://jekyllrb.com/docs/front-matter/
- [Metadata]
[front matter]: https://jekyllrb.com/docs/front-matter/
[Metadata]: ../setup/extensions/python-markdown.md#metadata
## Usage
### Setting the page title
If the [Metadata][5] extension is enabled, the page title can be overridden on
a per-document basis with custom front matter:
When [Metadata] is enabled, the page title can be overridden for a document with
some custom front matter. Add the following lines at the top of a Markdown file:
``` bash
---
title: Lorem ipsum dolor sit amet
title: Lorem ipsum dolor sit amet # (1)
---
# Document title
...
```
This will set the `title` tag inside the document `head` for the current page
to the provided value. Note that the site title is appended using a dash as a
separator, which is the default behavior.
1. This will set the [`title`][title] inside the HTML document's [`head`][head]
for the generated page to this value. Note that the site title, which is set
via [`site_name`][site_name], is appended with a dash.
[5]: #metadata
[title]: https://developer.mozilla.org/en-US/docs/Web/HTML/Element/title
[head]: https://developer.mozilla.org/en-US/docs/Web/HTML/Element/head
[site_name]: https://www.mkdocs.org/user-guide/configuration/#site_name
### Setting the page description
If the [Metadata][5] extension is enabled, the page description can also be
overridden on a per-document basis with custom front matter:
When [Metadata] is enabled, the page description can be overridden for a
document with custom front matter. Add the following lines at the top of a
Markdown file:
``` bash
---
@ -70,47 +72,41 @@ description: Nullam urna elit, malesuada eget finibus ut, ac tortor.
This will set the `meta` tag containing the site description inside the
document `head` for the current page to the provided value.
<div class="mdx-deprecated" markdown>
### Adding a web app manifest
A [web app manifest][6] is a simple JSON file that specifies how your web
[:octicons-tag-24: 3.1.0][manifest support] ·
:octicons-archive-24: Deprecated ·
:octicons-trash-24: 8.0.0
A [web app manifest] is a simple JSON file that specifies how your web
application should behave when installed on the user's mobile device or desktop,
which can be set via `mkdocs.yml`:
``` yaml
extra:
manifest: manifest.webmanifest
manifest: manifest.webmanifest # (1)
```
[6]: https://developers.google.com/web/fundamentals/web-app-manifest/
1. This option was deprecated, as it's not widely used and the same behavior
can be achieved with [theme extension].
[web app manifest]: https://web.dev/add-manifest/
[manifest support]: https://github.com/squidfunk/mkdocs-material/releases/tag/3.1.0
[theme extension]: ../customization.md#extending-the-theme
</div>
## Customization
### Displaying the metadata
Sometimes it's useful to be able to display the medatada in the page body, e.g.
print the name of the page author at the bottom of the page. To achieve that,
you can [extend the theme][7] by adding the following contents to `main.html`:
``` html
{% extends "base.html" %}
{% block content %}
{{ super() }}
{% if page and page.meta and page.meta.author %}
<p><small>Author: {{ page.meta.author }}</small></p>
{% endif %}
{% endblock %}
```
[7]: ../customization.md#extending-the-theme
### Custom meta tags
### Using metadata in templates
#### on all pages
In order to add custom `meta` tags to your document, you can [extend the theme
][7] and simply [override the `extrahead` block][8], e.g. to add indexing
policies for search engines:
][theme extension] and [override the `extrahead` block][overriding blocks],
e.g. to add indexing policies for search engines via the `robots` property:
``` html
{% extends "base.html" %}
@ -120,7 +116,7 @@ policies for search engines:
{% endblock %}
```
[8]: ../customization.md#overriding-blocks-recommended
[overriding blocks]: ../customization.md#overriding-blocks
#### on a single page
@ -140,63 +136,9 @@ template override, e.g.:
{% endblock %}
```
You can now use `robots` exactly like [`title`][9] and [`description`][10] to
set values. Note that in this case, the template defines an `else` branch, which
would set a default if none was given.
You can now use `robots` exactly like [`title`][title] and
[`description`][description] to set values. Note that in this case, the
template defines an `else` branch, which would set a default if none was given.
[9]: #setting-the-page-title
[10]: #setting-the-page-description
### Social meta tags
Some further examples, including [Open Graph][1] and [Twitter Cards][11]:
=== "Open Graph"
``` html
{% block extrahead %}
{% set title = config.site_name %}
{% 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 %}
{% endif %}
<meta property="og:type" content="website" />
<meta property="og:title" content="{{ title }}" />
<meta property="og:description" content="{{ config.site_description }}" />
<meta property="og:url" content="{{ page.canonical_url }}" />
<meta property="og:image" content="<url>" />
<meta property="og:image:type" content="image/png" />
<meta property="og:image:width" content="1200" />
<meta property="og:image:height" content="630" />
{% endblock %}
```
=== "Twitter Cards"
``` html
{% block extrahead %}
{% set title = config.site_name %}
{% 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 %}
{% 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>" />
{% endblock %}
```
!!! tip "Automatically generated social cards"
If you don't want to bother with meta tags and social cards yourself, you
can let the [built-in social cards plugin][12] do the work for you, which
generates beautiful image previews for social media automatically during
the build.
[11]: https://developer.twitter.com/en/docs/tweets/optimize-with-cards/overview/abouts-cards
[12]: ../setup/setting-up-social-cards.md
[title]: #setting-the-page-title
[description]: #setting-the-page-description

152
docs/reference/variables.md
View File

@ -1,152 +0,0 @@
---
template: overrides/main.html
---
# Variables
Macros and variables are powerful tools to parametrize Markdown files, as they
allow to perform Jinja templating directly from Markdown. This is especially
useful to include technical data from other files and add central variables via
`mkdocs.yml`.
## Configuration
### Macros
The [macros][1] plugin adds support to reference variables and call macros and
supports Jinja templating directly from Markdown. It can be installed with
`pip`:
```
pip install mkdocs-macros-plugin
```
Then, add the following to `mkdocs.yml`:
``` yaml
plugins:
- macros
```
[1]: https://github.com/fralau/mkdocs_macros_plugin
## Usage
### Using predefined variables
A set of predefined variables is enabled by default and can be used from
Markdown, including data from `mkdocs.yml`. More specifically, predefined
variables fall into the following categories:
- `config.*`: configuration parameters from `mkdocs.yml`
- `page.*`: metadata and content of current page
- `navigation.*`: list of all pages and sections
- `environment.*`: underlying operating system
- `git.*`: git-related information, if available
_Example_:
``` markdown
Welcome to {{ config.site_name }}!
```
_Result_:
``` markdown
Welcome to Material for MkDocs!
```
A list of all predefined variables can be printed with:
```
{{ macros_info() }}
```
### Using custom variables
All data defined under `extra` in `mkdocs.yml` is automatically exposed as a
variable and can be used from the template. This enables centralized parameter
storage and management.
_Example_:
=== "`docs/page.md`"
```` markdown
The unit price is {{ unit.price }}
````
=== "`mkdocs.yml`"
``` yaml
extra:
unit:
price: 12.50
```
_Result_:
The unit price is 12.50.
### Using variables in snippets
The [macros][2] plugin can be used to allow variables in snippets, which is not
possible with the [Snippets][3] extension alone. Add the snippets location to
the plugin configuration in `mkdocs.yml`:
``` yaml
plugins:
- search
- macros:
include_dir: snippets
```
In your Markdown file, include snippets with Jinja's [`include`][4] function:
``` markdown
{% include "definitions.md" %}
```
_Example_:
=== "`snippets/definitions.md`"
``` markdown
The unit price is {{ page.meta.unit.price }}
```
=== "`docs/page-1.md`"
``` markdown
---
unit:
price: 12.50
---
{% include "definitions.md" %}
```
=== "`docs/page-2.md`"
``` markdown
---
unit:
price: 25.00
---
{% include "definitions.md" %}
```
[2]: #macros
[3]: https://facelessuser.github.io/pymdown-extensions/extensions/snippets/
[4]: https://jinja.palletsprojects.com/en/2.11.x/templates/#include
## Customization
### Custom macros
The [macros][1] plugin allows to define custom macros, which can then be used
from Markdown files. See the [official documentation][5] for more information
how to define custom macros.
[5]: https://mkdocs-macros-plugin.readthedocs.io/en/latest/python/

49
docs/setup/adding-a-comment-system.md
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

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

@ -11,9 +11,14 @@ documents can be linked to specific source files.
## Configuration
### Repository
[:octicons-tag-24: 0.1.0][repo_url support] ·
:octicons-milestone-24: Default: _none_
In order to display a link to the repository of your project as part of your
documentation, set [`repo_url`][1] in `mkdocs.yml` to the public URL of your
repository, e.g.:
documentation, set [`repo_url`][repo_url] in `mkdocs.yml` to the public URL of
your repository, e.g.:
``` yaml
repo_url: https://github.com/squidfunk/mkdocs-material
@ -21,35 +26,38 @@ repo_url: https://github.com/squidfunk/mkdocs-material
The link to the repository will be rendered next to the search bar on big
screens and as part of the main navigation drawer on smaller screen sizes.
Additionally, for GitHub and GitLab, the number of stars and forks is
automatically requested and rendered for _public repositories_.
Additionally, for public repositories hosted on [GitHub] or [GitLab], the
number of stars and forks is automatically requested and rendered.
[1]: https://www.mkdocs.org/user-guide/configuration/#repo_url
[repo_url support]: https://github.com/squidfunk/mkdocs-material/releases/tag/0.1.0
[repo_url]: https://www.mkdocs.org/user-guide/configuration/#repo_url
### Repository name
[:octicons-file-code-24: Source][2] · :octicons-milestone-24: Default:
_automatically set to_ `GitHub`, `GitLab` _or_ `Bitbucket`
[:octicons-tag-24: 0.1.0][repo_name support] ·
:octicons-milestone-24: Default: _automatically set to_ `GitHub`, `GitLab` _or_
`Bitbucket`
MkDocs will infer the source provider by examining the URL and try to set the
_repository name_ automatically. If you wish to customize the name, set
[`repo_name`][3] in `mkdocs.yml`:
[`repo_name`][repo_name] in `mkdocs.yml`:
``` yaml
repo_name: squidfunk/mkdocs-material
```
[2]: https://github.com/squidfunk/mkdocs-material/blob/master/src/partials/source.html
[3]: https://www.mkdocs.org/user-guide/configuration/#repo_name
[repo_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-file-code-24: Source][2] · :octicons-milestone-24: Default:
`fontawesome/brands/git-alt`
[:octicons-tag-24: 5.0.0][icon.repo support] ·
:octicons-milestone-24: Default:
[`fontawesome/brands/git-alt`][icon.repo default]
While the default _repository icon_ is a generic git icon, it can be set to
[any icon bundled with the theme][4] by referencing a valid icon path in
`mkdocs.yml`:
While the default repository icon is a generic git icon, it can be set to
[any icon bundled with the theme][custom icons] by referencing a valid icon
path in `mkdocs.yml`:
``` yaml
theme:
@ -70,16 +78,18 @@ Some popular choices:
- :fontawesome-brands-bitbucket: – `fontawesome/brands/bitbucket`
- :fontawesome-solid-trash: – `fontawesome/solid/trash`
[4]: https://github.com/squidfunk/mkdocs-material/tree/master/material/.icons
[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
[custom icons]: https://github.com/squidfunk/mkdocs-material/tree/master/material/.icons
### Edit button
[:octicons-file-code-24: Source][5] · :octicons-milestone-24: Default:
_automatically set_
[:octicons-tag-24: 0.1.0][edit_uri support] ·
:octicons-milestone-24: Default: _automatically set_
If the repository URL points to a [GitHub][6], [GitLab][7] or [Bitbucket][8]
repository, an _edit button_ is displayed at the top of each document. This
behavior can be changed by setting [`edit_uri`][9] in `mkdocs.yml`:
If the repository URL points to a [GitHub], [GitLab] or [Bitbucket] repository,
an edit button is displayed at the top of each document. This behavior can be
changed by setting [`edit_uri`][edit_uri] in `mkdocs.yml`:
=== "Customize edit path"
@ -93,39 +103,39 @@ behavior can be changed by setting [`edit_uri`][9] in `mkdocs.yml`:
edit_uri: ""
```
[5]: https://github.com/squidfunk/mkdocs-material/blob/master/src/base.html
[6]: https://github.com/
[7]: https://about.gitlab.com/
[8]: https://bitbucket.org/
[9]: https://www.mkdocs.org/user-guide/configuration/#edit_uri
[edit_uri 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/
[Bitbucket]: https://bitbucket.org/
### Revision date
[:octicons-file-code-24: Source][10] ·
[:octicons-cpu-24: Plugin][11]
[:octicons-tag-24: 4.6.0][git-revision-date support] ·
[:octicons-cpu-24: Plugin][git-revision-date]
The [git-revision-date][10] plugin adds support for displaying the date a
document was _last updated_ at the bottom of each page. It can be installed
The [git-revision-date] plugin adds support for displaying the date a
document was last updated at the bottom of each page. It can be installed
with `pip`:
```
pip install mkdocs-git-revision-date-plugin
```
Then, add the following to `mkdocs.yml`:
Then, add the following lines to `mkdocs.yml`:
``` yaml
plugins:
- git-revision-date
```
The following options are supported:
The following configuration options are supported:
`enabled_if_env`{ #enabled_if_env }
`enabled_if_env`{ #enabled-if-env }
: :octicons-milestone-24: Default: _none_ – When specified the data will only be extracted from git
if the environment variable exists. This makes it possible to disable
extraction for cases when the repository is not available:
: :octicons-milestone-24: Default: _none_ – When specified, the plugin will
only be invoked if the environment variable exists. This makes it easy to
disable extraction for cases when the repository is not available:
``` yaml
plugins:
@ -133,21 +143,21 @@ The following options are supported:
enabled_if_env: CI
```
_Material for MkDocs doesn't provide official support for the other options of
this plugin, so they may be supported but might yield unexpected results.
Use them at your own risk._
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.
[10]: https://github.com/squidfunk/mkdocs-material/blob/master/src/partials/source-date.html
[11]: https://github.com/zhaoterryy/mkdocs-git-revision-date-plugin
[git-revision-date support]: https://github.com/squidfunk/mkdocs-material/releases/tag/4.6.0
[git-revision-date]: https://github.com/zhaoterryy/mkdocs-git-revision-date-plugin
### Revision date, localized
[:octicons-file-code-24: Source][10] ·
[:octicons-cpu-24: Plugin][12]
[:octicons-tag-24: 4.6.0][git-revision-date-localized support] ·
[:octicons-cpu-24: Plugin][git-revision-date-localized]
Similarly, the [git-revision-date-localized][12] plugin adds support for adding
a localized _updated at_ and _created at_ date at the bottom of each page. It
can be installed with `pip`:
Similarly, the [git-revision-date-localized] plugin adds support for adding
a localized update and creation date at the bottom of each page. It can be
installed with `pip`:
```
pip install mkdocs-git-revision-date-localized-plugin
@ -160,7 +170,7 @@ plugins:
- git-revision-date-localized
```
The following options are supported:
The following configuration options are supported:
`type`{ #type }
@ -174,11 +184,11 @@ The following options are supported:
type: date
```
`fallback_to_build_date`{ #fallback_to_build_date }
`fallback_to_build_date`{ #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
the build is performed outside of the git repository:
the build is performed outside of a git repository:
``` yaml
plugins:
@ -186,11 +196,11 @@ The following options are supported:
fallback_to_build_date: true
```
`enable_creation_date`{ #enable_creation_date }
`enable_creation_date`{ #enable-creation-date }
: :octicons-milestone-24: Default: `false` – Enables the display of the
_created at_ date of the file associated with the page next to the
_updated at_ date at the bottom of the page:
creation date of the file associated with the page next to the last updated
date at the bottom of the page:
``` yaml
plugins:
@ -199,8 +209,9 @@ The following options are supported:
```
_Material for MkDocs doesn't provide official support for the other options of
this plugin, so they may be supported but might yield unexpected results.
Use them at your own risk._
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.
[12]: https://github.com/timvink/mkdocs-git-revision-date-localized-plugin
[git-revision-date-localized 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

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

@ -5,12 +5,12 @@ template: overrides/main.html
# Changing the colors
As any proper Material Design implementation, Material for MkDocs supports
Google's original [color palette][1], which can be easily configured through
Google's original [color palette], which can be easily configured through
`mkdocs.yml`. Furthermore, colors can be customized with a few lines of CSS to
fit your brand's identity by using [CSS variables][2].
fit your brand's identity by using [CSS variables][custom colors].
[1]: http://www.materialui.co/colors
[2]: #custom-colors
[color palette]: http://www.materialui.co/colors
[custom colors]: #custom-colors
## Configuration
@ -18,9 +18,10 @@ fit your brand's identity by using [CSS variables][2].
#### Color scheme
[:octicons-file-code-24: Source][3] · :octicons-milestone-24: Default: `default`
[:octicons-tag-24: 5.2.0][palette.scheme support] ·
:octicons-milestone-24: Default: `default`
Material for MkDocs supports two _color schemes_: a light mode, which is just
Material for MkDocs supports two color schemes: a light mode, which is just
called `default`, and a dark mode, which is called `slate`. The color scheme
can be set via `mkdocs.yml`:
@ -30,7 +31,7 @@ theme:
scheme: default
```
_Click on a tile to change the color scheme_:
Click on a tile to change the color scheme:
<div class="mdx-switch">
<button data-md-color-scheme="default"><code>default</code></button>
@ -49,13 +50,14 @@ _Click on a tile to change the color scheme_:
})
</script>
[3]: https://github.com/squidfunk/mkdocs-material/blob/master/src/assets/stylesheets/palette/_scheme.scss
[palette.scheme support]: https://github.com/squidfunk/mkdocs-material/releases/tag/5.2.0
#### Primary color
[:octicons-file-code-24: Source][4] · :octicons-milestone-24: Default: `indigo`
[:octicons-tag-24: 0.2.0][palette.primary support] ·
:octicons-milestone-24: Default: `indigo`
The _primary color_ is used for the header, the sidebar, text links and several
The primary color is used for the header, the sidebar, text links and several
other components. In order to change the primary color, set the following value
in `mkdocs.yml` to a valid color name:
@ -65,7 +67,7 @@ theme:
primary: indigo
```
_Click on a tile to change the primary color_:
Click on a tile to change the primary color:
<div class="mdx-switch">
<button data-md-color-primary="red"><code>red</code></button>
@ -103,13 +105,14 @@ _Click on a tile to change the primary color_:
})
</script>
[4]: https://github.com/squidfunk/mkdocs-material/blob/master/src/assets/stylesheets/palette/_primary.scss
[palette.primary support]: https://github.com/squidfunk/mkdocs-material/releases/tag/0.2.0
#### Accent color
[:octicons-file-code-24: Source][5] · :octicons-milestone-24: Default: `indigo`
[:octicons-tag-24: 0.2.0][palette.accent support] ·
:octicons-milestone-24: Default: `indigo`
The _accent color_ is used to denote elements that can be interacted with, e.g.
The accent color is used to denote elements that can be interacted with, e.g.
hovered links, buttons and scrollbars. It can be changed in `mkdocs.yml` by
choosing a valid color name:
@ -119,7 +122,7 @@ theme:
accent: indigo
```
_Click on a tile to change the accent color_:
Click on a tile to change the accent color:
<style>
.md-typeset button[data-md-color-accent] > code {
@ -159,36 +162,45 @@ _Click on a tile to change the accent color_:
})
</script>
[5]: https://github.com/squidfunk/mkdocs-material/blob/master/src/assets/stylesheets/palette/_accent.scss
[palette.accent support]: https://github.com/squidfunk/mkdocs-material/releases/tag/0.2.0
### Color palette toggle
[:octicons-file-code-24: Source][6] · :octicons-milestone-24: Default: _none_
[:octicons-tag-24: 7.1.0][palette.toggle support] ·
:octicons-milestone-24: Default: _none_
It's also possible to offer a list of color palettes to the user, each of which
can include a [`scheme`][7], [`primary`][8] and [`accent`][9] color each. The
user can toggle between those color palettes:
can include a [`scheme`][palette.scheme], [`primary`][palette.primary] and
[`accent`][palette.accent] color each. The user can toggle between those color
palettes:
``` yaml hl_lines="4-6 8-10"
``` yaml
theme:
palette:
palette: # (1)
- scheme: default
toggle:
icon: material/toggle-switch-off-outline
name: Switch to dark mode
- scheme: slate
- scheme: slate # (2)
toggle:
icon: material/toggle-switch
name: Switch to light mode
```
The following fields must be set for each toggle:
1. Note that the `theme.palette` setting is now defined as a list.
2. With __2__ (color schemes) __x 21__ (primary colors) __x 17__ (accent color)
= __714__ combinations, it's impossible to ensure that all configurations
provide a good user experience (e.g. _yellow on light background_). Make
sure that the color combination of your choosing provides enough contrast
and tweak CSS variables where necessary.
`icon`{ #icon }
The following properties must be set for each toggle:
`icon`{ #toggle-icon }
: :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][10], or the build will not succeed. Some popular
with the theme][custom icons], or the build will not succeed. Some popular
combinations:
* :material-toggle-switch-off-outline: + :material-toggle-switch: – `material/toggle-switch-off-outline` + `material/toggle-switch`
@ -196,102 +208,116 @@ The following fields must be set for each toggle:
* :material-eye-outline: + :material-eye: – `material/eye-outline` + `material/eye`
* :material-lightbulb-outline: + :material-lightbulb: – `material/lightbulb-outline` + `material/lightbulb`
`name`{ #name }
`name`{ #toggle-name }
: :octicons-milestone-24: Default: _none_ · :octicons-alert-24: Required –
This field is used as the toggle's `title` attribute and should be set to a
discernable name to improve accessibility.
discernable name to improve accessibility. It will appear on mouse hover.
[6]: https://github.com/squidfunk/mkdocs-material/blob/master/src/partials/header.html
[7]: #color-scheme
[8]: #primary-color
[9]: #accent-color
[10]: https://github.com/squidfunk/mkdocs-material/tree/master/material/.icons
[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
[custom icons]: https://github.com/squidfunk/mkdocs-material/tree/master/material/.icons
### System preference
[:octicons-file-code-24: Source][6] · :octicons-milestone-24: Default: _none_
[:octicons-tag-24: 7.1.0][palette.media support] ·
:octicons-milestone-24: Default: _none_
In order to automatically set the color palette to the user's system preference,
a media query can be set as part of the `media` field next to the toggle
definition in `mkdocs.yml`:
``` yaml hl_lines="3 8"
``` yaml
theme:
palette:
- media: "(prefers-color-scheme: light)"
- media: "(prefers-color-scheme: light)" # (1)
scheme: default
toggle:
icon: material/toggle-switch-off-outline
name: Switch to dark mode
- media: "(prefers-color-scheme: dark)"
- media: "(prefers-color-scheme: dark)" # (2)
scheme: slate
toggle:
icon: material/toggle-switch
name: Switch to light mode
```
1. This media query is __checked first__. It's also the __fallback__ when no
media query matches.
2. This media query is __checked second__. If it doesn't match, the first one
is automatically used.
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.
!!! warning "Accessibility – not all color combinations work well"
With __2__ (color schemes) __x 21__ (primary colors) __x 17__ (accent color)
= __714__ combinations, it's impossible to ensure that all configurations
provide a good user experience (e.g. _yellow on light background_). Make
sure that the color combination of your choosing provides enough contrast
and tweak CSS variables where necessary.
[palette.media support]: https://github.com/squidfunk/mkdocs-material/releases/tag/7.1.0
## Customization
### Custom colors
[:octicons-file-code-24: Source][11] ·
:octicons-mortar-board-24: Difficulty: _easy_
Material for MkDocs implements colors using [CSS variables][12] (custom
Material for MkDocs implements colors using [CSS variables] (custom
properties). If you want to customize the colors beyond the palette (e.g. to
use your brand-specific colors), you can add an [additional stylesheet][13] and
use your brand-specific colors), you can add an [additional style sheet] and
tweak the values of the CSS variables.
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:
``` css
:root {
=== ":octicons-file-code-16: docs/stylesheets/extra.css"
``` css
:root {
--md-primary-fg-color: #EE0F0F;
--md-primary-fg-color--light: #ECB7B7;
--md-primary-fg-color--dark: #90030C;
}
```
}
```
See the file containing the [color definitions][11] for a list of all CSS
variables.
=== ":octicons-file-code-16: mkdocs.yml"
[11]: https://github.com/squidfunk/mkdocs-material/blob/master/src/assets/stylesheets/main/_colors.scss
[12]: https://developer.mozilla.org/en-US/docs/Web/CSS/Using_CSS_custom_properties
[13]: ../customization.md#additional-css
``` yaml
extra_css:
- stylesheets/extra.css
```
See the file containing the [color definitions] for a list of all CSS variables.
[CSS variables]: https://developer.mozilla.org/en-US/docs/Web/CSS/Using_CSS_custom_properties
[color definitions]: https://github.com/squidfunk/mkdocs-material/blob/master/src/assets/stylesheets/main/_colors.scss
[additional style sheet]: ../customization.md#additional-css
### Custom color schemes
[:octicons-file-code-24: Source][11] ·
:octicons-mortar-board-24: Difficulty: _easy_
Besides overriding specific colors, you can create your own, named color scheme
by wrapping the definitions in the `#!css [data-md-color-scheme="..."]`
[attribute selector][14], which you can then set via `mkdocs.yml` as described
in the [color schemes][7] section:
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:
``` css
[data-md-color-scheme="youtube"] {
=== ":octicons-file-code-16: docs/stylesheets/extra.css"
``` css
[data-md-color-scheme="youtube"] {
--md-primary-fg-color: #EE0F0F;
--md-primary-fg-color--light: #ECB7B7;
--md-primary-fg-color--dark: #90030C;
}
```
}
```
=== ":octicons-file-code-16: mkdocs.yml"
``` yaml
theme:
palette:
scheme: youtube
extra_css:
- stylesheets/extra.css
```
Additionally, the `slate` color scheme defines all of it's colors via `hsla`
color functions and deduces its colors from the `--md-hue` CSS variable. You
@ -299,8 +325,10 @@ can tune the `slate` theme with:
``` css
[data-md-color-scheme="slate"] {
--md-hue: 210; /* [0, 360] */
--md-hue: 210; /* (1) */
}
```
[14]: https://www.w3.org/TR/selectors-4/#attribute-selectors
1. The `hue` value must be in the range of `[0, 360]`
[attribute selector]: https://www.w3.org/TR/selectors-4/#attribute-selectors

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

@ -5,22 +5,22 @@ template: overrides/main.html
# Changing the fonts
Material for MkDocs makes it easy to change the typeface of your project
documentation, as it directly integrates with [Google Fonts][1]. Alternatively,
documentation, as it directly integrates with [Google Fonts]. Alternatively,
fonts can be custom-loaded if self-hosting is preferred for data privacy reasons
or another destination should be used.
[1]: https://fonts.google.com
[Google Fonts]: https://fonts.google.com
## Configuration
### Regular font
[:octicons-file-code-24: Source][2] ·
:octicons-milestone-24: Default: [`Roboto`][3]
[: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
The regular font is used for all body copy, headlines, and essentially
everything that does not need to be monospaced. It can be set to any
valid [Google Font][1] with:
valid [Google Font][Google Fonts] via `mkdocs.yml`:
``` yaml
theme:
@ -30,17 +30,17 @@ theme:
The typeface will be loaded in 300, 400, _400i_ and __700__.
[2]: https://github.com/squidfunk/mkdocs-material/blob/master/src/base.html
[3]: https://fonts.google.com/specimen/Roboto
[Roboto]: https://fonts.google.com/specimen/Roboto
[font support]: https://github.com/squidfunk/mkdocs-material/releases/tag/0.1.2
### Monospaced font
[:octicons-file-code-24: Source][2] ·
:octicons-milestone-24: Default: [`Roboto Mono`][4]
[: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.
Just like the regular font, it can be set to any valid [Google Font][1] via
`mkdocs.yml` with:
Just like the regular font, it can be set to any valid [Google Font]
[Google Fonts] via `mkdocs.yml`:
``` yaml
theme:
@ -50,55 +50,63 @@ theme:
The typeface will be loaded in 400.
[4]: https://fonts.google.com/specimen/Roboto+Mono
[Roboto Mono]: https://fonts.google.com/specimen/Roboto+Mono
## Customization
### Autoloading
If you want to load fonts from other destinations or don't want to use Google
Fonts for [data privacy][5] reasons, e.g. _due to GDPR_, you may customize
font loading as described below.
[:octicons-tag-24: 1.0.0][font=false support] ·
:octicons-milestone-24: Default: _none_
### Disabling font loading
[:octicons-file-code-24: Source][2] ·
:octicons-mortar-board-24: Difficulty: _easy_
If you want to prevent typefaces from being loaded from Google Fonts and fall
back to system fonts, add the following lines to `mkdocs.yml`:
If you want to prevent typefaces from being loaded from [Google Fonts], e.g.
to adhere to [data privacy] regulations, and fall back to system fonts, add the
following lines to `mkdocs.yml`:
``` yaml
theme:
font: false
```
[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
## Customization
### Additional fonts
[:octicons-file-code-24: Source][2] ·
:octicons-mortar-board-24: Difficulty: _easy_
If you want to load an (additional) font from another or override
the fallback font, you can use an [additional stylesheet][8] to add the
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:
``` css
@font-face {
=== ":octicons-file-code-16: docs/stylesheets/extra.css"
``` css
@font-face {
font-family: "<font>";
src: "...";
}
```
}
```
=== ":octicons-file-code-16: mkdocs.yml"
``` yaml
extra_css:
- stylesheets/extra.css
```
The font can then be applied to specific elements, e.g. only headlines, or
globally to be used as the site-wide regular or monospaced font (with fallback
fonts being added automatically):
globally to be used as the site-wide regular or monospaced font:
=== "Regular font"
``` css
:root {
--md-text-font-family: "<font>";
--md-text-font-family: "<font>"; /* (1) */
}
```
1. Always define fonts through CSS variables and not `font-family`, as
this would disable the system font fallback.
=== "Monospaced font"
``` css
@ -107,7 +115,4 @@ fonts being added automatically):
}
```
[5]: ../data-privacy.md
[6]: ../customization.md#extending-the-theme
[7]: ../customization.md#overriding-blocks-recommended
[8]: ../customization.md#additional-stylesheets
[additional style sheet]: ../customization.md#additional-css

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

@ -6,16 +6,17 @@ template: overrides/main.html
Material for MkDocs supports internationalization (i18n) and provides
translations for template variables and labels in 40+ languages. Additionally,
the site search can be configured to use a language-specific stemmer (if
available).
the site search can be configured to use a language-specific stemmer, if
available.
## Configuration
### Site language
[:octicons-file-code-24: Source][1] · :octicons-milestone-24: Default: `en`
[:octicons-tag-24: 1.12.0][language support] ·
:octicons-milestone-24: Default: `en`
You can set the _site language_ in `mkdocs.yml` with:
You can set the site language in `mkdocs.yml` with:
``` yaml
theme:
@ -24,7 +25,7 @@ theme:
The following languages are supported:
<div class="mdx-columns" markdown="1">
<div class="mdx-columns" markdown>
- `af` – Afrikaans
- `ar` – Arabic
@ -79,70 +80,72 @@ The following languages are supported:
</div>
_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,
as [documented here][2]._
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].
[1]: https://github.com/squidfunk/mkdocs-material/blob/master/src/partials/languages/en.html
[2]: setting-up-navigation.md#slugify
[language support]: https://github.com/squidfunk/mkdocs-material/releases/tag/1.12.0
[Unicode-aware slug function]: setting-up-navigation.md#slugify
### Site language selector
[:octicons-file-code-24: Source][3] ·
[:octicons-tag-24: 7.0.0][alternate support] ·
:octicons-milestone-24: Default: _none_ ·
:octicons-beaker-24: Experimental
If your documentation is available in multiple languages, a _language selector_
can be added to the header next to the search bar. Alternate languages can be
defined via `mkdocs.yml`:
If your documentation is available in multiple languages, a language selector
pointing to those languages can be added to the header. Alternate languages
can be defined via `mkdocs.yml`.
``` yaml
extra:
alternate:
# Switch to English
- name: English
link: <your-site>/en/
link: /en/ # (1)
lang: en
# Switch to German
- name: Deutsch
link: <your-site>/de/
link: /de/
lang: de
# Switch to Japanese
- name: 日本語
link: <your-site>/ja/
lang: ja
```
This will render a language selector in the header next to the search bar:
1. Note that this must be an absolute link. If it includes a domain part, it's
used as defined. Otherwise the domain part of the [`site_url`][site_url] as
set in `mkdocs.yml` is prepended to the link.
[![Language selection][4]][4]
The following properties must be set for each alternate language:
[3]: https://github.com/squidfunk/mkdocs-material/blob/master/src/partials/header.html
[4]: ../assets/screenshots/language-selection.png
`name`{ #language-name }
### Site search language
: :octicons-milestone-24: Default: _none_ · :octicons-alert-24: Required –
This field is used inside the language selector as the name of the language
and must be set to a non-empty string.
[:octicons-file-code-24: Source][5] ·
:octicons-milestone-24: Default: _automatically set_
`link`{ #language-link }
Some languages, like Arabic or Japanese, need dedicated stemmers for search to
work properly. Material for MkDocs relies on [lunr-languages][6] to provide this
functionality. See the guide detailing how to [set up site search][7] for
more information.
: :octicons-milestone-24: Default: _none_ · :octicons-alert-24: Required –
This field must be set to an absolute link, which might also point to
another domain or subdomain not necessarily generated with MkDocs.
[5]: https://github.com/squidfunk/mkdocs-material/blob/master/src/assets/javascripts/integrations/search/worker/main/index.ts
[6]: https://github.com/MihaiValentin/lunr-languages
[7]: setting-up-site-search.md
`lang`{ #language-lang }
: :octicons-milestone-24: Default: _none_ · :octicons-alert-24: Required –
This field must contain a valid [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_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-file-code-24: Source][8] ·
[:octicons-tag-24: 2.5.0][direction support] ·
:octicons-milestone-24: Default: _automatically set_
While many languages are read `ltr` (left-to-right), Material for MkDocs also
supports `rtl` (right-to-left) _directionality_ which is inferred from the
supports `rtl` (right-to-left) directionality which is deduced from the
selected language, but can also be set with:
``` yaml
@ -163,44 +166,54 @@ Click on a tile to change the directionality:
button.addEventListener("click", function() {
var attr = this.getAttribute("data-md-dir")
document.body.dir = attr
var name = document.querySelector("#__code_1 code span:nth-child(5)")
var name = document.querySelector("#__code_3 code span:nth-child(5)")
name.textContent = attr
})
})
</script>
[8]: https://github.com/squidfunk/mkdocs-material/blob/master/src/base.html
[direction support]: https://github.com/squidfunk/mkdocs-material/releases/tag/2.5.0
## Customization
### Custom translations
[:octicons-file-code-24: Source][1] ·
:octicons-mortar-board-24: Difficulty: _easy_
If you want to customize some of the translations for a language, just follow
the guide on [theme extension][9] and create a new partial in
`partials/languages`, e.g. `en-custom.html`. Next, look up the translation you
want to change in the [base translation][1] and add it to the partial.
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:
Let's say you want to change "__Table of contents__" to "__On this page__":
=== ":octicons-file-code-16: partials/languages/custom.html"
``` html
<!-- Use en language as fallback -->
{% import "partials/languages/en.html" as fallback %}
{% macro override(key) %}{{ {
"toc.title": "On this page"
}[key] }}{% endmacro %}
``` html
<!-- Import translations for language and fallback -->
{% import "partials/languages/de.html" as language %}
{% import "partials/languages/en.html" as fallback %} <!-- (1) -->
<!-- Re-export the translation macro for mkbuild-material to use -->
{% macro t(key) %}{{ override(key) or fallback.t(key) }}{% endmacro %}
```
<!-- Define custom translations -->
{% macro override(key) %}{{ {
"toc.title": "Auf dieser Seite" <!-- (2) -->
}[key] }}{% endmacro %}
Then, add the following lines to `mkdocs.yml`:
<!-- Re-export translations -->
{% macro t(key) %}{{
override(key) or language(key) or fallback.t(key)
}}{% endmacro %}
```
``` yaml
theme:
language: en-custom
```
1. Note that `en` must always be used as a fallback language, as it's the
default theme language.
[9]: ../customization.md#extending-the-theme
2. Check the [list of available languages], pick the translation you want
to override for your language and add them here.
=== ":octicons-file-code-16: mkdocs.yml"
``` yaml
theme:
language: custom
```
[theme extension]: ../customization.md#extending-the-theme
[translations]: https://github.com/squidfunk/mkdocs-material/blob/master/src/partials/languages/
[list of available languages]: https://github.com/squidfunk/mkdocs-material/blob/master/src/partials/languages/

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

@ -4,32 +4,32 @@ template: overrides/main.html
# Changing the logo and icons
When installing Material for MkDocs, you immediately get access to _over 7.000
When installing Material for MkDocs, you immediately get access to _over 8.000
icons_ ready to be used for customization of specific parts of the theme and/or
when writing your documentation in Markdown. Not enough? You can also [add
additional icons][1] with minimal effort.
when writing your documentation in Markdown. Not enough? You can also add
[additional icons] with minimal effort.
[1]: #additional-icons
[additional icons]: #additional-icons
## Configuration
### Logo
[:octicons-file-code-24: Source][2] ·
:octicons-milestone-24: Default: [`material/library`][3]
[:octicons-tag-24: 0.1.0][logo support] ·
:octicons-milestone-24: Default: [`material/library`][logo default]
The _logo_ can be changed to a user-provided image (any type, incl. `*.png` and
The logo can be changed to a user-provided image (any type, incl. `*.png` and
`*.svg`) located in the `docs` folder, or to any icon bundled with the theme.
Add the following lines to `mkdocs.yml`:
=== "Image"
=== ":octicons-image-16: Image"
``` yaml
theme:
logo: assets/logo.png
```
=== "Icon, bundled"
=== ":octicons-package-16: Icon, bundled"
``` yaml
theme:
@ -37,9 +37,8 @@ Add the following lines to `mkdocs.yml`:
logo: material/library
```
[2]: https://github.com/squidfunk/mkdocs-material/blob/master/src/partials/logo.html
[3]: https://github.com/squidfunk/mkdocs-material/blob/master/material/.icons/material/library.svg
[4]: https://github.com/squidfunk/mkdocs-material/tree/master/material/.icons
[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
Normally, the logo in the header and sidebar links to the homepage of the
documentation, which is the same as `site_url`. This behavior can be changed
@ -52,60 +51,28 @@ extra:
### Favicon
[:octicons-file-code-24: Source][5] ·
:octicons-milestone-24: Default: `assets/images/favicon.png`
[: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. It can be set via `mkdocs.yml`:
The favicon can be changed to a path pointing to a user-provided image, which
must be located in the `docs` folder. Add the following lines to `mkdocs.yml`:
``` yaml
theme:
favicon: images/favicon.png
```
[5]: https://github.com/squidfunk/mkdocs-material/blob/master/src/base.html
### Icons
[:octicons-file-code-24: Source][4] · [:octicons-workflow-24: Extension][6]
The [Emoji][6] extension, which is part of [Python Markdown Extensions][7],
adds the ability to __integrate icons__ in the `*.svg` file format, which are
inlined when [building your site][8]:
``` yaml
markdown_extensions:
- pymdownx.emoji:
emoji_index: !!python/name:materialx.emoji.twemoji
emoji_generator: !!python/name:materialx.emoji.to_svg
```
The following icon sets are bundled with Material for MkDocs:
- :material-material-design: – [Material Design][9]
- :fontawesome-brands-font-awesome-flag: – [FontAwesome][10]
- :octicons-mark-github-16: – [Octicons][11]
If you want to add [additional icons][1], read on.
[6]: https://facelessuser.github.io/pymdown-extensions/extensions/emoji/
[7]: https://facelessuser.github.io/pymdown-extensions/
[8]: ../creating-your-site.md#building-your-site
[9]: https://materialdesignicons.com/
[10]: https://fontawesome.com/icons?d=gallery&m=free
[11]: https://octicons.github.com/
[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
### Additional icons
[:octicons-file-code-24: Source][4] ·
:octicons-mortar-board-24: Difficulty: _easy_
In order to add additional icons, [extend the theme][12], and create a folder
named `.icons` in the [`custom_dir`][13] you want to use for overrides. Next,
add your `*.svg` icons into a subfolder of the `.icons` folder. Let's say you
downloaded and unpacked the [Bootstrap][14] icon set, and want to add it to
In order to use custom icons, [extend the theme] and create a new folder named
`.icons` in the [`custom_dir`][custom_dir] you want to use for overrides.
Next, add your `*.svg` icons into a subfolder of the `.icons` folder. Let's say
you downloaded and unpacked the [Bootstrap] icon set, and want to add it to
your project documentation. The structure of your project should look like this:
``` sh
@ -129,9 +96,8 @@ markdown_extensions:
- overrides/.icons
```
You should now be able to use the :fontawesome-brands-bootstrap: Bootstrap
icons.
You can now use all :fontawesome-brands-bootstrap: Bootstrap icons.
[12]: ../customization.md#extending-the-theme
[13]: https://www.mkdocs.org/user-guide/configuration/#custom_dir
[14]: https://icons.getbootstrap.com/
[extend the theme]: ../customization.md#extending-the-theme
[custom_dir]: https://www.mkdocs.org/user-guide/configuration/#custom_dir
[Bootstrap]: https://icons.getbootstrap.com/

142
docs/setup/extensions/index.md Normal file
View File

@ -0,0 +1,142 @@
---
template: overrides/main.html
title: Extensions
---
# Extensions
Markdown is a very small language with a kind-of reference implementation called
[John Gruber's Markdown]. [Python Markdown] and [Python Markdown Extensions]
are two packages that enhance the Markdown writing experience, adding useful
syntax extensions for technical writing.
[John Gruber's Markdown]: https://daringfireball.net/projects/markdown/
[Python Markdown]: python-markdown.md
[Python Markdown Extensions]: python-markdown-extensions.md
## Supported extensions
The following extensions are all supported by Material for MkDocs and therefore
strongly recommended. Click on each extension to learn about its purpose and
configuration:
<div class="mdx-columns" markdown>
- [Abbreviations]
- [Admonition]
- [Arithmatex]
- [Attribute Lists]
- [BetterEm]
- [Caret, Mark & Tilde]
- [Critic]
- [Definition Lists]
- [Details]
- [Emoji]
- [Footnotes]
- [Highlight]
- [Keys]
- [Metadata]
- [Markdown in HTML]
- [SmartSymbols]
- [Snippets]
- [SuperFences]
- [Tabbed]
- [Table of Contents]
- [Tables]
- [Tasklist]
</div>
[Abbreviations]: python-markdown.md#abbreviations
[Admonition]: python-markdown.md#admonition
[Arithmatex]: python-markdown-extensions.md#arithmatex
[Attribute Lists]: python-markdown.md#attribute-lists
[BetterEm]: python-markdown-extensions.md#betterem
[Caret, Mark & Tilde]: python-markdown-extensions.md#caret-mark-tilde
[Critic]: python-markdown-extensions.md#critic
[Definition Lists]: python-markdown.md#definition-lists
[Details]: python-markdown-extensions.md#details
[Emoji]: python-markdown-extensions.md#emoji
[Footnotes]: python-markdown.md#footnotes
[Highlight]: python-markdown-extensions.md#highlight
[Keys]: python-markdown-extensions.md#keys
[Metadata]: python-markdown.md#metadata
[Markdown in HTML]: python-markdown.md#markdown-in-html
[SmartSymbols]: python-markdown-extensions.md#smartsymbols
[Snippets]: python-markdown-extensions.md#snippets
[SuperFences]: python-markdown-extensions.md#superfences
[Tabbed]: python-markdown-extensions.md#tabbed
[Table of Contents]: python-markdown.md#table-of-contents
[Tables]: python-markdown.md#tables
[Tasklist]: python-markdown-extensions.md#tasklist
## Configuration
Extensions are configured as part of `mkdocs.yml` – the MkDocs configuration
file. The following sections contain two example configurations to bootstrap
your documentation project.
[overview]: #advanced-configuration
### Minimal configuration
This configuration is a good starting point for when you're using Material for
MkDocs for the first time. The best idea is to explore the [reference], and
gradually add what you want to use:
``` yaml
markdown_extensions:
# Python Markdown
- meta
- toc:
permalink: true
# Python Markdown Extensions
- pymdownx.highlight
- pymdownx.superfences
```
[reference]: ../../reference/abbreviations.md
### Recommended configuration
This configuration enables all Markdown-related features of Material for MkDocs
and is great for experienced users bootstrapping a new documentation project:
``` yaml
markdown_extensions:
# Python Markdown
- abbr
- admonition
- attr_list
- def_list
- footnotes
- meta
- md_in_html
- toc:
permalink: true
# Python Markdown Extensions
- pymdownx.arithmatex:
generic: true
- pymdownx.betterem:
smart_enable: all
- pymdownx.caret
- pymdownx.details
- pymdownx.emoji:
emoji_index: !!python/name:materialx.emoji.twemoji
emoji_generator: !!python/name:materialx.emoji.to_svg
- pymdownx.highlight
- pymdownx.inlinehilite
- pymdownx.keys
- pymdownx.mark
- pymdownx.smartsymbols
- pymdownx.superfences
- pymdownx.tabbed:
alternate_style: true
- pymdownx.tasklist:
custom_checkbox: true
- pymdownx.tilde
```

691
docs/setup/extensions/python-markdown-extensions.md Normal file
View File

@ -0,0 +1,691 @@
---
template: overrides/main.html
---
# Python Markdown Extensions
The [Python Markdown Extensions] package is an excellent collection of
additional extensions perfectly suited for advanced technical writing. Material
for MkDocs lists this package as an explicit dependency, so it's automatically
installed with a supported version.
[Python Markdown Extensions]: https://facelessuser.github.io/pymdown-extensions/
## Supported extensions
### Arithmatex
[:octicons-tag-24: 1.0.0][Arithmatex support] ·
[:octicons-workflow-24: Extension][Arithmatex]
The [Arithmatex] extension allows for rendering of block and inline block
equations and integrates seamlessly with [MathJax][^1] – a library for
mathematical typesetting. Enable it via `mkdocs.yml`:
[^1]:
Other libraries like [KaTeX] are also supported and can be integrated with
some additional effort. See the [Arithmatex documentation on KaTeX] for
further guidance, as this is beyond the scope of Material for MkDocs.
``` yaml
markdown_extensions:
- pymdownx.arithmatex:
generic: true
```
Besides enabling the extension in `mkdocs.yml`, a MathJax configuration and
the JavaScript runtime need to be included, which can be done with a few lines
of [additional JavaScript]:
=== ":octicons-file-code-16: docs/javascripts/mathjax.js"
``` js
window.MathJax = {
tex: {
inlineMath: [["\\(", "\\)"]],
displayMath: [["\\[", "\\]"]],
processEscapes: true,
processEnvironments: true
},
options: {
ignoreHtmlClass: ".*|",
processHtmlClass: "arithmatex"
}
};
document$.subscribe(() => {
MathJax.typesetPromise()
})
```
=== ":octicons-file-code-16: mkdocs.yml"
``` yaml
extra_javascript:
- javascripts/mathjax.js
- https://polyfill.io/v3/polyfill.min.js?features=es6
- https://cdn.jsdelivr.net/npm/mathjax@3/es5/tex-mml-chtml.js
```
The other configuration options of this extension are not officially supported
by Material for MkDocs, which is why they may yield unexpected results. Use
them at your own risk.
See reference for usage:
- [Using block syntax]
- [Using inline block syntax]
[Arithmatex]: https://facelessuser.github.io/pymdown-extensions/extensions/arithmatex/
[Arithmatex support]: https://github.com/squidfunk/mkdocs-material/releases/tag/1.0.0
[Arithmatex documentation on KaTeX]: https://facelessuser.github.io/pymdown-extensions/extensions/arithmatex/#loading-katex
[MathJax]: https://www.mathjax.org/
[KaTeX]: https://github.com/Khan/KaTeX
[additional JavaScript]: ../../customization.md#additional-javascript
[Using block syntax]: ../../reference/mathjax.md#using-block-syntax
[Using inline block syntax]: ../../reference/mathjax.md#using-inline-block-syntax
### BetterEm
[:octicons-tag-24: 0.1.0][BetterEm support] ·
[:octicons-workflow-24: Extension][BetterEm]
The [BetterEm] extension improves the detection of Markup to emphasize text
in Markdown using special characters, i.e. for `**bold**` and `_italic_`
formatting. Enable it via `mkdocs.yml`:
``` yaml
markdown_extensions:
- pymdownx.betterem
```
The configuration options of this extension are not specific to Material for
MkDocs, as they only impact the Markdown parsing stage. See the [BetterEm
documentation][BetterEm] for more information.
[BetterEm]: https://facelessuser.github.io/pymdown-extensions/extensions/betterem/
[BetterEm support]: https://github.com/squidfunk/mkdocs-material/releases/tag/0.1.0
### Caret, Mark & Tilde
[:octicons-tag-24: 1.0.0][Caret support] ·
[:octicons-workflow-24: Extension][Caret]
The [Caret], [Mark] and [Tilde] extensions add the ability to highlight text
and define sub- and superscript using a simple syntax. Enable them together
via `mkdocs.yml`:
``` yaml
markdown_extensions:
- pymdownx.caret
- pymdownx.mark
- pymdownx.tilde
```
The configuration options of this extension are not specific to Material for
MkDocs, as they only impact the Markdown parsing stage. See the [Caret], [Mark]
and [Tilde documentation][Tilde] for guidance.
See reference for usage:
- [Highlighting text]
- [Sub- and superscripts]
[Caret]: https://facelessuser.github.io/pymdown-extensions/extensions/caret/
[Caret support]: https://github.com/squidfunk/mkdocs-material/releases/tag/1.0.0
[Mark]: https://facelessuser.github.io/pymdown-extensions/extensions/mark/
[Tilde]: https://facelessuser.github.io/pymdown-extensions/extensions/tilde/
[Highlighting text]: ../../reference/formatting.md#highlighting-text
[Sub- and superscripts]: ../../reference/formatting.md#sub-and-superscripts
### Critic
[:octicons-tag-24: 1.0.0][Critic support] ·
[:octicons-workflow-24: Extension][Critic]
The [Critic] extension allows for the usage of [Critic Markup] to highlight
added, deleted or updated sections in a document, i.e. for tracking changes in
Markdown syntax. Enable it via `mkdocs.yml`:
``` yaml
markdown_extensions:
- pymdownx.critic
```
The following configuration options are supported:
`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
alternatively `accept` or `reject` them:
=== "View changes"
``` yaml
markdown_extensions:
- pymdownx.critic:
mode: view
```
=== "Accept changes"
``` yaml
markdown_extensions:
- pymdownx.critic:
mode: accept
```
=== "Reject changes"
``` yaml
markdown_extensions:
- pymdownx.critic:
mode: reject
```
See reference for usage:
- [Highlighting changes]
[Critic]: https://facelessuser.github.io/pymdown-extensions/extensions/critic/
[Critic support]: https://github.com/squidfunk/mkdocs-material/releases/tag/1.0.0
[Critic Markup]: https://github.com/CriticMarkup/CriticMarkup-toolkit
[Highlighting changes]: ../../reference/formatting.md#highlighting-changes
### Details
[:octicons-tag-24: 1.9.0][Details support] ·
[:octicons-workflow-24: Extension][Details]
The [Details] extension supercharges the [Admonition] extension, making the
resulting _call-outs_ collapsible, allowing them to be opened and closed by the
user. Enable it via `mkdocs.yml`:
``` yaml
markdown_extensions:
- pymdownx.details
```
No configuration options are available. See reference for usage:
- [Collapsible blocks]
[Details]: https://facelessuser.github.io/pymdown-extensions/extensions/details/
[Details support]: https://github.com/squidfunk/mkdocs-material/releases/tag/1.9.0
[Admonition]: python-markdown.md#admonition
[Collapsible blocks]: ../../reference/admonitions.md#collapsible-blocks
### Emoji
[:octicons-tag-24: 1.0.0][Emoji support] ·
[:octicons-workflow-24: Extension][Emoji]
The [Emoji] extension automatically inlines bundled and custom icons and emojis
in `*.svg` file format into the resulting HTML page. Enable it via `mkdocs.yml`:
``` yaml
markdown_extensions:
- pymdownx.emoji:
emoji_index: !!python/name:materialx.emoji.twemoji # (1)
emoji_generator: !!python/name:materialx.emoji.to_svg
```
1. [Python Markdown Extensions] uses the `pymdownx` namespace, but in order to
support the inlining of icons, the `materialx` namespace must be used, as it
extends the functionality of `pymdownx`.
The following configuration options are supported:
`emoji_index`{ #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
recommended due to [restrictions in licensing][Emoji index]:
``` yaml
markdown_extensions:
- pymdownx.emoji:
emoji_index: !!python/name:materialx.emoji.twemoji
```
`emoji_generator`{ #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
used together with the `to_svg` configuration:
``` yaml
markdown_extensions:
- pymdownx.emoji:
emoji_generator: !!python/name:materialx.emoji.to_svg
```
`options.custom_icons`{ #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
explained in more detail in the [icon customization guide]:
``` yaml
markdown_extensions:
- pymdownx.emoji:
emoji_index: !!python/name:materialx.emoji.twemoji
emoji_generator: !!python/name:materialx.emoji.to_svg
options:
custom_icons:
- overrides/.icons
```
The other configuration options of this extension are not officially supported
by Material for MkDocs, which is why they may yield unexpected results. Use
them at your own risk.
See reference for usage:
- [Using emojis]
- [Using icons]
- [Using icons in templates]
[Emoji]: https://facelessuser.github.io/pymdown-extensions/extensions/emoji/
[Emoji support]: https://github.com/squidfunk/mkdocs-material/releases/tag/1.0.0
[Emoji index]: https://facelessuser.github.io/pymdown-extensions/extensions/emoji/#default-emoji-indexes
[icon customization guide]: ../changing-the-logo-and-icons.md#additional-icons
[Using emojis]: ../../reference/icons-emojis.md#using-emojis
[Using icons]: ../../reference/icons-emojis.md#using-icons
[Using icons in templates]: ../../reference/icons-emojis.md#using-icons-in-templates
### Highlight
[:octicons-tag-24: 5.0.0][Highlight support] ·
[:octicons-workflow-24: Extension][Highlight] ·
:octicons-zap-24: Supersedes [CodeHilite]
The [Highlight] extension adds support for syntax highlighting of code blocks
(with the help of [SuperFences][pymdownx.superfences]) and inline code blocks
(with the help of [InlineHilite][pymdownx.inlinehilite]). Enable it via
`mkdocs.yml`:
``` yaml
markdown_extensions:
- pymdownx.highlight
- pymdownx.superfences # (1)
```
1. [Highlight] is used by the [SuperFences][pymdownx.superfences] extension to
perform syntax highlighting on code blocks, not the other way round, which
is why this extension also needs to be enabled.
The following configuration options are supported:
`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
[Pygments] or in the browser with a JavaScript syntax highlighter:
=== "Pygments"
``` yaml
markdown_extensions:
- pymdownx.highlight:
use_pygments: true
- pymdownx.superfences
```
=== "JavaScript"
``` yaml
markdown_extensions:
- pymdownx.highlight:
use_pygments: false
```
As an example, [Highlight.js], a JavaScript syntax highlighter, can be
integrated with some [additional JavaScript] and [CSS][additional CSS]
in `mkdocs.yml`:
=== ":octicons-file-code-16: docs/javascripts/highlight.js"
``` js
document$.subscribe(() => {
hljs.highlightAll()
})
```
=== ":octicons-file-code-16: mkdocs.yml"
``` yaml
extra_javascript:
- https://cdnjs.cloudflare.com/ajax/libs/highlight.js/10.7.2/highlight.min.js
- javascripts/highlight.js
extra_css:
- https://cdnjs.cloudflare.com/ajax/libs/highlight.js/10.7.2/styles/default.min.css
```
Note that [Highlight.js] has no affiliation with the Highlight extension.
`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
code blocks, consult the section on [adding line numbers][Adding line
numbers] in the code block reference, which also contains some tips on
working with line numbers:
``` yaml
markdown_extensions:
- pymdownx.highlight:
linenums: true
```
`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
Material for MkDocs. While `table` wraps a code block in a table, `inline`
and `pymdownx-inline` render line numbers as part of the line itself:
``` yaml
markdown_extensions:
- pymdownx.highlight:
linenums_style: pymdownx-inline
```
Note that `inline` will put line numbers next to the actual code, which
means that they will be included when selecting text with the cursor or
copying a code block to the clipboard. Thus, the usage of either `table`
or `pymdownx-inline` is recommended.
The other configuration options of this extension are not officially supported
by Material for MkDocs, which is why they may yield unexpected results. Use
them at your own risk.
See reference for usage:
- [Specifying the language]
- [Adding line numbers]
- [Highlighting specific lines]
- [Custom syntax theme]
[Highlight]: https://facelessuser.github.io/pymdown-extensions/extensions/highlight/
[Highlight support]: https://github.com/squidfunk/mkdocs-material/releases/tag/5.0.0
[CodeHilite]: python-markdown.md#codehilite
[pymdownx.superfences]: #superfences
[pymdownx.inlinehilite]: #inlinehilite
[Pygments]: https://pygments.org
[additional CSS]: ../../customization.md#additional-css
[Highlight.js]: https://highlightjs.org/
[Adding line numbers]: ../../reference/code-blocks.md#adding-line-numbers
[Specifying the language]: ../../reference/code-blocks.md#specifying-the-language
[Highlighting specific lines]: ../../reference/code-blocks.md#highlighting-specific-lines
[Custom syntax theme]: ../../reference/code-blocks.md#custom-syntax-theme
### InlineHilite
[:octicons-tag-24: 5.0.0][InlineHilite support] ·
[:octicons-workflow-24: Extension][InlineHilite]
The [InlineHilite] extension add support for syntax highlighting of inline code
blocks. It's built on top of the [Highlight][pymdownx.highlight] extension, from
which it sources its configuration. Enable it via `mkdocs.yml`:
``` yaml
markdown_extensions:
- pymdownx.highlight
- pymdownx.inlinehilite
```
The configuration options of this extension are not specific to Material for
MkDocs, as they only impact the Markdown parsing stage. The only exception is
the [`css_class`][InlineHilite options] option, which must not be changed. See the
[InlineHilite documentation][InlineHilite] for guidance.
See reference for usage:
- [Highlighting inline code blocks]
[InlineHilite]: https://facelessuser.github.io/pymdown-extensions/extensions/inlinehilite/
[InlineHilite support]: https://github.com/squidfunk/mkdocs-material/releases/tag/5.0.0
[InlineHilite options]: https://facelessuser.github.io/pymdown-extensions/extensions/inlinehilite/#options
[pymdownx.highlight]: #highlight
[Highlighting inline code blocks]: ../../reference/code-blocks.md#highlighting-inline-code-blocks
### Keys
[:octicons-tag-24: 1.0.0][Keys support] ·
[:octicons-workflow-24: Extension][Keys]
The [Keys] extension adds a simple syntax to allow for the rendering of keyboard
keys and combinations, e.g. ++ctrl+alt+del++. Enable it via `mkdocs.yml`:
``` yaml
markdown_extensions:
- pymdownx.keys
```
The configuration options of this extension are not specific to Material for
MkDocs, as they only impact the Markdown parsing stage. The only exception is
the [`class`][Keys options] option, which must not be changed. See the
[Keys documentation][Keys] for more information.
See reference for usage:
- [Adding keyboard keys]
[Keys]: https://facelessuser.github.io/pymdown-extensions/extensions/keys/
[Keys support]: https://github.com/squidfunk/mkdocs-material/releases/tag/1.0.0
[Keys options]: https://facelessuser.github.io/pymdown-extensions/extensions/keys/#options
[Adding keyboard keys]: ../../reference/formatting.md#adding-keyboard-keys
### SmartSymbols
[:octicons-tag-24: 0.1.0][SmartSymbols support] ·
[:octicons-workflow-24: Extension][SmartSymbols]
The [SmartSymbols] extension converts some sequences of characters into their
corresponding symbols, e.h. copyright symbols or fractions. Enable it via
`mkdocs.yml`:
``` yaml
markdown_extensions:
- pymdownx.smartsymbols
```
The configuration options of this extension are not specific to Material for
MkDocs, as they only impact the Markdown parsing stage. See the [SmartSymbols
documentation][SmartSymbols] for guidance.
[SmartSymbols]: https://facelessuser.github.io/pymdown-extensions/extensions/smartsymbols/
[SmartSymbols support]: https://github.com/squidfunk/mkdocs-material/releases/tag/0.1.0
### Snippets
[:octicons-tag-24: 0.1.0][Snippets support] ·
[:octicons-workflow-24: Extension][Snippets]
The [Snippets] extension adds the ability to embed content from arbitrary files
into a document, including other documents or source files, by using a simple
syntax. Enable it via `mkdocs.yml`:
``` yaml
markdown_extensions:
- pymdownx.snippets
```
The configuration options of this extension are not specific to Material for
MkDocs, as they only impact the Markdown parsing stage. See the [Snippets
documentation][Snippets] for more information.
See reference for usage:
- [Adding a glossary]
- [Embedding external files]
[Snippets]: https://facelessuser.github.io/pymdown-extensions/extensions/snippets/
[Snippets support]: https://github.com/squidfunk/mkdocs-material/releases/tag/0.1.0
[Adding a glossary]: ../../reference/abbreviations.md#adding-a-glossary
[Embedding external files]: ../../reference/code-blocks.md#embedding-external-files
### SuperFences
[:octicons-tag-24: 0.1.0][SuperFences support] ·
[:octicons-workflow-24: Extension][SuperFences] ·
:octicons-zap-24: Supersedes [Fenced Code Blocks]
The [SuperFences] extension allows for arbitrary nesting of code and content
blocks inside each other, including admonitions, tabs, lists and all other
elements. Enable it via `mkdocs.yml`:
``` yaml
markdown_extensions:
- pymdownx.superfences
```
The following configuration options are supported:
`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]
diagrams to be interpreted in the browser:
``` yaml
markdown_extensions:
- pymdownx.superfences:
custom_fences:
- name: mermaid
class: mermaid
format: !!python/name:pymdownx.superfences.fence_code_format
```
Note that this will primarily prevent syntax highlighting from being
applied. See the reference on [diagrams] to learn how Mermaid.js is
integrated with Material for MkDocs.
The other configuration options of this extension are not officially supported
by Material for MkDocs, which is why they may yield unexpected results. Use
them at your own risk.
See reference for usage:
- [Using flowcharts]
- [Using sequence diagrams]
- [Using state diagrams]
- [Using class diagrams]
- [Using entity-relationship diagrams]
[SuperFences]: https://facelessuser.github.io/pymdown-extensions/extensions/superfences/
[SuperFences support]: https://github.com/squidfunk/mkdocs-material/releases/tag/0.1.0
[Fenced Code Blocks]: python-markdown.md#fenced-code-blocks
[Mermaid.js]: https://mermaid-js.github.io/mermaid/
[diagrams]: ../../reference/diagrams.md
[Using flowcharts]: ../../reference/diagrams.md#using-flowcharts
[Using sequence diagrams]: ../../reference/diagrams.md#using-sequence-diagrams
[Using state diagrams]: ../../reference/diagrams.md#using-state-diagrams
[Using class diagrams]: ../../reference/diagrams.md#using-class-diagrams
[Using entity-relationship diagrams]: ../../reference/diagrams.md#using-entity-relationship-diagrams
### Tabbed
[:octicons-tag-24: 5.0.0][Tabbed support] ·
[:octicons-workflow-24: Extension][Tabbed]
The [Tabbed] extension allows the usage of content tabs, a simple way to group
related content and code blocks under accessible tabs. Enable it via
`mkdocs.yml`:
``` yaml
markdown_extensions:
- pymdownx.tabbed:
alternate_style: true
```
The following configuration options are supported:
`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
content tabs, which has [better behavior on mobile viewports], and thus
is strongly recommended:
``` yaml
markdown_extensions:
- pymdownx.tabbed:
alternate_style: true
```
The other configuration options of this extension are not officially supported
by Material for MkDocs, which is why they may yield unexpected results. Use
them at your own risk.
See reference for usage:
- [Grouping code blocks]
- [Grouping other content]
- [Embedded content]
[Tabbed]: https://facelessuser.github.io/pymdown-extensions/extensions/tabbed/
[Tabbed support]: https://github.com/squidfunk/mkdocs-material/releases/tag/5.0.0
[Tabbed alternate support]: https://github.com/squidfunk/mkdocs-material/releases/tag/7.3.1
[alternate style]: https://facelessuser.github.io/pymdown-extensions/extensions/tabbed/#alternate-style
[better behavior on mobile viewports]: https://twitter.com/squidfunk/status/1424740370596958214
[Grouping code blocks]: ../../reference/content-tabs.md#grouping-code-blocks
[Grouping other content]: ../../reference/content-tabs.md#grouping-other-content
[Embedded content]: ../../reference/content-tabs.md#embedded-content
### Tasklist
[:octicons-tag-24: 1.0.0][Tasklist support] ·
[:octicons-workflow-24: Extension][Tasklist]
The [Tasklist] extension allows for the usage of [GitHub Flavored Markdown]
inspired [task lists][Tasklist specification], following the same syntactical
conventions. Enable it via `mkdocs.yml`:
``` yaml
markdown_extensions:
- pymdownx.tasklist:
custom_checkbox: true
```
The following configuration options are supported:
`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,
and is therefore recommended:
``` yaml
markdown_extensions:
- pymdownx.tasklist:
custom_checkbox: true
```
`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
option is _rather discouraged_ from a user experience perspective:
``` yaml
markdown_extensions:
- pymdownx.tasklist:
clickable_checkbox: true
```
The other configuration options of this extension are not officially supported
by Material for MkDocs, which is why they may yield unexpected results. Use
them at your own risk.
See reference for usage:
- [Using task lists]
[Tasklist]: https://facelessuser.github.io/pymdown-extensions/extensions/tasklist/
[Tasklist support]: https://github.com/squidfunk/mkdocs-material/releases/tag/1.0.0
[GitHub Flavored Markdown]: https://github.github.com/gfm/
[Tasklist specification]: https://github.github.com/gfm/#task-list-items-extension-
[Using task lists]: ../../reference/lists.md#using-task-lists

348
docs/setup/extensions/python-markdown.md Normal file
View File

@ -0,0 +1,348 @@
---
template: overrides/main.html
---
# Python Markdown
Material for MkDocs supports a large number of [Python Markdown] extensions,
which is part of what makes it so attractive for technical writing. Following
is a list of all supported extensions, linking to the relevant sections of the
reference for which features they need to be enabled.
[Python Markdown]: https://python-markdown.github.io/
## Supported extensions
### Abbreviations
[:octicons-tag-24: 1.0.0][Abbreviations support] ·
[:octicons-workflow-24: Extension][Abbreviations]
The [Abbreviations] extension adds the ability to add a small tooltip to an
element, by wrapping it with an `abbr` tag. Only plain text (no markup) is
supported. Enable it via `mkdocs.yml`:
``` yaml
markdown_extensions:
- abbr
```
No configuration options are available. See reference for usage:
- [Adding abbreviations]
- [Adding a glossary]
[Abbreviations]: https://python-markdown.github.io/extensions/abbreviations/
[Abbreviations support]: https://github.com/squidfunk/mkdocs-material/releases/tag/1.0.0
[Adding abbreviations]: ../../reference/abbreviations.md#adding-abbreviations
[Adding a glossary]: ../../reference/abbreviations.md#adding-a-glossary
### Admonition
[:octicons-tag-24: 0.1.0][Admonition support] ·
[:octicons-workflow-24: Extension][Admonition]
The [Admonition] extension adds support for admonitions, more commonly known as
_call-outs_, which can be defined in Markdown by using a simple syntax. Enable
it via `mkdocs.yml`:
``` yaml
markdown_extensions:
- admonition
```
No configuration options are available. See reference for usage:
- [Adding admonitions]
- [Changing the title]
- [Removing the title]
- [Supported types]
[Admonition]: https://python-markdown.github.io/extensions/admonition/
[Admonition support]: https://github.com/squidfunk/mkdocs-material/releases/tag/0.1.0
[Adding admonitions]: ../../reference/admonitions.md#usage
[Changing the title]: ../../reference/admonitions.md#changing-the-title
[Removing the title]: ../../reference/admonitions.md#removing-the-title
[Supported types]: ../../reference/admonitions.md#supported-types
### Attribute Lists
[:octicons-tag-24: 0.1.0][Attribute Lists support] ·
[:octicons-workflow-24: Extension][Attribute Lists]
The [Attribute Lists] extension allows to add HTML attributes and CSS classes
to [almost every][Attribute Lists limitations] Markdown inline- and block-level
element with a special syntax. Enable it via `mkdocs.yml`:
``` yaml
markdown_extensions:
- attr_list
```
No configuration options are available. See reference for usage:
- [Adding buttons]
- [Adding icons with colors]
- [Image alignment]
- [Image lazy-loading]
[Attribute Lists]: https://python-markdown.github.io/extensions/attr_list/
[Attribute Lists support]: https://github.com/squidfunk/mkdocs-material/releases/tag/0.1.0
[Attribute Lists limitations]: https://python-markdown.github.io/extensions/attr_list/#limitations
[Adding buttons]: ../../reference/buttons.md#adding-buttons
[Adding icons with colors]: ../../reference/buttons.md#with-colors
[Image alignment]: ../../reference/images.md#image-alignment
[Image lazy-loading]: ../../reference/images.md#image-lazy-loading
### Definition Lists
[:octicons-tag-24: 1.1.0][Definition Lists support] ·
[:octicons-workflow-24: Extension][Definition Lists]
The [Definition Lists] extension adds the ability to add definition lists (more
commonly known as [description lists] – `dl` in HTML) via Markdown to a
document. Enable it via `mkdocs.yml`:
``` yaml
markdown_extensions:
- def_list
```
No configuration options are available. See reference for usage:
- [Using definition lists]
[Definition Lists]: https://python-markdown.github.io/extensions/definition_lists/
[Definition Lists support]: https://github.com/squidfunk/mkdocs-material/releases/tag/1.1.0
[description lists]: https://developer.mozilla.org/en-US/docs/Web/HTML/Element/dl
[Using definition lists]: ../../reference/lists.md#using-definition-lists
### Footnotes
[:octicons-tag-24: 1.0.0][Footnotes support] ·
[:octicons-workflow-24: Extension][Footnotes]
The [Footnotes] extension allows to define inline footnotes, which are then
rendered below all Markdown content of a document. Enable it via `mkdocs.yml`:
``` yaml
markdown_extensions:
- footnotes
```
No configuration options are supported. See reference for usage:
- [Adding footnote references]
- [Adding footnote content]
[Footnotes]: https://python-markdown.github.io/extensions/footnotes/
[Footnotes support]: https://github.com/squidfunk/mkdocs-material/releases/tag/1.0.0
[Adding footnote references]: ../../reference/footnotes.md#adding-footnote-references
[Adding footnote content]: ../../reference/footnotes.md#adding-footnote-content
### Metadata
[:octicons-tag-24: 1.0.0][Metadata support] ·
[:octicons-workflow-24: Extension][Metadata]
The [Metadata] extension adds the ability to attach arbitrary key-value pairs
to a document via front matter written in YAML syntax before the Markdown.
Enable it via `mkdocs.yml`:
``` yaml
markdown_extensions:
- meta
```
No configuration options are available. See reference for usage:
- [Setting the page title]
- [Setting the page description]
- [Hiding the sidebars]
- [Adding tags]
[Metadata]: https://python-markdown.github.io/extensions/meta_data/
[Metadata support]: https://github.com/squidfunk/mkdocs-material/releases/tag/1.0.0
[Setting the page title]: ../../reference/meta-tags.md#setting-the-page-title
[Setting the page description]: ../../reference/meta-tags.md#setting-the-page-description
[Hiding the sidebars]: ../../setup/setting-up-navigation.md#hiding-the-sidebars
[Adding tags]: ../../setup/setting-up-tags.md#adding-tags
### Markdown in HTML
[:octicons-tag-24: 0.1.0][Markdown in HTML support] ·
[:octicons-workflow-24: Extension][Markdown in HTML]
The [Markdown in HTML] extension allows for writing Markdown inside of HTML,
which is useful for wrapping Markdown content with custom elements. Enable it
via `mkdocs.yml`:
``` yaml
markdown_extensions:
- md_in_html
```
> By default, Markdown ignores any content within a raw HTML block-level
> element. With the `md_in_html` extension enabled, the content of a raw HTML
> block-level element can be parsed as Markdown by including a `markdown`
> attribute on the opening tag. The `markdown` attribute will be stripped from
> the output, while all other attributes will be preserved.
No configuration options are available. See reference for usage:
- [Image captions]
[Markdown in HTML]: https://python-markdown.github.io/extensions/md_in_html/
[Markdown in HTML support]: https://github.com/squidfunk/mkdocs-material/releases/tag/0.1.0
[Image captions]: ../../reference/images.md#image-captions
### Table of Contents
[:octicons-tag-24: 0.1.0][Table of Contents support] ·
[:octicons-workflow-24: Extension][Table of Contents]
The [Table of Contents] extension automatically generates a table of contents
from a document, which Material for MkDocs will render as part of the resulting
page. Enable it via `mkdocs.yml`:
``` yaml
markdown_extensions:
- toc:
permalink: true
```
The following configuration options are supported:
`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
each headline, exactly like on the page you're currently viewing, which
Material for MkDocs will make appear on hover:
=== "¶"
``` yaml
markdown_extensions:
- toc:
permalink: true
```
=== "⚓︎"
``` yaml
markdown_extensions:
- toc:
permalink: ⚓︎
```
`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
produce good and readable identifiers – consider using another slug function
like for example those from [Python Markdown Extensions][Slugs]:
=== "Unicode"
``` yaml
markdown_extensions:
- toc:
slugify: !!python/name:pymdownx.slugs.uslugify
```
=== "Unicode, case-sensitive"
``` yaml
markdown_extensions:
- toc:
slugify: !!python/name:pymdownx.slugs.uslugify_cased
```
`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
documentation with deeply structured headings to decrease the length of the
table of contents, or to remove the table of contents altogether:
=== "Hide levels 4-6"
``` yaml
markdown_extensions:
- toc:
toc_depth: 3
```
=== "Hide table of contents"
``` yaml
markdown_extensions:
- toc:
toc_depth: 0
```
The other configuration options of this extension are not officially supported
by Material for MkDocs, which is why they may yield unexpected results. Use them at your
own risk.
[Table of Contents]: https://python-markdown.github.io/extensions/toc/
[Table of Contents support]: https://github.com/squidfunk/mkdocs-material/releases/tag/0.1.0
[Slugs]: https://facelessuser.github.io/pymdown-extensions/extras/slugs/
### Tables
[:octicons-tag-24: 0.1.0][Tables support] ·
[:octicons-workflow-24: Extension][Tables]
The [Tables] extension adds the ability to create tables in Markdown by using a
simple syntax. Enable it via `mkdocs.yml` (albeit it should be enabled by
default):
``` yaml
markdown_extensions:
- tables
```
No configuration options are available. See reference for usage:
- [Using data tables]
- [Column alignment]
[Tables]: https://python-markdown.github.io/extensions/tables/
[Tables support]: https://github.com/squidfunk/mkdocs-material/releases/tag/0.1.0
[Using data tables]: ../../reference/data-tables.md#using-data-tables
[Column alignment]: ../../reference/data-tables.md#column-alignment
## Superseded extensions
The following [Python Markdown] extensions are not (or might not be) supported
anymore, and are therefore not recommended for use. Instead, the alternatives
should be considered.
### Fenced Code Blocks
[:octicons-tag-24: 0.1.0][Fenced Code Blocks support] ·
[:octicons-workflow-24: Extension][Fenced Code Blocks]
Superseded by [SuperFences]. This extension might still work, but the
[SuperFences] extension is superior in many ways, as it allows for arbitrary
nesting, and is therefore recommended.
[Fenced Code Blocks]: https://python-markdown.github.io/extensions/fenced_code_blocks/
[Fenced Code Blocks support]: https://github.com/squidfunk/mkdocs-material/releases/tag/0.1.0
[SuperFences]: https://facelessuser.github.io/pymdown-extensions/extensions/superfences/
### CodeHilite
[:octicons-tag-24: 0.1.0 ... 5.5.14][CodeHilite support] ·
[:octicons-workflow-24: Extension][CodeHilite]
Superseded by [Highlight]. Support for CodeHilite was dropped in
:octicons-tag-24: 6.0.0, as [Highlight] has a better integration with other
essential extensions like [SuperFences] and [InlineHilite].
[CodeHilite]: https://python-markdown.github.io/extensions/code_hilite/
[CodeHilite support]: https://github.com/squidfunk/mkdocs-material/releases/tag/0.1.0
[Highlight]: https://facelessuser.github.io/pymdown-extensions/extensions/highlight/
[InlineHilite]: https://facelessuser.github.io/pymdown-extensions/extensions/inlinehilite/

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

@ -6,22 +6,23 @@ 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][1] and [sections][2],
and its flag-ship feature: [instant loading][3].
the behavior of navigational elements, including [tabs][navigation.tabs] and
[sections][navigation.sections], and its flag-ship feature: [instant loading]
[navigation.instant].
[1]: #navigation-tabs
[2]: #navigation-sections
[3]: #instant-loading
[navigation.tabs]: #navigation-tabs
[navigation.sections]: #navigation-sections
[navigation.instant]: #instant-loading
## Configuration
### Instant loading
[:octicons-file-code-24: Source][4] ·
[:octicons-tag-24: 5.0.0][navigation.instant support] ·
:octicons-unlock-24: Feature flag
When _instant loading_ is enabled, clicks on all internal links will be
intercepted and dispatched via [XHR][5] without fully reloading the page. Add
When instant loading is enabled, clicks on all internal links will be
intercepted and dispatched via [XHR] without fully reloading the page. Add
the following lines to `mkdocs.yml`:
``` yaml
@ -31,23 +32,21 @@ theme:
```
The resulting page is parsed and injected and all event handlers and components
are rebound automatically. This means that __Material for MkDocs behaves like a
Single Page Application__, which is especially useful for large documentation
sites that come with a massive search index, as the search index will now
remain intact in-between document switches.
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.
_Material for MkDocs is the only MkDocs theme offering this feature._
[4]: https://github.com/squidfunk/mkdocs-material/blob/master/src/assets/javascripts/integrations/instant/index.ts
[5]: https://developer.mozilla.org/en-US/docs/Web/API/XMLHttpRequest
[navigation.instant 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
[:octicons-file-code-24: Source][6] ·
[:octicons-heart-fill-24:{ .mdx-heart } Insiders][Insiders]{ .mdx-insiders } ·
[:octicons-tag-24: insiders-2.1.0][Insiders] ·
:octicons-unlock-24: Feature flag ·
[:octicons-heart-fill-24:{ .mdx-heart } Insiders only][6]{ .mdx-insiders }
:octicons-beaker-24: Experimental
When _anchor tracking_ is enabled, the URL in the address bar is automatically
When anchor tracking is enabled, the URL in the address bar is automatically
updated with the active anchor as highlighted in the table of contents. Add the
following lines to `mkdocs.yml`:
@ -57,24 +56,25 @@ theme:
- navigation.tracking
```
[6]: ../insiders/index.md
[Insiders]: ../insiders/index.md
### Navigation tabs
[:octicons-file-code-24: Source][7] · :octicons-unlock-24: Feature flag
[: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
When tabs are enabled, top-level sections are rendered in a menu layer below
the header for viewports above `1220px`, but remain as-is on mobile.[^1] Add
the following lines to `mkdocs.yml`:
[^1]:
Prior to version 6.2, navigation tabs had a slightly different behavior.
All top-level pages (i.e. all top-level entries that directly refer to an
`*.md` file) defined inside the `nav` entry of `mkdocs.yml` were grouped
under the first tab which received the title of the first page. This made
it impossible to include a top-level page (or external link) as a tab item,
as was reported in #1884 and #2072. From version 6.2 on, navigation tabs
include all top-level pages and sections.
Prior to :octicons-tag-24: 6.2.0, navigation tabs had a slightly different
behavior. All top-level pages (i.e. all top-level entries directly
refefring to a `*.md` file) defined inside the `nav` entry of `mkdocs.yml`
were grouped under the first tab which received the title of the first page.
This made it impossible to include a top-level page (or external link) as a
tab item, as was reported in #1884 and #2072. From :octicons-tag-24: 6.2.0
on, navigation tabs include all top-level pages and sections.
``` yaml
theme:
@ -82,25 +82,25 @@ theme:
- navigation.tabs
```
=== "With tabs"
=== ":octicons-check-circle-fill-16: Enabled"
[![With tabs][8]][8]
[![navigation.tabs enabled]][navigation.tabs enabled]
=== "Without tabs"
=== ":octicons-skip-16: Disabled"
[![Without tabs][9]][9]
[![navigation.tabs disabled]][navigation.tabs disabled]
[7]: https://github.com/squidfunk/mkdocs-material/blob/master/src/partials/tabs.html
[8]: ../assets/screenshots/navigation-tabs.png
[9]: ../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-file-code-24: Source][10] ·
[:octicons-tag-24: 7.3.0][navigation.tabs.sticky support] ·
:octicons-unlock-24: Feature flag ·
:octicons-beaker-24: Experimental
When _sticky tabs_ are enabled, navigation tabs will lock below the header and
When sticky tabs are enabled, navigation tabs will lock below the header and
always remain visible when scrolling down. Just add the following two feature
flags to `mkdocs.yml`:
@ -111,24 +111,24 @@ theme:
- navigation.tabs.sticky
```
=== "With sticky tabs"
=== ":octicons-check-circle-fill-16: Enabled"
[![With sticky tabs][11]][11]
[![navigation.tabs.sticky enabled]][navigation.tabs.sticky enabled]
=== "Without sticky tabs"
=== ":octicons-skip-16: Disabled"
[![Without sticky tabs][12]][12]
[![navigation.tabs.sticky disabled]][navigation.tabs.sticky disabled]
[10]: https://github.com/squidfunk/mkdocs-material/blob/master/src/partials/header.html
[11]: ../assets/screenshots/navigation-tabs-sticky.png
[12]: ../assets/screenshots/navigation-tabs-collapsed.png
[navigation.tabs.sticky support]: https://github.com/squidfunk/mkdocs-material/releases/tag/7.3.0
[navigation.tabs.sticky enabled]: ../assets/screenshots/navigation-tabs.png
[navigation.tabs.sticky disabled]: ../assets/screenshots/navigation.png
### Navigation sections
[:octicons-file-code-24: Source][13] ·
[: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
When sections are enabled, top-level sections are rendered as groups in the
sidebar for viewports above `1220px`, but remain as-is on mobile. Add the
following lines to `mkdocs.yml`:
@ -138,27 +138,29 @@ theme:
- navigation.sections
```
=== "With sections"
=== ":octicons-check-circle-fill-16: Enabled"
[![With sections][14]][14]
[![navigation.sections enabled]][navigation.sections enabled]
=== "Without sections"
=== ":octicons-skip-16: Disabled"
[![Without sections][9]][9]
[![navigation.sections disabled]][navigation.sections disabled]
[13]: https://github.com/squidfunk/mkdocs-material/blob/master/src/partials/nav-item.html
[14]: ../assets/screenshots/navigation-sections.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, _tabs_ and _sections_, can be combined with each other. If
both feature flags are enabled, sections are rendered for level 2 navigation
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.
### Navigation expansion
[:octicons-file-code-24: Source][13] ·
[:octicons-tag-24: 6.2.0][navigation.expand support] ·
:octicons-unlock-24: Feature flag
When _expansion_ is enabled, the left sidebar will expand all collapsible
When expansion is enabled, the left sidebar will expand all collapsible
subsections by default, so the user doesn't have to open subsections manually.
Add the following lines to `mkdocs.yml`:
@ -168,23 +170,25 @@ theme:
- navigation.expand
```
=== "With expansion"
=== ":octicons-check-circle-fill-16: Enabled"
[![With expansion][15]][15]
[![navigation.expand enabled]][navigation.expand enabled]
=== "Without expansion"
=== ":octicons-skip-16: Disabled"
[![Without expansion][9]][9]
[![navigation.expand disabled]][navigation.expand disabled]
[15]: ../assets/screenshots/navigation-expand.png
[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
### Section index pages
[:octicons-file-code-24: Source][16] ·
[:octicons-tag-24: 7.3.0][navigation.indexes support] ·
:octicons-unlock-24: Feature flag ·
:octicons-beaker-24: Experimental
When _section index pages_ are enabled, documents can be directly attached to
When section index pages are enabled, documents can be directly attached to
sections, which is particularly useful for providing overview pages. Add the
following lines to `mkdocs.yml`:
@ -194,13 +198,13 @@ theme:
- navigation.indexes
```
=== "With section index pages"
=== ":octicons-check-circle-fill-16: Enabled"
[![With expansion][17]][17]
[![navigation.indexes enabled]][navigation.indexes enabled]
=== "Without section index pages"
=== ":octicons-skip-16: Disabled"
[![Without expansion][18]][18]
[![navigation.indexes disabled]][navigation.indexes 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
@ -215,20 +219,50 @@ nav:
- Page n: section/page-n.md
```
_This feature flag can be combined with all other feature flags, e.g. [tabs][1]
and [sections][2], except for table of contents [navigation integration][19]._
This feature flag is not compatible with [`toc.integrate`][toc.integrate].
[16]: https://github.com/squidfunk/mkdocs-material/blob/master/src/partials/nav-item.html
[17]: ../assets/screenshots/navigation-index-on.png
[18]: ../assets/screenshots/navigation-index-off.png
[19]: #navigation-integration
[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
[toc.integrate]: #integrated-table-of-contents
### Integrated table of contents
[:octicons-tag-24: 6.2.0][toc.integrate support] ·
:octicons-unlock-24: Feature flag
When navigation integration for the table of contents is enabled, it is always
rendered as part of the navigation sidebar on the left. Add the following lines
to `mkdocs.yml`:
``` yaml
theme:
features:
- toc.integrate
```
=== ":octicons-check-circle-fill-16: Enabled"
[![toc.integrate enabled]][toc.integrate enabled]
=== ":octicons-skip-16: Disabled"
[![toc.integrate disabled]][toc.integrate disabled]
This feature flag is not compatible with [`navigation.indexes`]
[navigation.indexes].
[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.indexes]: #section-index-pages
### Back-to-top button
[:octicons-file-code-24: Source][20] ·
[:octicons-tag-24: 7.1.0][navigation.top support] ·
:octicons-unlock-24: Feature flag
A _back-to-top button_ can be shown when the user, after scrolling down, starts
A back-to-top button can be shown when the user, after scrolling down, starts
to scroll up again. It's rendered centered and just below the header. Add the
following lines to `mkdocs.yml`:
@ -238,137 +272,15 @@ theme:
- navigation.top
```
[![back-to-top button][21]][21]
[20]: https://github.com/squidfunk/mkdocs-material/blob/master/src/assets/stylesheets/main/layout/_top.scss
[21]: ../assets/screenshots/back-to-top.png
### Table of contents
[:octicons-file-code-24: Source][22] · [:octicons-workflow-24: Extension][23]
The [Table of contents][24] extension, which is part of the standard Markdown
library, provides some options that are supported by Material for MkDocs to
customize its appearance:
`permalink`{ #permalink }
: :octicons-milestone-24: Default: `false` – This option adds an anchor link
containing the paragraph symbol `¶` or another custom symbol at the end of
each headline, exactly like on the page you're currently viewing, which
Material for MkDocs will make appear on hover:
=== "¶"
``` yaml
markdown_extensions:
- toc:
permalink: true
```
=== "⚓︎"
``` yaml
markdown_extensions:
- toc:
permalink: ⚓︎
```
`slugify`{ #slugify }
: :octicons-milestone-24: Default: `headerid.slugify` – This option allows for
customization of the slug function. For some languages, the default may not
produce good and readable identifiers – consider using another slug function
like for example those from [Python Markdown Extensions][25]:
=== "Unicode"
``` yaml
markdown_extensions:
- toc:
slugify: !!python/name:pymdownx.slugs.uslugify
```
=== "Unicode, case-sensitive"
``` yaml
markdown_extensions:
- toc:
slugify: !!python/name:pymdownx.slugs.uslugify_cased
```
`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
documentation with deeply structured headings to decrease the length of the
table of contents, or to remove the table of contents altogether:
=== "Hide levels 4-6"
``` yaml
markdown_extensions:
- toc:
toc_depth: 3
```
=== "Hide table of contents"
``` yaml
markdown_extensions:
- toc:
toc_depth: 0
```
_Material for MkDocs doesn't provide official support for the other options of
this extension, so they may be supported but might yield unexpected results.
Use them at your own risk._
[22]: https://github.com/squidfunk/mkdocs-material/blob/master/src/partials/toc.html
[23]: https://python-markdown.github.io/extensions/toc/
[24]: https://python-markdown.github.io/extensions/toc/#usage
[25]: https://facelessuser.github.io/pymdown-extensions/extras/slugs/
#### Navigation integration
[:octicons-file-code-24: Source][26] ·
:octicons-unlock-24: Feature flag
When _integration_ is enabled, the table of contents is rendered as part of
the navigation for viewports above `1220px`, but remains as-is on mobile. Add
the following lines to `mkdocs.yml`:
``` yaml
theme:
features:
- toc.integrate
```
=== "Integrate table of contents"
[![Integrate table of contents][27]][27]
=== "Separate table of contents"
[![Separate table of contents][8]][8]
[26]: https://github.com/squidfunk/mkdocs-material/blob/master/src/assets/stylesheets/main/layout/_nav.scss
[27]: ../assets/screenshots/toc-integrate.png
The content section will now always stretch to the right side, resulting in
more space for your content. This feature flag can be combined with all other
feature flags, e.g. [tabs][1] and [sections][2].
[navigation.top support]: https://github.com/squidfunk/mkdocs-material/releases/tag/7.1.0
## Usage
### Hiding the sidebars
[:octicons-file-code-24: Source][28] ·
:octicons-note-24: Metadata
Sometimes it's desirable to hide the navigation and/or table of contents
sidebar, especially when there's a single navigation item. This can be done for
any page using the [Metadata][29] extension:
When [Metadata] is enabled, the navigation and/or table of contents sidebars
can be hidden for a document with custom front matter. Add the following lines
at the top of a Markdown file:
``` bash
---
@ -383,33 +295,29 @@ hide:
=== "Hide navigation"
[![Hide navigation][30]][30]
[![hide.navigation enabled]][hide.navigation enabled]
=== "Hide table of contents"
[![Hide table of contents][31]][31]
[![hide.toc enabled]][hide.toc enabled]
=== "Hide both"
[![Hide navigation and table of contents][32]][32]
[![hide.* enabled]][hide.* enabled]
[28]: https://github.com/squidfunk/mkdocs-material/blob/master/src/base.html
[29]: ../../reference/meta-tags/#metadata
[30]: ../assets/screenshots/hide-navigation.png
[31]: ../assets/screenshots/hide-toc.png
[32]: ../assets/screenshots/hide-navigation-toc.png
[Metadata]: extensions/python-markdown.md#metadata
[hide.navigation enabled]: ../assets/screenshots/hide-navigation.png
[hide.toc enabled]: ../assets/screenshots/hide-toc.png
[hide.* enabled]: ../assets/screenshots/hide-navigation-toc.png
## Customization
### Keyboard shortcuts
[:octicons-file-code-24: Source][33] ·
:octicons-mortar-board-24: Difficulty: _easy_
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:
@ -418,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
@ -429,48 +337,54 @@ to navigate your project documentation via keyboard. There're two modes:
* ++n++ , ++period++ : go to next page
Let's say you want to bind some action to the ++x++ key. By using [additional
JavaScript][34], you can subscribe to the `keyboard$` observable and attach
JavaScript], you can subscribe to the `keyboard$` observable and attach
your custom event listener:
``` js
keyboard$.subscribe(function(key) {
=== ":octicons-file-code-16: docs/javascripts/shortcuts.js"
``` js
keyboard$.subscribe(function(key) {
if (key.mode === "global" && key.type === "x") {
/* Add custom keyboard handler here */
key.claim()
key.claim() // (1)
}
})
```
})
```
The call to `#!js key.claim()` will essentially execute `#!js preventDefault()`
on the underlying event, so the keypress will not propagate further and touch
other event listeners.
1. The call to `key.claim()` will execute `preventDefault()` on the
underlying event, so the keypress will not propagate further and
touch other event listeners.
[33]: https://github.com/squidfunk/mkdocs-material/blob/master/src/assets/javascripts/integrations/keyboard/index.ts
[34]: ../customization.md#additional-javascript
=== ":octicons-file-code-16: mkdocs.yml"
``` yaml
extra_javascript:
- javascripts/shortcuts.js
```
[additional JavaScript]: ../customization.md#additional-javascript
### Content area width
[:octicons-file-code-24: Source][35] ·
:octicons-mortar-board-24: Difficulty: _easy_
The width of the content area is set so the length of each line doesn't exceed
80-100 characters, depending on the width of the characters. While this
is a reasonable default, as longer lines tend to be harder to read, it may be
desirable to increase the overall width of the content area, or even make it
stretch to the entire available space.
This can easily be achieved with an [additional stylesheet][36] and a few lines
This can easily be achieved with an [additional style sheet] and a few lines
of CSS:
=== "Increase width"
=== ":octicons-file-code-16: docs/stylesheets/extra.css"
``` css
.md-grid {
max-width: 1440px;
max-width: 1440px; /* (1) */
}
```
=== "Stretch to fit"
1. If you want the content area to always stretch to the available screen
space, reset `max-width` with the following CSS:
``` css
.md-grid {
@ -478,5 +392,11 @@ of CSS:
}
```
[35]: https://github.com/squidfunk/mkdocs-material/blob/aeaa00a625abf952f355164de02c539b061e6127/src/assets/stylesheets/main/layout/_base.scss
[36]: ../customization.md#additional-css
=== ":octicons-file-code-16: mkdocs.yml"
``` yaml
extra_css:
- stylesheets/extra.css
```
[additional style sheet]: ../customization.md#additional-css

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

@ -6,23 +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-file-code-24: Source][3] · :octicons-milestone-24: Default: _none_
[: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. Depending on the given property prefix, add the
following lines to `mkdocs.yml`:
=== "Google Analytics 4"
=== ":material-google-analytics: Google Analytics 4"
``` yaml
extra:
@ -31,7 +32,7 @@ the following to `mkdocs.yml`:
property: G-XXXXXXXXXX
```
=== "Universal Analytics"
=== ":material-google-analytics: Universal Analytics"
``` yaml
extra:
@ -40,11 +41,11 @@ the following to `mkdocs.yml`:
property: UA-XXXXXXXX-X
```
[3]: https://github.com/squidfunk/mkdocs-material/blob/master/src/partials/integrations/analytics.html
[Google Analytics support]: https://github.com/squidfunk/mkdocs-material/releases/tag/7.1.8
#### 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:
@ -54,20 +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-file-code-24: Source][5] ·
:octicons-milestone-24: Default: _none_ ·
[:octicons-heart-fill-24:{ .mdx-heart } Insiders only][5]{ .mdx-insiders }
[:octicons-heart-fill-24:{ .mdx-heart } Insiders][Insiders]{ .mdx-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
@ -86,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:
@ -100,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:
@ -115,78 +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 }
```
[5]: ../insiders/index.md
[6]: #custom-cookies
[7]: ../assets/screenshots/consent.png
[Insiders]: ../insiders/index.md
[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:
=== ":octicons-file-code-16: partials/integrations/analytics/custom.html"
``` html
<script>
/* Add custom analytics integration here, e.g. */
var property = "{{ config.extra.analytics.property }}" // (1)
/* Wait for page to load and application to mount */
document.addEventListener("DOMContentLoaded", function() {
location$.subscribe(function(url) {
/* Add custom page event tracking here */ // (2)
})
})
</script>
```
1. As an example, this variable receives the value set in `mkdocs.yml`,
which is `"foobar"` for `property`.
2. If you're using [instant loading], you can use the `location$`
observable to listen for navigation events, which always emits the
current `URL`.
=== ":octicons-file-code-16: mkdocs.yml"
``` yaml
extra:
analytics:
provider: custom # (1)
key: value # (2)
```
provider: custom
property: foobar # (1)
```
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.
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.
[8]: ../customization.md#extending-the-theme
[9]: https://github.com/squidfunk/mkdocs-material/tree/master/src/partials/integrations/analytics
#### Instant loading
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:
``` js
location$.subscribe(function(url) {
/* Track a page event */
})
```
Note that this must be integrated with [additional JavaScript][11].
[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) {
``` 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

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

@ -37,7 +37,7 @@ plugins:
The following options are supported:
`lang`{ #lang }
`lang`{ #search-lang }
: :octicons-milestone-24: Default: _automatically set_ – This option allows
to include the language-specific stemmers provided by [lunr-languages][5].
@ -65,7 +65,7 @@ The following options are supported:
The following languages are supported:
<div class="mdx-columns" markdown="1">
<div class="mdx-columns" markdown>
- `ar` – Arabic
- `da` – Danish
@ -98,7 +98,7 @@ 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: _automatically set_ – The separator for
indexing and query tokenization can be customized, making it possible to
@ -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
@ -146,11 +146,11 @@ Use them at your own risk._
### Search suggestions
[:octicons-file-code-24: Source][8] ·
:octicons-unlock-24: Feature flag ·
:octicons-beaker-24: Experimental
: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.
@ -166,17 +166,18 @@ Searching for [:octicons-search-24: search su][9] yields ^^search suggestions^^
[![Search suggestions][10]][10]
[Search suggestions support]: https://github.com/squidfunk/mkdocs-material/releases/tag/7.2.0
[8]: https://github.com/squidfunk/mkdocs-material/blob/master/src/assets/javascripts/components/search/suggest/index.ts
[9]: ?q=search+su
[10]: ../assets/screenshots/search-suggestions.png
### Search highlighting
[:octicons-file-code-24: Source][11] ·
:octicons-unlock-24: Feature flag ·
:octicons-beaker-24: Experimental
: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`:
@ -190,17 +191,18 @@ Searching for [:octicons-search-24: code blocks][12] yields:
[![Search highlighting][13]][13]
[Search highlighting support]: https://github.com/squidfunk/mkdocs-material/releases/tag/7.2.0
[11]: https://github.com/squidfunk/mkdocs-material/blob/master/src/assets/javascripts/components/search/highlight/index.ts
[12]: ../reference/code-blocks.md?h=code+blocks
[13]: ../assets/screenshots/search-highlighting.png
### Search sharing
[:octicons-file-code-24: Source][14] ·
:octicons-unlock-24: Feature flag ·
:octicons-beaker-24: Experimental
: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`:
@ -215,6 +217,7 @@ clipboard.
[![Search sharing][15]][15]
[Search sharing support]: https://github.com/squidfunk/mkdocs-material/releases/tag/7.2.0
[14]: https://github.com/squidfunk/mkdocs-material/blob/master/src/assets/javascripts/components/search/share/index.ts
[15]: ../assets/screenshots/search-share.png
@ -245,9 +248,9 @@ For setup instructions, refer to the [official documentation][19].
### Search boosting
[:octicons-file-code-24: Source][20] ·
[:octicons-heart-fill-24:{ .mdx-heart } Insiders][Insiders]{ .mdx-insiders } ·
:octicons-note-24: Metadata ·
[:octicons-heart-fill-24:{ .mdx-heart } Insiders only][20]{ .mdx-insiders }
[:octicons-tag-24: insiders-2.8.0][Insiders]
In order to give specific pages a higher relevance in search, [lunr][4] supports
page-specific boosts, which can be defined for each page by leveraging the
@ -263,14 +266,16 @@ search:
...
```
[Insiders]: ../insiders/index.md
[20]: ../insiders/index.md
[21]: ../reference/meta-tags.md#metadata
### Search exclusion
[:octicons-file-code-24: Source][20] ·
[:octicons-heart-fill-24:{ .mdx-heart } Insiders][Insiders]{ .mdx-insiders } ·
:octicons-note-24: Metadata ·
:octicons-beaker-24: Experimental ·
[:octicons-heart-fill-24:{ .mdx-heart } Insiders only][20]{ .mdx-insiders }
[:octicons-tag-24: insiders-3.1.0][Insiders]
#### Excluding pages
@ -434,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

148
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][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,71 @@ 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-file-code-24: Source][4] ·
[:octicons-cpu-24: Plugin][4] ·
:octicons-beaker-24: Experimental ·
[:octicons-heart-fill-24:{ .mdx-heart } Insiders only][4]{ .mdx-insiders }
[: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
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.
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:
- 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="1">
<figure markdown>
[![Social Cards][6]][6]
[![Social cards preview]][Social cards preview]
<figcaption markdown="1">
<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: _automatically set based on [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 }
`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:
@ -85,24 +87,26 @@ are available:
cards_directory: assets/images/social
```
[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
[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
#### Caching <small>recommended</small> { #caching 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
@ -127,18 +131,64 @@ 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]: #built-in-social-cards
[publishing guide]: ../publishing-your-site.md#with-github-actions
#### Meta tags
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"
``` html
{% block extrahead %}
{% set title = config.site_name %}
{% 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 %}
{% endif %}
<meta property="og:type" content="website" />
<meta property="og:title" content="{{ title }}" />
<meta property="og:description" content="{{ config.site_description }}" />
<meta property="og:url" content="{{ page.canonical_url }}" />
<meta property="og:image" content="<url>" />
<meta property="og:image:type" content="image/png" />
<meta property="og:image:width" content="1200" />
<meta property="og:image:height" content="630" />
{% endblock %}
```
=== ":fontawesome-brands-twitter: Twitter Cards"
``` html
{% block extrahead %}
{% set title = config.site_name %}
{% 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 %}
{% endif %}
<meta name="twitter:card" content="summary_large_image" />
<meta name="twitter:title" content="{{ title }}" />
<meta name="twitter:description" content="{{ config.site_description }}" />
<meta name="twitter:image" content="<url>" />
{% endblock %}
```
[Twitter Cards]: https://developer.twitter.com/en/docs/tweets/optimize-with-cards/overview/abouts-cards
## Usage
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
you can use the [Metadata] extension, which takes precedence over the
default values.
- [Changing the title][12]
- [Changing the description][13]
- [Changing the title]
- [Changing the description]
[11]: ../reference/meta-tags.md#metadata
[12]: ../reference/meta-tags.md#setting-the-page-title
[13]: ../reference/meta-tags.md#setting-the-page-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

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

@ -13,12 +13,12 @@ can help to discover relevant information faster.
### Built-in tags
[:octicons-file-code-24: Source][1] ·
[:octicons-cpu-24: Plugin][1] ·
:octicons-beaker-24: Experimental ·
[:octicons-heart-fill-24:{ .mdx-heart } Insiders only][1]{ .mdx-insiders }
[: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
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 }
`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,31 +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.
[1]: ../insiders/index.md
[2]: https://github.com/jldiaz/mkdocs-plugin-tags
[3]: #adding-a-tags-index
[Insiders]: ../insiders/index.md
[adding a tags index]: #adding-a-tags-index
## Usage
### Adding tags
[:octicons-file-code-24: Source][1] ·
:octicons-note-24: Metadata
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:
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:
``` yaml
``` bash
---
tags:
- insiders
@ -89,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]: #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
@ -120,17 +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
[:octicons-file-code-24: Source][1] ·
:octicons-note-24: Metadata
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
---
@ -141,5 +123,3 @@ hide:
# Document title
...
```
[10]: ../../reference/meta-tags/#metadata

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

@ -15,10 +15,10 @@ configured via `mkdocs.yml`.
### Social links
[:octicons-file-code-24: Source][1] ·
[:octicons-tag-24: 1.0.0][Social links support] ·
:octicons-milestone-24: Default: _none_
All _social links_ are rendered next to the copyright information as part of the
Social links are rendered next to the copyright notice as part of the
footer of your project documentation. Add a list of social links in `mkdocs.yml`
with:
@ -29,13 +29,14 @@ extra:
link: https://twitter.com/squidfunk
```
For each entry, the following fields are available:
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
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`
@ -48,16 +49,16 @@ For each entry, the following fields are available:
* :fontawesome-brands-slack: – `fontawesome/brands/slack`
* :fontawesome-brands-twitter: – `fontawesome/brands/twitter`
[1]: https://github.com/squidfunk/mkdocs-material/blob/master/src/partials/social.html
[2]: https://github.com/squidfunk/mkdocs-material/tree/master/material/.icons
[Social links support]: https://github.com/squidfunk/mkdocs-material/releases/tag/1.0.0
[custom icons]: 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
scheme. All URI schemes are supported, including `mailto` and `bitcoin`:
=== "Twitter"
=== ":fontawesome-brands-twitter: Twitter"
``` yaml
extra:
@ -66,7 +67,7 @@ For each entry, the following fields are available:
link: https://twitter.com/squidfunk
```
=== "Email address"
=== ":octicons-mail-16: Email"
``` yaml
extra:
@ -75,7 +76,7 @@ For each entry, the following fields 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
@ -91,21 +92,23 @@ For each entry, the following fields are available:
### Copyright notice
[:octicons-file-code-24: Source][3] ·
[: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
A custom copyright banner can be rendered as part of the footer, which is
displayed next to the social links. It can be defined as part of `mkdocs.yml`:
``` yaml
copyright: Copyright &copy; 2016 - 2020 Martin Donath
```
[Copyright notice support]: https://github.com/squidfunk/mkdocs-material/releases/tag/0.1.0
[3]: https://github.com/squidfunk/mkdocs-material/blob/master/src/partials/footer.html
### Remove generator
### Generator notice
[:octicons-file-code-24: Source][3]
[: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
@ -121,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.
[4]: ../insiders/index.md
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

30
docs/setup/setting-up-the-header.md
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-file-code-24: Source][3] ·
[: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`:
@ -29,25 +29,27 @@ theme:
- header.autohide
```
[3]: https://github.com/squidfunk/mkdocs-material/blob/master/src/assets/stylesheets/main/layout/_header.scss
## Customization
[Automatic hiding support]: https://github.com/squidfunk/mkdocs-material/releases/tag/6.2.0
### Announcement bar
[: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 %}
```
[4]: ../customization.md#extending-the-theme
[5]: ../customization.md#overriding-blocks-recommended
[Announcement bar support]: https://github.com/squidfunk/mkdocs-material/releases/tag/6.2.0
[extend the theme]: ../customization.md#extending-the-theme
[overriding blocks]: ../customization.md#overriding-blocks

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

@ -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="1">
<figure markdown>
[![Version selection][3]][3]
[![Version selector preview]][Version selector preview]
<figcaption markdown="1">
<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,24 +55,20 @@ 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
[:octicons-file-code-24: Source][7] ·
[:octicons-heart-fill-24:{ .mdx-heart } Insiders only][7]{ .mdx-insiders }
[:octicons-heart-fill-24:{ .mdx-heart } Insiders][Insiders]{ .mdx-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" %}
@ -94,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:
@ -106,18 +101,18 @@ extra:
default: stable
```
Make sure that this matches the [default version][11].
Make sure that this matches the [default version].
[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
[Insiders]: ../insiders/index.md
[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
[:octicons-file-code-24: Source][7] ·
[:octicons-heart-fill-24:{ .mdx-heart } Insiders only][7]{ .mdx-insiders }
[:octicons-heart-fill-24:{ .mdx-heart } Insiders][Insiders]{ .mdx-insiders } ·
[:octicons-tag-24: insiders-2.6.0][Insiders]
Insiders improves the user experience when switching between versions: if
version A and B contain a page with the same path name, the user will stay on
@ -139,21 +134,11 @@ the current page:
docs.example.com/0.1/bar/ -> docs.example.com/0.2/
```
<figure markdown="1">
<figcaption markdown="1">
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
@ -173,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_

117
docs/troubleshooting.md
View File

@ -1,117 +0,0 @@
---
template: overrides/main.html
---
# Troubleshooting
## Theme not recognized
Operating systems:
:fontawesome-brands-apple:
:fontawesome-brands-windows:
:fontawesome-brands-linux:
!!! error "Error: Unrecognized theme"
``` sh
mkdocs serve
# => INFO - Building documentation...
# => ERROR - Config value: 'theme'. Error: Unrecognised theme 'material'.
# => ...
# => ConfigurationError: Aborted with 1 Configuration Errors!
```
If you run into this error, the most common reason is that you installed MkDocs
through some package manager (e.g. `brew` or `apt-get`) and Material for MkDocs
through `pip`, so both packages end up in different locations. MkDocs only
checks its install location for themes.
## Inadequate permissions
Operating systems: :fontawesome-brands-apple:
!!! error "Error: Permission denied"
``` sh
pip install mkdocs-material
# => Could not install packages due to an EnvironmentError: [Errno 13] Permission denied: '...'
# => Consider using the --user option or check the permissions.
```
When you're running the pre-installed version of Python on macOS, `pip` tries
to install packages in a folder for which your user might not have the adequate
permissions. There are three possible solutions for this, the recommended one
of which is to use virtual environments:
=== "Virtual environments"
If you're installing Material for MkDocs with `pip`, the easiest way to make
sure that you end up with the correct versions and without any
incompatibility problems between packages it to use a [virtual
environment][1]. First, ensure that you have a Python version of 3 or
higher installed:
```
python --version
```
If you're good to go, create and activate a virtual environment with:
```
python -m venv venv
source ./venv/bin/activate
```
Note that the second `venv` is the name of the folder where to create the
virtual environment – you may choose it as you like. Your terminal should
now print `(venv)` before the prompt and the `python` executable should be
located inside the folder you just created.
Next, [install Material for MkDocs][2] with `pip`, which will download and
install all packages in the `venv` folder you just created, including MkDocs
and its dependencies:
```
pip install mkdocs-material
```
Verify that MkDocs and Material for MkDocs were both installed correctly:
```
mkdocs --version
mkdocs serve --help
```
MkDocs should list `material` as an option under the `--theme` flag. When
you're finished working with MkDocs, you can exit the virtual environment
with:
```
deactivate
```
=== "User space"
Provide the `--user` flag to the install command and `pip` will install the
package in a user-site location. While this is not a global installation,
it's still not isolated and may lead to problems when you use different
versions of Material for MkDocs in other projects:
```
pip install --user mkdocs-material
```
=== "Upgrade Python"
Upgrade your Python installation by installing Python with [Homebrew][3].
This should eliminate a lot of problems you will run into with `pip`. Yet,
it's still not an isolated installation which may also lead to the same
problems as installing in user space:
```
brew upgrade python
```
[1]: https://docs.python.org/3/tutorial/venv.html
[2]: getting-started.md#with-pip-recommended
[3]: https://brew.sh/

4
docs/upgrading.md → docs/upgrade.md
View File

@ -2,7 +2,7 @@
template: overrides/main.html
---
# Upgrading
# How to upgrade
Upgrade to the latest version with:
@ -10,7 +10,7 @@ Upgrade to the latest version with:
pip install --upgrade mkdocs-material
```
Inspect the currently installed version with:
Show the currently installed version with:
```
pip show mkdocs-material

2
material/assets/stylesheets/main.24c991ad.min.css vendored
View File

File diff suppressed because one or more lines are too long

1
material/assets/stylesheets/main.24c991ad.min.css.map
View File

File diff suppressed because one or more lines are too long

2
material/assets/stylesheets/main.2ec5b002.min.css vendored Normal file
View File

File diff suppressed because one or more lines are too long

1
material/assets/stylesheets/main.2ec5b002.min.css.map Normal file
View File

File diff suppressed because one or more lines are too long

2
material/base.html
View File

@ -39,7 +39,7 @@
{% endif %}
{% endblock %}
{% block styles %}
<link rel="stylesheet" href="{{ 'assets/stylesheets/main.24c991ad.min.css' | url }}">
<link rel="stylesheet" href="{{ 'assets/stylesheets/main.2ec5b002.min.css' | url }}">
{% if config.theme.palette %}
{% set palette = config.theme.palette %}
<link rel="stylesheet" href="{{ 'assets/stylesheets/palette.3f5d1f46.min.css' | url }}">

2
material/overrides/assets/stylesheets/main.5136944a.min.css vendored Normal file
View File

File diff suppressed because one or more lines are too long

1
material/overrides/assets/stylesheets/main.5136944a.min.css.map Normal file
View File

File diff suppressed because one or more lines are too long

2
material/overrides/assets/stylesheets/main.9307850e.min.css vendored
View File

File diff suppressed because one or more lines are too long

1
material/overrides/assets/stylesheets/main.9307850e.min.css.map
View File

File diff suppressed because one or more lines are too long

2
material/overrides/main.html
View File

@ -3,7 +3,7 @@
-#}
{% extends "base.html" %}
{% block extrahead %}
<link rel="stylesheet" href="{{ 'overrides/assets/stylesheets/main.9307850e.min.css' | url }}">
<link rel="stylesheet" href="{{ 'overrides/assets/stylesheets/main.5136944a.min.css' | url }}">
{% endblock %}
{% block announce %}
<a href="https://twitter.com/squidfunk">

29
mkdocs.yml
View File

@ -51,7 +51,7 @@ theme:
language: en
features:
- content.code.annotate
- content.tabs.link
# - content.tabs.link
# - header.autohide
# - navigation.expand
- navigation.indexes
@ -91,18 +91,7 @@ plugins:
- redirects:
redirect_maps:
changelog/insiders.md: insiders/changelog.md
extensions/admonition.md: reference/admonitions.md
extensions/codehilite.md: reference/code-blocks.md
extensions/footnotes.md: reference/footnotes.md
extensions/metadata.md: reference/meta-tags.md
extensions/permalinks.md: setup/setting-up-navigation.md #permalink
extensions/pymdown.md: reference/admonitions.md
plugins/revision-date.md: setup/adding-a-git-repository.md #revision-date
plugins/search.md: setup/setting-up-site-search.md
releases/4.md: upgrading.md #upgrading-from-4x-to-5x
releases/5.md: upgrading.md #upgrading-from-3x-to-4x
releases/changelog.md: changelog.md
setup/adding-social-links.md: setup/setting-up-the-footer.md
upgrading.md: upgrade.md
sponsorship.md: insiders/index.md
- minify:
minify_html: true
@ -174,13 +163,10 @@ nav:
- Creating your site: creating-your-site.md
- Publishing your site: publishing-your-site.md
- Customization: customization.md
- Troubleshooting: troubleshooting.md
- Data privacy: data-privacy.md
- License: license.md
- Releases:
- Changelog: changelog.md
- Upgrade guide: upgrading.md
- Deprecations: deprecations.md
- Changelog:
- changelog/index.md
- How to upgrade: upgrade.md
- Setup:
- Changing the colors: setup/changing-the-colors.md
- Changing the fonts: setup/changing-the-fonts.md
@ -196,6 +182,10 @@ nav:
- Setting up the footer: setup/setting-up-the-footer.md
- Adding a git repository: setup/adding-a-git-repository.md
- Adding a comment system: setup/adding-a-comment-system.md
- Extensions:
- setup/extensions/index.md
- Python Markdown: setup/extensions/python-markdown.md
- Python Markdown Extensions: setup/extensions/python-markdown-extensions.md
- Reference:
- Abbreviations: reference/abbreviations.md
- Admonitions: reference/admonitions.md
@ -211,7 +201,6 @@ nav:
- Lists: reference/lists.md
- MathJax: reference/mathjax.md
- Meta tags: reference/meta-tags.md
- Variables: reference/variables.md
- Insiders:
- insiders/index.md
- Getting started:

6
src/assets/stylesheets/main/extensions/markdown/_admonition.scss
View File

@ -150,12 +150,6 @@ $admonitions: (
left: initial;
}
}
// Adjust spacing on last tabbed block container child - if the tabbed
// block container is the sole child, it looks better to omit the margin
+ .tabbed-set:last-child {
margin-top: 0;
}
}
}

2
src/assets/stylesheets/main/layout/_content.scss
View File

@ -50,7 +50,6 @@
// Adjust for right-to-left languages
[dir="rtl"] & {
margin-right: px2rem(24px);
margin-left: px2rem(16px);
}
}
@ -60,7 +59,6 @@
// Adjust for right-to-left languages
[dir="rtl"] & {
margin-right: px2rem(16px);
margin-left: px2rem(24px);
}
}

4
src/base.html
View File

@ -78,7 +78,7 @@
{% endif %}
{% endblock %}
<!-- Theme-related stylesheets -->
<!-- Theme-related style sheets -->
{% block styles %}
<link rel="stylesheet" href="{{ 'assets/stylesheets/main.css' | url }}" />
@ -136,7 +136,7 @@
/>
{% endif %}
<!-- Custom stylesheets -->
<!-- Custom style sheets -->
{% for path in config["extra_css"] %}
<link rel="stylesheet" href="{{ path | url }}" />
{% endfor %}

12
src/overrides/assets/stylesheets/main/_typeset.scss
View File

@ -104,6 +104,18 @@
}
}
// Deprecation
.mdx-deprecated {
opacity: 0.5;
transition: opacity 250ms;
// Deprecation on focus/hover
&:focus-within,
&:hover {
opacity: 1;
}
}
// Two-column layout
.mdx-columns {

2
src/overrides/main.html
View File

@ -25,7 +25,7 @@
<!-- Custom front matter -->
{% block extrahead %}
<!-- Extra stylesheets (can't be set in mkdocs.yml due to content hash) -->
<!-- Extra style sheets (can't be set in mkdocs.yml due to content hash) -->
<link
rel="stylesheet"
href="{{ 'overrides/assets/stylesheets/main.css' | url }}"