OpenSourceArk/mkdocs-material
1
0
Fork 0
mirror of https://github.com/squidfunk/mkdocs-material.git synced 2024-06-14 11:52:32 +03:00
Code Issues Packages Projects Releases Wiki Activity

Updated documentation

Browse Source
This commit is contained in:
squidfunk 2022-09-11 19:25:40 +02:00
parent 871f6939aa
commit 1cf9d45c28
66 changed files with 2407 additions and 735 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

4
docs/blog/.authors.yml Normal file
View File

@ -0,0 +1,4 @@
squidfunk:
name: Martin Donath
description: Creator
avatar: https://avatars.githubusercontent.com/u/932156

3
docs/blog/.meta.yml Normal file
View File

@ -0,0 +1,3 @@
comments: true
hide:
- feedback

146
docs/blog/index.md
View File

@ -1,146 +1,4 @@
---
template: overrides/main.html
title: Blog
search:
exclude: true
---
<style>
.md-sidebar--secondary:not([hidden]) {
visibility: hidden;
}
</style>
# Blog # Blog
## [Chinese search support – 中文搜索​支持] This is our blog where we write about new features, performance improvements
and the project in general.
__Insiders adds experimental Chinese language support for the [built-in search
plugin] – a feature that has been requested for a long time given the large
number of Chinese users.__
<aside class="mdx-author" markdown>
![@squidfunk][@squidfunk avatar]
<span>__Martin Donath__ · @squidfunk</span>
<span>
:octicons-calendar-24: May 5, 2022 ·
:octicons-clock-24: 5 min read ·
[:octicons-tag-24: 8.2.13+insiders-4.14.0][insiders-4.14.0]
</span>
</aside>
---
After the United States and Germany, the third-largest country of origin of
Material for MkDocs users is China. For a long time, the [built-in search plugin]
didn't allow for proper segmentation of Chinese characters, mainly due to
missing support in [`lunr-languages`][lunr-languages] which is used for search
tokenization and stemming. The latest Insiders release adds long-awaited Chinese
language support for the built-in search plugin, something that has been
requested by many users.
[:octicons-arrow-right-24: Continue reading][Chinese search support – 中文搜索​支持]
[built-in search plugin]: ../setup/setting-up-site-search.md#built-in-search-plugin
[@squidfunk avatar]: https://avatars.githubusercontent.com/u/932156
[insiders-4.14.0]: ../insiders/changelog.md#4.14.0
[lunr-languages]: https://github.com/MihaiValentin/lunr-languages
[Chinese search support – 中文搜索​支持]: 2022/chinese-search-support.md
## [The past, present and future]
__2021 was a fantastic year for this project as we shipped many new awesome
features, saw significant user growth and leveraged GitHub Sponsors to make the
project sustainable.__
<aside class="mdx-author" markdown>
![@squidfunk][@squidfunk avatar]
<span>__Martin Donath__ · @squidfunk</span>
<span>
:octicons-calendar-24: December 27, 2021 ·
:octicons-clock-24: 10 min read
</span>
</aside>
---
Today, together, MkDocs and Material for MkDocs are among the most popular
options when it comes to choosing a static site generator and theme for your
technical documentation project. Material for MkDocs ensures that your
content is always perfectly presented to your audience, regardless of screen
resolution or device capabilities. It has evolved to a framework for technical
writing, offering many features, some of which are yet to be found in other
static site generators. However, we're far from the end, as 2022 is going to
bring some interesting new capabilities.
[:octicons-arrow-right-24: Continue reading][The past, present and future]
[The past, present and future]: 2021/the-past-present-and-future.md
## [Excluding content from search]
__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>
![@squidfunk][@squidfunk avatar]
<span>__Martin Donath__ · @squidfunk</span>
<span>
:octicons-calendar-24: September 26, 2021 ·
:octicons-clock-24: 5 min read ·
[:octicons-tag-24: 7.3.0+insiders-3.1.1][insiders-3.1.1]
</span>
</aside>
---
Two weeks ago, Material for MkDocs Insiders shipped a brand new search plugin,
yielding massive improvements in usability, but also in speed and size of the
search index. Interestingly, as discussed in the previous blog article, we only
scratched the surface of what's now possible. This release brings some useful
features that enhance the writing experience, allowing for more fine-grained
control of what pages, sections and blocks of a Markdown file should be indexed
by the built-in search functionality.
[:octicons-arrow-right-24: Continue reading][Excluding content from search]
[Excluding content from search]: 2021/excluding-content-from-search.md
[insiders-3.1.1]: ../insiders/changelog.md#3.1.1
## [Search: better, faster, smaller]
__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>
![@squidfunk][@squidfunk avatar]
<span>__Martin Donath__ · @squidfunk</span>
<span>
:octicons-calendar-24: September 13, 2021 ·
:octicons-clock-24: 15 min read ·
[:octicons-tag-24: 7.2.6+insiders-3.0.0][insiders-3.0.0]
</span>
</aside>
---
The search of Material for MkDocs is by far one of its best and most-loved
assets: multilingual, offline-capable, and most importantly: _all client-side_.
It provides a solution to empower the users of your documentation to find what
they're searching for instantly without the headache of managing additional
servers. However, even though several iterations have been made, there's still
some room for improvement, which is why we rebuilt the search plugin and
integration from the ground up. This article shines some light on the internals
of the new search, why it's much more powerful than the previous version, and
what's about to come.
[:octicons-arrow-right-24: Continue reading][Search: better, faster, smaller]
[Search: better, faster, smaller]: 2021/search-better-faster-smaller.md
[insiders-3.0.0]: ../insiders/changelog.md#3.0.0

246
docs/blog/posts/blog-support-just-landed.md Normal file
View File

@ -0,0 +1,246 @@
---
date: 2022-09-12
authors: [squidfunk]
description: >
Our new blog is built with the brand new built-in blog plugin. You can build
a blog alongside your documentation or standalone
categories:
- Blog
links:
- Getting started with Insiders: insiders/getting-started.md#requirements
- setup/setting-up-a-blog.md#built-in-blog-plugin
---
# Blog support just landed
__Hey there! You're looking at our new blog, built with the brand new
[built-in blog plugin]. With this plugin, you can easily build a blog alongside
your documentation or standalone.__
Proper support for blogging, as requested by many users over the past few years,
was something that was desperately missing from Material for MkDocs' feature set.
While everybody agreed that blogging support was a blind spot, it was not
obvious whether MkDocs could be extended in a way to allow for blogging as we
know it from [Jekyll] and friends. The [built-in blog plugin] proves that it is,
after all, possible to build a blogging engine on top of MkDocs, in order to
create a technical blog alongside your documentation, or as the main thing.
<!-- more -->
_This article explains how to build a standalone blog with Material for MkDocs.
If you want to build a blog alongside your documentation, please refer to
[the plugin's documentation][built-in blog plugin]._
[built-in blog plugin]: ../../setup/setting-up-a-blog.md#built-in-blog-plugin
[Jekyll]: https://jekyllrb.com/
## Quick start
### Setting up Insiders
Before we can start bootstrapping a blog and [write our first post], we need to
set up [Insiders], since the [built-in blog plugin] is currently reserved to
sponsors. Without the funds this project receives through sponsorships, this
plugin wouldn't exist. Three steps are necessary:
1. [Subscribe to a monthly sponsorship]
2. [Create a personal access token]
3. [Install Insiders]
[write our first post]: #writing-your-first-post
[Insiders]: ../../insiders/index.md
[Subscribe to a monthly sponsorship]: ../../insiders/index.md#how-to-become-a-sponsor
[Create a personal access token]: ../../insiders/getting-started.md#requirements
[Install Insiders]: ../../insiders/getting-started.md#installation
### Creating a standalone blog
After Insiders is installed, you can bootstrap a new project using the `mkdocs`
executable:
```
mkdocs new .
```
This will create the following structure:
```
.
├─ docs/
│ └─ index.md
└─ mkdocs.yml
```
#### Configuration
In this article, we're going to build a standalone blog, which means that the
blog lives at the root of your project. For this reason, open `mkdocs.yml`,
and replace its contents with:
``` yaml
site_name: My Blog
theme:
name: material
features:
- navigation.sections
plugins:
- blog:
blog_dir: . # (1)!
- search
- tags
nav:
- index.md
```
1. This is the important part – we're hosting the blog at the root of the
project, and not in a subdirectory. For more information, see the
[`blog_dir`][blog_dir] configuration option.
[blog_dir]: ../../setup/setting-up-a-blog.md#+blog.blog_dir
#### Blog setup
The blog index page lives in `docs/index.md`. This page was pre-filled by
MkDocs with some content, so we're going to replace it with what we need to
bootstrap the blog:
``` markdown
# Blog
```
That's it.
### Writing your first post
Now that we have set up the [built-in blog plugin], we can start writing our
first post. All blog posts are written with the [exact same Markdown flavor] as
already included with Material for MkDocs. First, create a folder called `posts`
with a file called `hello-world.md`:
``` sh
.
├─ docs/
│ ├─ posts/
│ │ └─ hello-world.md # (1)!
│ └─ index.md
└─ mkdocs.yml
```
1. If you'd like to arrange posts differently, you're free to do so. The URLs
are built from the format specified in [`post_url_format`][post slugs] and
the titles and dates of posts, no matter how they are organized
inside the `posts` directory.
Then, open up `hello-world.md`, and add the following lines:
``` yaml
---
draft: true # (1)!
date: 2022-01-31
categories:
- Hello
- World
---
# Hello world!
Lorem ipsum dolor sit amet, consectetur adipiscing elit. Pellentesque nec
maximus ex. Sed consequat, nulla quis malesuada dapibus, elit metus vehicula
erat, ut egestas tellus eros at risus. In hac habitasse platea dictumst.
Phasellus id lacus pulvinar erat consequat pretium. Morbi malesuada arcu mauris
Nam vel justo sem. Nam placerat purus non varius luctus. Integer pretium leo in
sem rhoncus, quis gravida orci mollis. Proin id aliquam est. Vivamus in nunc ac
metus tristique pellentesque. Suspendisse viverra urna in accumsan aliquet.
<!-- more -->
Donec volutpat, elit ac volutpat laoreet, turpis dolor semper nibh, et dictum
massa ex pulvinar elit. Curabitur commodo sit amet dolor sed mattis. Etiam
tempor odio eu nisi gravida cursus. Maecenas ante enim, fermentum sit amet
molestie nec, mollis ac libero. Vivamus sagittis suscipit eros ut luctus.
Nunc vehicula sagittis condimentum. Cras facilisis bibendum lorem et feugiat.
In auctor accumsan ligula, at consectetur erat commodo quis. Morbi ac nunc
pharetra, pellentesque risus in, consectetur urna. Nulla id enim facilisis
arcu tincidunt pulvinar. Vestibulum laoreet risus scelerisque porta congue.
In velit purus, dictum quis neque nec, molestie viverra risus. Nam pellentesque
tellus id elit ultricies, vel finibus erat cursus.
```
1. If you mark a post as a [draft], a red marker appears next to the post date
on index pages. When the site is built, drafts are not included in the
output. [This behavior can be changed], e.g. for rendering drafts when
building deploy previews.
When you spin up the [live preview server], you should be greeted by your first
post! You'll also realize, that [archive] and [category] indexes have been
automatically generated for you:
![Blog]
However, this is just the start. The [built-in blog plugin] packs a lot of
functionality needed in day-to-day blogging. Visit the documentation of the
plugin to learn about the following topics:
<div class="mdx-columns" markdown>
- [Adding an excerpt]
- [Adding authors]
- [Adding categories]
- [Adding tags]
- [Adding related links]
- [Linking from and to posts]
- [Setting the reading time]
- [Setting defaults]
</div>
Additionally, the [built-in blog plugin] has dozens of [configuration options]
which allow for fine-tuning the output. You can configure post slugs, general
behavior and much more.
[exact same Markdown flavor]: ../../reference/index.md
[post slugs]: ../../setup/setting-up-a-blog.md#+blog.post_url_format
[draft]: ../../setup/setting-up-a-blog.md#drafts
[This behavior can be changed]: ../../setup/setting-up-a-blog.md#+blog.draft
[live preview server]: ../../creating-your-site.md#previewing-as-you-write
[archive]: ../../setup/setting-up-a-blog.md#archive
[category]: ../../setup/setting-up-a-blog.md#categories
[Blog]: blog-support-just-landed/blog.png
[Blog post]: blog-support-just-landed/blog-post.png
[Adding an excerpt]: ../../setup/setting-up-a-blog.md#adding-an-excerpt
[Adding authors]: ../../setup/setting-up-a-blog.md#adding-authors
[Adding categories]: ../../setup/setting-up-a-blog.md#adding-categories
[Adding tags]: ../../setup/setting-up-a-blog.md#adding-tags
[Adding related links]: ../../setup/setting-up-a-blog.md#adding-related-links
[Linking from and to posts]: ../../setup/setting-up-a-blog.md#linking-from-and-to-posts
[Setting the reading time]: ../../setup/setting-up-a-blog.md#setting-the-reading-time
[Setting defaults]: ../../setup/setting-up-a-blog.md#setting-defaults
[configuration options]: ../../setup/setting-up-a-blog.md#configuration
## What's next?
Getting basic blogging support out the door was quite a challenge – the
[built-in blog plugin] is probably the biggest release this year and already
packs a lot of functionality. However, Material for MkDocs is used in many
different contexts, which is why we'd expect to iterate, as always.
Some ideas already proposed by users:
- __Blog series__: Authors should be able to create so called blog series and
assign posts to a blog series using simple identifiers. For each post that is
part of a series, a list with links to all other posts should be included in
the post's content.
- __Author indexes__: Besides [archive] and [category] indexes, authors should
be able to create per-author indexes, which list all posts linked to an
author. Additionally, a profile should be created for each author and linked
from posts.
- __Social share buttons__: It should be easy to share blog posts via social
media or other ways. For this reason, it should be possible to automatically
include social sharing buttons with each post.
What's still missing from the brand new [built-in blog plugin]? Feel free to
share your ideas in the comments. Together, we can build one of the best modern
engines for technical blogging!

BIN
docs/blog/posts/blog-support-just-landed/blog.png Normal file
View File

Binary file not shown.
Side by Side

After

Width:  |  Height:  |  Size: 325 KiB

31
docs/blog/2022/chinese-search-support.md → docs/blog/posts/chinese-search-support.md
View File

@ -1,11 +1,16 @@
--- ---
template: overrides/blog.html date: 2022-05-05
authors: [squidfunk]
title: Chinese search support title: Chinese search support
description: > description: >
Insiders adds Chinese language support for the built-in search plugin – a Insiders adds Chinese language support for the built-in search plugin – a
feature that has been requested many times feature that has been requested many times
hide: categories:
- feedback - Search
links:
- blog/posts/search-better-faster-smaller.md
- setup/setting-up-site-search.md#chinese-language-support
- insiders/index.md#how-to-become-a-sponsor
--- ---
# Chinese search support – 中文搜索​支持 # Chinese search support – 中文搜索​支持
@ -14,23 +19,6 @@ __Insiders adds experimental Chinese language support for the [built-in search
plugin] – a feature that has been requested for a long time given the large plugin] – a feature that has been requested for a long time given the large
number of Chinese users.__ number of Chinese users.__
<aside class="mdx-author" markdown>
![@squidfunk][@squidfunk avatar]
<span>__Martin Donath__ · @squidfunk</span>
<span>
:octicons-calendar-24: May 5, 2022 ·
:octicons-clock-24: 3 min read ·
[:octicons-tag-24: 8.2.13+insiders-4.14.0][insiders-4.14.0]
</span>
</aside>
[built-in search plugin]: ../../setup/setting-up-site-search.md#built-in-search-plugin
[@squidfunk avatar]: https://avatars.githubusercontent.com/u/932156
[insiders-4.14.0]: ../../insiders/changelog.md#4.14.0
---
After the United States and Germany, the third-largest country of origin of After the United States and Germany, the third-largest country of origin of
Material for MkDocs users is China. For a long time, the [built-in search plugin] Material for MkDocs users is China. For a long time, the [built-in search plugin]
didn't allow for proper segmentation of Chinese characters, mainly due to didn't allow for proper segmentation of Chinese characters, mainly due to
@ -38,6 +26,8 @@ missing support in [lunr-languages] which is used for search tokenization and
stemming. The latest Insiders release adds long-awaited Chinese language support stemming. The latest Insiders release adds long-awaited Chinese language support
for the built-in search plugin, something that has been requested by many users. for the built-in search plugin, something that has been requested by many users.
<!-- more -->
_Material for MkDocs終於​支持​中文​了！文本​被​正確​分割​並且​更​容易​找到。_ _Material for MkDocs終於​支持​中文​了！文本​被​正確​分割​並且​更​容易​找到。_
{ style="display: inline" } { style="display: inline" }
@ -45,6 +35,7 @@ _This article explains how to set up Chinese language support for the built-in
search plugin in a few minutes._ search plugin in a few minutes._
{ style="display: inline" } { style="display: inline" }
[built-in search plugin]: ../../setup/setting-up-site-search.md#built-in-search-plugin
[lunr-languages]: https://github.com/MihaiValentin/lunr-languages [lunr-languages]: https://github.com/MihaiValentin/lunr-languages
## Configuration ## Configuration

43
docs/blog/2021/excluding-content-from-search.md → docs/blog/posts/excluding-content-from-search.md
View File

@ -1,12 +1,15 @@
--- ---
template: overrides/blog.html date: 2021-09-26
authors: [squidfunk]
description: > description: >
Three new simple ways to exclude dedicated parts of a document from the search Three new simple ways to exclude dedicated parts of a document from the search
index, allowing for more fine-grained control index, allowing for more fine-grained control
search: categories:
exclude: true - Search
hide: links:
- feedback - blog/posts/search-better-faster-smaller.md
- setup/setting-up-site-search.md#search-exclusion
- insiders/index.md#how-to-become-a-sponsor
--- ---
# Excluding content from search # Excluding content from search
@ -15,22 +18,6 @@ __The latest Insiders release brings three new simple ways to exclude
dedicated parts of a document from the search index, allowing for more dedicated parts of a document from the search index, allowing for more
fine-grained control.__ fine-grained control.__
<aside class="mdx-author" markdown>
![@squidfunk][@squidfunk avatar]
<span>__Martin Donath__ · @squidfunk</span>
<span>
:octicons-calendar-24: September 26, 2021 ·
:octicons-clock-24: 5 min read ·
[:octicons-tag-24: 7.3.0+insiders-3.1.1][insiders-3.1.1]
</span>
</aside>
[@squidfunk avatar]: https://avatars.githubusercontent.com/u/932156
[insiders-3.1.1]: ../../insiders/changelog.md#3.1.1
---
Two weeks ago, Material for MkDocs Insiders shipped a [brand new search Two weeks ago, Material for MkDocs Insiders shipped a [brand new search
plugin], yielding [massive improvements in usability], but also in [speed plugin], yielding [massive improvements in usability], but also in [speed
and size] of the search index. Interestingly, as discussed in the previous and size] of the search index. Interestingly, as discussed in the previous
@ -39,6 +26,8 @@ release brings some useful features that enhance the writing experience,
allowing for more fine-grained control of what pages, sections and blocks of a allowing for more fine-grained control of what pages, sections and blocks of a
Markdown file should be indexed by the built-in search functionality. Markdown file should be indexed by the built-in search functionality.
<!-- more -->
_The following section discusses existing solutions for excluding pages and _The following section discusses existing solutions for excluding pages and
sections from the search index. If you immediately want to learn what's new, sections from the search index. If you immediately want to learn what's new,
skip to the [section just after that][what's new]._ skip to the [section just after that][what's new]._
@ -124,7 +113,7 @@ directive to the front matter of the respective Markdown file. The good thing
is that the author now only has to check the top of the document to learn is that the author now only has to check the top of the document to learn
whether it is excluded or not: whether it is excluded or not:
``` sh ``` yaml
--- ---
search: search:
exclude: true exclude: true
@ -137,11 +126,11 @@ search:
### Excluding sections ### Excluding sections
If a section should be excluded, the author can use the [Attribute Lists] If a section should be excluded, the author can use the [Attribute Lists]
extension to add a __pragma__ called `{ data-search-exclude }` at the end of a extension to add a __pragma__ called `data-search-exclude` at the end of a
heading. The pragma is not included in the final HTML, as search pragmas are heading. The pragma is not included in the final HTML, as search pragmas are
filtered by the search plugin before the page is rendered: filtered by the search plugin before the page is rendered:
=== ":octicons-file-code-16: docs/page.md" === ":octicons-file-code-16: `docs/page.md`"
``` markdown ``` markdown
# Document title # Document title
@ -155,7 +144,7 @@ filtered by the search plugin before the page is rendered:
The content of this section is excluded The content of this section is excluded
``` ```
=== ":octicons-codescan-16: search_index.json" === ":octicons-codescan-16: `search_index.json`"
``` json ``` json
{ {
@ -181,7 +170,7 @@ If even more fine-grained control is desired, the __pragma__ can be added to
any [block-level element] or [inline-level element] that is officially any [block-level element] or [inline-level element] that is officially
supported by the [Attribute Lists] extension: supported by the [Attribute Lists] extension:
=== ":octicons-file-code-16: docs/page.md" === ":octicons-file-code-16: `docs/page.md`"
``` markdown ``` markdown
# Document title # Document title
@ -192,7 +181,7 @@ supported by the [Attribute Lists] extension:
{ data-search-exclude } { data-search-exclude }
``` ```
=== ":octicons-codescan-16: search_index.json" === ":octicons-codescan-16: `search_index.json`"
``` json ``` json
{ {

36
docs/blog/2021/search-better-faster-smaller.md → docs/blog/posts/search-better-faster-smaller.md
View File

@ -1,12 +1,16 @@
--- ---
template: overrides/blog.html date: 2021-09-13
authors: [squidfunk]
readtime: 15
description: > description: >
How we rebuilt client-side search, delivering a better user experience while How we rebuilt client-side search, delivering a better user experience while
making it faster and smaller at the same time making it faster and smaller at the same time
search: categories:
exclude: true - Search
hide: - Performance
- feedback links:
- setup/setting-up-site-search.md#built-in-search-plugin
- insiders/index.md#how-to-become-a-sponsor
--- ---
# Search: better, faster, smaller # Search: better, faster, smaller
@ -15,22 +19,6 @@ __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 delivering a significantly better user experience while making it faster and
smaller at the same time.__ smaller at the same time.__
<aside class="mdx-author" markdown>
![@squidfunk][@squidfunk avatar]
<span>__Martin Donath__ · @squidfunk</span>
<span>
:octicons-calendar-24: September 13, 2021 ·
:octicons-clock-24: 15 min read ·
[:octicons-tag-24: 7.2.6+insiders-3.0.0][insiders-3.0.0]
</span>
</aside>
[@squidfunk avatar]: https://avatars.githubusercontent.com/u/932156
[insiders-3.0.0]: ../../insiders/changelog.md#3.0.0
---
The [search] of Material for MkDocs is by far one of its best and most-loved The [search] of Material for MkDocs is by far one of its best and most-loved
assets: [multilingual], [offline-capable], and most importantly: _all assets: [multilingual], [offline-capable], and most importantly: _all
client-side_. It provides a solution to empower the users of your documentation client-side_. It provides a solution to empower the users of your documentation
@ -41,6 +29,8 @@ plugin and integration from the ground up. This article shines some light on the
internals of the new search, why it's much more powerful than the previous internals of the new search, why it's much more powerful than the previous
version, and what's about to come. version, and what's about to come.
<!-- more -->
_The next section discusses the architecture and issues of the current search _The next section discusses the architecture and issues of the current search
implementation. If you immediately want to learn what's new, skip to the implementation. If you immediately want to learn what's new, skip to the
[section just after that][what's new]._ [section just after that][what's new]._
@ -78,7 +68,7 @@ the original Markdown file:
??? example "Expand to inspect example" ??? example "Expand to inspect example"
=== ":octicons-file-code-16: docs/page.md" === ":octicons-file-code-16: `docs/page.md`"
```` markdown ```` markdown
# Example # Example
@ -108,7 +98,7 @@ the original Markdown file:
* Profit! * Profit!
```` ````
=== ":octicons-codescan-16: search_index.json" === ":octicons-codescan-16: `search_index.json`"
``` json ``` json
{ {

0
docs/blog/2021/search-better-faster-smaller/search-preview-before.png → docs/blog/posts/search-better-faster-smaller/search-preview-before.png
View File

Side by Side Swipe Overlay

Before

Width:  |  Height:  |  Size: 225 KiB

After

Width:  |  Height:  |  Size: 225 KiB

0
docs/blog/2021/search-better-faster-smaller/search-preview-now.png → docs/blog/posts/search-better-faster-smaller/search-preview-now.png
View File

Side by Side Swipe Overlay

Before

Width:  |  Height:  |  Size: 174 KiB

After

Width:  |  Height:  |  Size: 174 KiB

0
docs/blog/2021/search-better-faster-smaller/search-preview.png → docs/blog/posts/search-better-faster-smaller/search-preview.png
View File

Side by Side Swipe Overlay

Before

Width:  |  Height:  |  Size: 55 KiB

After

Width:  |  Height:  |  Size: 55 KiB

27
docs/blog/2021/the-past-present-and-future.md → docs/blog/posts/the-past-present-and-future.md
View File

@ -1,12 +1,11 @@
--- ---
template: overrides/blog.html date: 2021-12-27
authors: [squidfunk]
description: > description: >
2021 was a fantastic year for this project as we shipped many new awesome 2021 was a fantastic year for this project as we shipped many new awesome
features and made this project sustainable features and made this project sustainable
search: categories:
exclude: true - General
hide:
- feedback
--- ---
# The past, present and future # The past, present and future
@ -15,20 +14,6 @@ __2021 was a fantastic year for this project as we shipped many new awesome
features, saw significant user growth and leveraged GitHub Sponsors to make the features, saw significant user growth and leveraged GitHub Sponsors to make the
project sustainable.__ project sustainable.__
<aside class="mdx-author" markdown>
![@squidfunk][@squidfunk avatar]
<span>__Martin Donath__ · @squidfunk</span>
<span>
:octicons-calendar-24: December 27, 2021 ·
:octicons-clock-24: 10 min read
</span>
</aside>
[@squidfunk avatar]: https://avatars.githubusercontent.com/u/932156
---
Today, together, [MkDocs] and Material for MkDocs are among the most popular Today, together, [MkDocs] and Material for MkDocs are among the most popular
options when it comes to choosing a static site generator and theme for your options when it comes to choosing a static site generator and theme for your
technical documentation project. Material for MkDocs ensures that your technical documentation project. Material for MkDocs ensures that your
@ -38,6 +23,8 @@ writing, offering many features, some of which are yet to be found in other
static site generators. However, we're far from the end, as 2022 is going to static site generators. However, we're far from the end, as 2022 is going to
bring some interesting new capabilities. bring some interesting new capabilities.
<!-- more -->
_This article showcases all features that were added in 2021 and gives an _This article showcases all features that were added in 2021 and gives an
outlook on what's going to drop in 2022. Additionally, it provides some context outlook on what's going to drop in 2022. Additionally, it provides some context
on the history of the project._ on the history of the project._
@ -187,7 +174,7 @@ __55__ times, `mkdocs-material-insiders` was shipped __72__ times.
[Color palette toggle]: ../../setup/changing-the-colors.md#color-palette-toggle [Color palette toggle]: ../../setup/changing-the-colors.md#color-palette-toggle
[Content tabs: improved support]: ../../reference/content-tabs.md [Content tabs: improved support]: ../../reference/content-tabs.md
[Content tabs: auto-linking]: ../../reference/content-tabs.md#linked-content-tabs [Content tabs: auto-linking]: ../../reference/content-tabs.md#linked-content-tabs
[Cookie consent]: ../../setup/ensuring-data-privacy.md#native-cookie-consent [Cookie consent]: ../../setup/ensuring-data-privacy.md#cookie-consent
[Custom admonition icons]: ../../reference/admonitions.md#admonition-icons [Custom admonition icons]: ../../reference/admonitions.md#admonition-icons
[Dark mode support for images]: ../../reference/images.md#light-and-dark-mode [Dark mode support for images]: ../../reference/images.md#light-and-dark-mode
[Dismissable announcement bar]: ../../setup/setting-up-the-header.md#mark-as-read [Dismissable announcement bar]: ../../setup/setting-up-the-header.md#mark-as-read

0
docs/blog/2021/the-past-present-and-future/funding.png → docs/blog/posts/the-past-present-and-future/funding.png
View File

Side by Side Swipe Overlay

Before

Width:  |  Height:  |  Size: 94 KiB

After

Width:  |  Height:  |  Size: 94 KiB

0
docs/blog/2021/the-past-present-and-future/mkdocs-material-0.1.0-search.png → docs/blog/posts/the-past-present-and-future/mkdocs-material-0.1.0-search.png
View File

Side by Side Swipe Overlay

Before

Width:  |  Height:  |  Size: 74 KiB

After

Width:  |  Height:  |  Size: 74 KiB

0
docs/blog/2021/the-past-present-and-future/mkdocs-material-0.1.0.png → docs/blog/posts/the-past-present-and-future/mkdocs-material-0.1.0.png
View File

Side by Side Swipe Overlay

Before

Width:  |  Height:  |  Size: 93 KiB

After

Width:  |  Height:  |  Size: 93 KiB

4
docs/browser-support.md
View File

@ -15,8 +15,8 @@ modern CSS features like [custom properties] and [mask images].
The following table lists all browsers for which Material for MkDocs offers full The following table lists all browsers for which Material for MkDocs offers full
support, so it can be assumed that all features work without degradation. If you support, so it can be assumed that all features work without degradation. If you
find a feature not to be working in a browser in the supported version range, find that something doesn't look right in a browser which is in the supported
please [open an issue]: version range, please [open an issue]:
<figure markdown> <figure markdown>

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

@ -153,6 +153,7 @@ and much more:
- [Setting up site search] - [Setting up site search]
- [Setting up site analytics] - [Setting up site analytics]
- [Setting up social cards] - [Setting up social cards]
- [Setting up a blog]
- [Setting up tags] - [Setting up tags]
- [Setting up versioning] - [Setting up versioning]
- [Setting up the header] - [Setting up the header]
@ -164,7 +165,7 @@ and much more:
</div> </div>
Furthermore, see the list of supported [Markdown extensions] that are natively Furthermore, see the list of supported [Markdown extensions] that are natively
integrated with Material for MkDocs, delivering a low-effort and unprecedented integrated with Material for MkDocs, delivering an unprecedented low-effort
technical writing experience. technical writing experience.
[Changing the colors]: setup/changing-the-colors.md [Changing the colors]: setup/changing-the-colors.md
@ -176,6 +177,7 @@ technical writing experience.
[Setting up site search]: setup/setting-up-site-search.md [Setting up site search]: setup/setting-up-site-search.md
[Setting up site analytics]: setup/setting-up-site-analytics.md [Setting up site analytics]: setup/setting-up-site-analytics.md
[Setting up social cards]: setup/setting-up-social-cards.md [Setting up social cards]: setup/setting-up-social-cards.md
[Setting up a blog]: setup/setting-up-a-blog.md
[Setting up tags]: setup/setting-up-tags.md [Setting up tags]: setup/setting-up-tags.md
[Setting up versioning]: setup/setting-up-versioning.md [Setting up versioning]: setup/setting-up-versioning.md
[Setting up the header]: setup/setting-up-the-header.md [Setting up the header]: setup/setting-up-the-header.md

15
docs/customization.md
View File

@ -103,26 +103,38 @@ assets may also be put in the `overrides` directory:
│ │ ├─ analytics/ # Analytics integrations │ │ ├─ analytics/ # Analytics integrations
│ │ └─ analytics.html # Analytics setup │ │ └─ analytics.html # Analytics setup
│ ├─ languages/ # Translation languages │ ├─ languages/ # Translation languages
│ ├─ actions.html # Actions
│ ├─ comments.html # Comment system (empty by default)
│ ├─ consent.html # Consent
│ ├─ content.html # Page content │ ├─ content.html # Page content
│ ├─ copyright.html # Copyright and theme information │ ├─ copyright.html # Copyright and theme information
│ ├─ feedback.html # Was this page helpful?
│ ├─ footer.html # Footer bar │ ├─ footer.html # Footer bar
│ ├─ header.html # Header bar │ ├─ header.html # Header bar
│ ├─ icons.html # Custom icons
│ ├─ language.html # Translation setup │ ├─ language.html # Translation setup
│ ├─ logo.html # Logo in header and sidebar │ ├─ logo.html # Logo in header and sidebar
│ ├─ nav.html # Main navigation │ ├─ nav.html # Main navigation
│ ├─ nav-item.html # Main navigation item │ ├─ nav-item.html # Main navigation item
│ ├─ pagination.html # Pagination (used for blog)
│ ├─ palette.html # Color palette │ ├─ palette.html # Color palette
│ ├─ post.html # Blog post excerpt
│ ├─ search.html # Search interface │ ├─ search.html # Search interface
│ ├─ social.html # Social links │ ├─ social.html # Social links
│ ├─ source.html # Repository information │ ├─ source.html # Repository information
│ ├─ source-file.html # Source file information │ ├─ source-file.html # Source file information
│ ├─ tabs.html # Tabs navigation │ ├─ tabs.html # Tabs navigation
│ ├─ tabs-item.html # Tabs navigation item │ ├─ tabs-item.html # Tabs navigation item
│ ├─ tags.html # Tags
│ ├─ toc.html # Table of contents │ ├─ toc.html # Table of contents
│ └─ toc-item.html # Table of contents item │ └─ toc-item.html # Table of contents item
├─ 404.html # 404 error page ├─ 404.html # 404 error page
├─ base.html # Base template ├─ base.html # Base template
└─ main.html # Default page ├─ blog.html # Blog index
├─ blog-archive.html # Blog archive index
├─ blog-category.html # Blog category index
├─ blog-post.html # Blog post
└─ main.html # Page
``` ```
[custom_dir]: https://www.mkdocs.org/user-guide/configuration/#custom_dir [custom_dir]: https://www.mkdocs.org/user-guide/configuration/#custom_dir
@ -192,6 +204,7 @@ The following template blocks are provided by the theme:
| `analytics` | Wraps the Google Analytics integration | | `analytics` | Wraps the Google Analytics integration |
| `announce` | Wraps the announcement bar | | `announce` | Wraps the announcement bar |
| `config` | Wraps the JavaScript application config | | `config` | Wraps the JavaScript application config |
| `container` | Wraps the main content container |
| `content` | Wraps the main content | | `content` | Wraps the main content |
| `extrahead` | Empty block to add custom meta tags | | `extrahead` | Empty block to add custom meta tags |
| `fonts` | Wraps the font definitions | | `fonts` | Wraps the font definitions |

15
docs/getting-started.md
View File

@ -1,6 +1,5 @@
--- ---
template: overrides/main.html template: overrides/main.html
title: Getting started
--- ---
# Getting started # Getting started
@ -19,8 +18,8 @@ If not, we recommend using [`docker`][docker].
### with pip <small>recommended</small> { #with-pip data-toc-label="with pip" } ### with pip <small>recommended</small> { #with-pip data-toc-label="with pip" }
Material for MkDocs is published as a [Python package] and can be installed with Material for MkDocs is published as a [Python package] and can be installed with
`pip`, ideally by using a [virtual environment]. If not, scroll down and expand `pip`, ideally by using a [virtual environment]. Open up a terminal and install
the help box. Install with: Material for MkDocs with:
=== "Latest" === "Latest"
@ -38,7 +37,7 @@ the help box. Install with:
good idea to limit upgrades to the current major version. good idea to limit upgrades to the current major version.
This will make sure that you don't accidentally [upgrade to the next This will make sure that you don't accidentally [upgrade to the next
major version], which may include breaking changes that silently break major version], which may include breaking changes that silently corrupt
your site. Additionally, you can use `pip freeze` to create a lockfile, your site. Additionally, you can use `pip freeze` to create a lockfile,
so builds are reproducible at all times: so builds are reproducible at all times:
@ -81,8 +80,8 @@ troubleshoot if you run into errors.
### with docker ### with docker
The official [Docker image] 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 minutes, as it comes with all dependencies pre-installed. Open up a terminal
`latest` version with: and pull the image with:
=== "Latest" === "Latest"
@ -151,8 +150,8 @@ want to use the very latest version:
git clone https://github.com/squidfunk/mkdocs-material.git git clone https://github.com/squidfunk/mkdocs-material.git
``` ```
The theme will reside in the folder `mkdocs-material/material`. When cloning The theme will reside in the folder `mkdocs-material/material`. After cloning
from `git`, you must install all required dependencies yourself: from `git`, you must install all required dependencies with:
``` ```
pip install -e mkdocs-material pip install -e mkdocs-material

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

@ -97,10 +97,9 @@ docker pull ghcr.io/${GH_USERNAME}/mkdocs-material-insiders
dedicated token which you'll only use for publishing the Docker image. dedicated token which you'll only use for publishing the Docker image.
[^5]: [^5]:
The Insiders repository contains three GitHub Actions workflows: The Insiders repository contains two GitHub Actions workflows:
- `build.yml` – Build and lint the project (disabled on forks) - `build.yml` – Build and lint the project (disabled on forks)
- `documentation.yml` – Build and deploy the documentation (disabled on forks)
- `publish.yml` – Build and publish the Docker image - `publish.yml` – Build and publish the Docker image
### with git ### with git
@ -162,7 +161,7 @@ necessary to split the `mkdocs.yml` configuration into a base configuration, and
one with plugin overrides. Note that this is a limitation of MkDocs, which can one with plugin overrides. Note that this is a limitation of MkDocs, which can
be mitigated by using [configuration inheritance]: be mitigated by using [configuration inheritance]:
=== ":octicons-file-code-16: mkdocs.insiders.yml" === ":octicons-file-code-16: `mkdocs.insiders.yml`"
``` yaml ``` yaml
INHERIT: mkdocs.yml INHERIT: mkdocs.yml
@ -172,7 +171,7 @@ be mitigated by using [configuration inheritance]:
- tags - tags
``` ```
=== ":octicons-file-code-16: mkdocs.yml" === ":octicons-file-code-16: `mkdocs.yml`"
``` yaml ``` yaml
# Configuration with everything except Insiders plugins # Configuration with everything except Insiders plugins
@ -192,7 +191,7 @@ mkdocs build --config-file mkdocs.insiders.yml
the alternative key-value syntax in both files. The above example would the alternative key-value syntax in both files. The above example would
then look like: then look like:
=== ":octicons-file-code-16: mkdocs.insiders.yml" === ":octicons-file-code-16: `mkdocs.insiders.yml`"
``` yaml ``` yaml
INHERIT: mkdocs.yml INHERIT: mkdocs.yml
@ -200,7 +199,7 @@ mkdocs build --config-file mkdocs.insiders.yml
social: {} social: {}
``` ```
=== ":octicons-file-code-16: mkdocs.yml" === ":octicons-file-code-16 `mkdocs.yml`"
``` yaml ``` yaml
# Additional configuration above # Additional configuration above

24
docs/insiders/index.md
View File

@ -82,14 +82,16 @@ a handful of them, [thanks to our awesome sponsors]!
## What's in for me? ## What's in for me?
The moment you [become a sponsor][how to become a sponsor], you'll get __immediate The moment you [become a sponsor][how to become a sponsor], you'll get __immediate
access to 25 additional features__ that you can start using right away, and access to 27 additional features__ that you can start using right away, and
which are currently exclusively available to sponsors: which are currently exclusively available to sponsors:
<div class="mdx-columns" markdown> <div class="mdx-columns" markdown>
- [x] [Blog plugin] :material-alert-decagram:{ .mdx-pulse title="Added on September 12, 2022" }
- [x] [Blog plugin: related links] :material-alert-decagram:{ .mdx-pulse title="Added on September 12, 2022" }
- [x] [Navigation status] :material-alert-decagram:{ .mdx-pulse title="Added on August 21, 2022" } - [x] [Navigation status] :material-alert-decagram:{ .mdx-pulse title="Added on August 21, 2022" }
- [x] [Meta plugin] :material-alert-decagram:{ .mdx-pulse title="Added on July 17, 2022" } - [x] [Meta plugin] :material-alert-decagram:{ .mdx-pulse title="Added on July 17, 2022" }
- [x] [Additional tags indexes] :material-alert-decagram:{ .mdx-pulse title="Added on July 7, 2022" } - [x] [Additional tags indexes]
- [x] [Document contributors] - [x] [Document contributors]
- [x] [Automatic light / dark mode] - [x] [Automatic light / dark mode]
- [x] [Content tabs: anchor links] - [x] [Content tabs: anchor links]
@ -258,10 +260,10 @@ are released for general availability.
- [x] [Excluding content from search] - [x] [Excluding content from search]
- [x] [Offline plugin] - [x] [Offline plugin]
[Brand new search plugin]: ../blog/2021/search-better-faster-smaller.md [Brand new search plugin]: ../blog/posts/search-better-faster-smaller.md
[Rich search previews]: ../blog/2021/search-better-faster-smaller.md#rich-search-previews [Rich search previews]: ../blog/posts/search-better-faster-smaller.md#rich-search-previews
[Tokenizer with lookahead]: ../blog/2021/search-better-faster-smaller.md#tokenizer-lookahead [Tokenizer with lookahead]: ../blog/posts/search-better-faster-smaller.md#tokenizer-lookahead
[Advanced search highlighting]: ../blog/2021/search-better-faster-smaller.md#accurate-highlighting [Advanced search highlighting]: ../blog/posts/search-better-faster-smaller.md#accurate-highlighting
[Excluding content from search]: ../setup/setting-up-site-search.md#search-exclusion [Excluding content from search]: ../setup/setting-up-site-search.md#search-exclusion
[Offline plugin]: ../setup/building-for-offline-usage.md [Offline plugin]: ../setup/building-for-offline-usage.md
@ -272,13 +274,14 @@ are released for general availability.
- [x] [Navigation icons] - [x] [Navigation icons]
- [x] [Navigation pruning] - [x] [Navigation pruning]
- [x] [Navigation status] - [x] [Navigation status]
- [ ] Blog plugin - [x] [Blog plugin]
[Annotations]: ../reference/annotations.md [Annotations]: ../reference/annotations.md
[Chinese search support]: ../blog/2022/chinese-search-support.md [Chinese search support]: ../blog/posts/chinese-search-support.md
[Navigation icons]: ../reference/index.md#setting-the-page-icon [Navigation icons]: ../reference/index.md#setting-the-page-icon
[Navigation pruning]: ../setup/setting-up-navigation.md#navigation-pruning [Navigation pruning]: ../setup/setting-up-navigation.md#navigation-pruning
[Navigation status]: ../reference/index.md#setting-the-page-status [Navigation status]: ../reference/index.md#setting-the-page-status
[Blog plugin]: ../setup/setting-up-a-blog.md
#### $ 14,000 – Goat's Horn #### $ 14,000 – Goat's Horn
@ -298,14 +301,17 @@ are released for general availability.
#### $ 16,000 – Chipotle #### $ 16,000 – Chipotle
- [x] [Blog plugin: related links]
- [x] [Meta plugin] - [x] [Meta plugin]
- [x] [Additional tags indexes] - [x] [Additional tags indexes]
- [ ] [Navigation subtitles]
- [ ] [Instant previews] - [ ] [Instant previews]
- [ ] ... more to be announced - [ ] ... more to be announced
[Meta plugin]: ../reference/index.md#built-in-meta-plugin [Meta plugin]: ../reference/index.md#built-in-meta-plugin
[Additional tags indexes]: ../setup/setting-up-tags.md#tags-extra-files [Additional tags indexes]: ../setup/setting-up-tags.md#tags-extra-files
[Instant previews]: https://twitter.com/squidfunk/status/1466794654213492743 [Instant previews]: https://twitter.com/squidfunk/status/1466794654213492743
[Blog plugin: related links]: ../setup/setting-up-a-blog.md#adding-related-links
### Goals completed ### Goals completed
@ -319,7 +325,7 @@ can be used by all users.
- [x] [Was this page helpful?] - [x] [Was this page helpful?]
- [x] [Dismissable announcement bar] - [x] [Dismissable announcement bar]
[Cookie consent]: ../setup/ensuring-data-privacy.md#native-cookie-consent [Cookie consent]: ../setup/ensuring-data-privacy.md#cookie-consent
[Was this page helpful?]: ../setup/setting-up-site-analytics.md#was-this-page-helpful [Was this page helpful?]: ../setup/setting-up-site-analytics.md#was-this-page-helpful
[Dismissable announcement bar]: ../setup/setting-up-the-header.md#mark-as-read [Dismissable announcement bar]: ../setup/setting-up-the-header.md#mark-as-read

36
docs/reference/admonitions.md
View File

@ -35,7 +35,7 @@ See additional configuration options:
### Admonition icons ### Admonition icons
[:octicons-tag-24: 8.3.0][icon support] · [:octicons-tag-24: 8.3.0][Admonition icons support] ·
:octicons-beaker-24: Experimental :octicons-beaker-24: Experimental
Each of the supported admonition types has a distinct icon, which can be changed Each of the supported admonition types has a distinct icon, which can be changed
@ -103,7 +103,7 @@ theme:
quote: fontawesome/solid/quote-left quote: fontawesome/solid/quote-left
``` ```
[icon support]: https://github.com/squidfunk/mkdocs-material/releases/tag/8.3.0 [Admonition icons support]: https://github.com/squidfunk/mkdocs-material/releases/tag/8.3.0
[custom icon]: ../setup/changing-the-logo-and-icons.md#additional-icons [custom icon]: ../setup/changing-the-logo-and-icons.md#additional-icons
[supported types]: #supported-types [supported types]: #supported-types
[icon search]: icons-emojis.md#search [icon search]: icons-emojis.md#search
@ -231,7 +231,7 @@ Adding a `+` after the `???` token renders the block expanded:
### Inline blocks ### Inline blocks
[:octicons-tag-24: 7.0.0][Inline support] · [:octicons-tag-24: 7.0.0][Inline blocks support] ·
:octicons-beaker-24: Experimental :octicons-beaker-24: Experimental
Admonitions can also be rendered as inline blocks (i.e. for sidebars), placing Admonitions can also be rendered as inline blocks (i.e. for sidebars), placing
@ -283,14 +283,14 @@ 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 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. 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 [Inline blocks support]: https://github.com/squidfunk/mkdocs-material/releases/tag/7.0.0
### Supported types ### Supported types
Following is a list of type qualifiers provided by Material for MkDocs, whereas 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`: the default type, and thus fallback for unknown type qualifiers, is `note`:
`note`{ #type-note } [`note`](#type:note){ #type:note }
: !!! note : !!! note
@ -298,7 +298,7 @@ the default type, and thus fallback for unknown type qualifiers, is `note`:
euismod nulla. Curabitur feugiat, tortor non consequat finibus, justo euismod nulla. Curabitur feugiat, tortor non consequat finibus, justo
purus auctor massa, nec semper lorem quam in massa. purus auctor massa, nec semper lorem quam in massa.
`abstract`{ #type-abstract }, `summary`, `tldr` [`abstract`](#type:abstract){ #type:abstract }, `summary`, `tldr`
: !!! abstract : !!! abstract
@ -306,7 +306,7 @@ the default type, and thus fallback for unknown type qualifiers, is `note`:
euismod nulla. Curabitur feugiat, tortor non consequat finibus, justo euismod nulla. Curabitur feugiat, tortor non consequat finibus, justo
purus auctor massa, nec semper lorem quam in massa. purus auctor massa, nec semper lorem quam in massa.
`info`{ #type-info }, `todo` [`info`](#type:info){ #type:info }, `todo`
: !!! info : !!! info
@ -314,7 +314,7 @@ the default type, and thus fallback for unknown type qualifiers, is `note`:
euismod nulla. Curabitur feugiat, tortor non consequat finibus, justo euismod nulla. Curabitur feugiat, tortor non consequat finibus, justo
purus auctor massa, nec semper lorem quam in massa. purus auctor massa, nec semper lorem quam in massa.
`tip`{ #type-tip }, `hint`, `important` [`tip`](#type:tip){ #type:tip }, `hint`, `important`
: !!! tip : !!! tip
@ -322,7 +322,7 @@ the default type, and thus fallback for unknown type qualifiers, is `note`:
euismod nulla. Curabitur feugiat, tortor non consequat finibus, justo euismod nulla. Curabitur feugiat, tortor non consequat finibus, justo
purus auctor massa, nec semper lorem quam in massa. purus auctor massa, nec semper lorem quam in massa.
`success`{ #type-success }, `check`, `done` [`success`](#type:success){ #type:success }, `check`, `done`
: !!! success : !!! success
@ -330,7 +330,7 @@ the default type, and thus fallback for unknown type qualifiers, is `note`:
euismod nulla. Curabitur feugiat, tortor non consequat finibus, justo euismod nulla. Curabitur feugiat, tortor non consequat finibus, justo
purus auctor massa, nec semper lorem quam in massa. purus auctor massa, nec semper lorem quam in massa.
`question`{ #type-question }, `help`, `faq` [`question`](#type:question){ #type:question }, `help`, `faq`
: !!! question : !!! question
@ -338,7 +338,7 @@ the default type, and thus fallback for unknown type qualifiers, is `note`:
euismod nulla. Curabitur feugiat, tortor non consequat finibus, justo euismod nulla. Curabitur feugiat, tortor non consequat finibus, justo
purus auctor massa, nec semper lorem quam in massa. purus auctor massa, nec semper lorem quam in massa.
`warning`{ #type-warning }, `caution`, `attention` [`warning`](#type:warning){ #type:warning }, `caution`, `attention`
: !!! warning : !!! warning
@ -346,7 +346,7 @@ the default type, and thus fallback for unknown type qualifiers, is `note`:
euismod nulla. Curabitur feugiat, tortor non consequat finibus, justo euismod nulla. Curabitur feugiat, tortor non consequat finibus, justo
purus auctor massa, nec semper lorem quam in massa. purus auctor massa, nec semper lorem quam in massa.
`failure`{ #type-failure }, `fail`, `missing` [`failure`](#type:failure){ #type:failure }, `fail`, `missing`
: !!! failure : !!! failure
@ -354,7 +354,7 @@ the default type, and thus fallback for unknown type qualifiers, is `note`:
euismod nulla. Curabitur feugiat, tortor non consequat finibus, justo euismod nulla. Curabitur feugiat, tortor non consequat finibus, justo
purus auctor massa, nec semper lorem quam in massa. purus auctor massa, nec semper lorem quam in massa.
`danger`{ #type-danger }, `error` [`danger`](#type:danger){ #type:danger }, `error`
: !!! danger : !!! danger
@ -362,7 +362,7 @@ the default type, and thus fallback for unknown type qualifiers, is `note`:
euismod nulla. Curabitur feugiat, tortor non consequat finibus, justo euismod nulla. Curabitur feugiat, tortor non consequat finibus, justo
purus auctor massa, nec semper lorem quam in massa. purus auctor massa, nec semper lorem quam in massa.
`bug`{ #type-bug } [`bug`](#type:bug){ #type:bug }
: !!! bug : !!! bug
@ -370,7 +370,7 @@ the default type, and thus fallback for unknown type qualifiers, is `note`:
euismod nulla. Curabitur feugiat, tortor non consequat finibus, justo euismod nulla. Curabitur feugiat, tortor non consequat finibus, justo
purus auctor massa, nec semper lorem quam in massa. purus auctor massa, nec semper lorem quam in massa.
`example`{ #type-example } [`example`](#type:example){ #type:example }
: !!! example : !!! example
@ -378,7 +378,7 @@ the default type, and thus fallback for unknown type qualifiers, is `note`:
euismod nulla. Curabitur feugiat, tortor non consequat finibus, justo euismod nulla. Curabitur feugiat, tortor non consequat finibus, justo
purus auctor massa, nec semper lorem quam in massa. purus auctor massa, nec semper lorem quam in massa.
`quote`{ #type-quote }, `cite` [`quote`](#type:quote){ #type:quote }, `cite`
: !!! quote : !!! quote
@ -414,7 +414,7 @@ and add the following CSS to an [additional style sheet]:
} }
</style> </style>
=== ":octicons-file-code-16: docs/stylesheets/extra.css" === ":octicons-file-code-16: `docs/stylesheets/extra.css`"
``` css ``` css
:root { :root {
@ -436,7 +436,7 @@ and add the following CSS to an [additional style sheet]:
} }
``` ```
=== ":octicons-file-code-16: mkdocs.yml" === ":octicons-file-code-16: `mkdocs.yml`"
``` yaml ``` yaml
extra_css: extra_css:

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

@ -126,8 +126,6 @@ import tensorflow as tf
### Adding a title ### Adding a title
[:octicons-tag-24: 7.3.6][Title support]
In order to provide additional context, a custom title can be added to a code In order to provide additional context, a custom title can be added to a code
block by using the `title="<custom title>"` option directly after the shortcode, block by using the `title="<custom title>"` option directly after the shortcode,
e.g. to display the name of a file: e.g. to display the name of a file:
@ -154,8 +152,6 @@ def bubble_sort(items):
</div> </div>
[Title support]: https://github.com/squidfunk/mkdocs-material/releases/tag/7.3.6
### Adding annotations ### Adding annotations
Code annotations can be placed anywhere in a code block where a comment for the Code annotations can be placed anywhere in a code block where a comment for the
@ -354,7 +350,7 @@ Let's say you want to change the color of `#!js "strings"`. While there are
several [types of string tokens], they use the same color. You can assign several [types of string tokens], they use the same color. You can assign
a new color by using an [additional style sheet]: a new color by using an [additional style sheet]:
=== ":octicons-file-code-16: docs/stylesheets/extra.css" === ":octicons-file-code-16: `docs/stylesheets/extra.css`"
``` css ``` css
:root > * { :root > * {
@ -362,7 +358,7 @@ a new color by using an [additional style sheet]:
} }
``` ```
=== ":octicons-file-code-16: mkdocs.yml" === ":octicons-file-code-16: `mkdocs.yml`"
``` yaml ``` yaml
extra_css: extra_css:
@ -373,7 +369,7 @@ 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 can lookup the specific CSS class name in the [syntax theme definition], and
override it as part of your [additional style sheet]: override it as part of your [additional style sheet]:
=== ":octicons-file-code-16: docs/stylesheets/extra.css" === ":octicons-file-code-16: `docs/stylesheets/extra.css`"
``` css ``` css
.highlight .sb { .highlight .sb {
@ -381,7 +377,7 @@ override it as part of your [additional style sheet]:
} }
``` ```
=== ":octicons-file-code-16: mkdocs.yml" === ":octicons-file-code-16: `mkdocs.yml`"
``` yaml ``` yaml
extra_css: extra_css:
@ -400,7 +396,7 @@ If you have a lot of content hosted inside your code annotations, it can be a
good idea to increase the width of the tooltip by adding the following as part good idea to increase the width of the tooltip by adding the following as part
of an [additional style sheet]: of an [additional style sheet]:
=== ":octicons-file-code-16: docs/stylesheets/extra.css" === ":octicons-file-code-16: `docs/stylesheets/extra.css`"
``` css ``` css
:root { :root {
@ -408,7 +404,7 @@ of an [additional style sheet]:
} }
``` ```
=== ":octicons-file-code-16: mkdocs.yml" === ":octicons-file-code-16: `mkdocs.yml`"
``` yaml ``` yaml
extra_css: extra_css:
@ -439,7 +435,7 @@ will close them.
If you wish to revert to the prior behavior and display code annotation numbers, If you wish to revert to the prior behavior and display code annotation numbers,
you can add an [additional style sheet] and copy and paste the following CSS: you can add an [additional style sheet] and copy and paste the following CSS:
=== ":octicons-file-code-16: docs/stylesheets/extra.css" === ":octicons-file-code-16: `docs/stylesheets/extra.css`"
``` css ``` css
.md-typeset .md-annotation__index > ::before { .md-typeset .md-annotation__index > ::before {
@ -450,7 +446,7 @@ you can add an [additional style sheet] and copy and paste the following CSS:
} }
``` ```
=== ":octicons-file-code-16: mkdocs.yml" === ":octicons-file-code-16: `mkdocs.yml`"
``` yaml ``` yaml
extra_css: extra_css:

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

@ -57,7 +57,7 @@ or to the [publishing guide for Insiders][tab_2].
### Linked content tabs ### Linked content tabs
[:octicons-tag-24: 8.3.0][link support] · [:octicons-tag-24: 8.3.0][Linked content tabs support] ·
:octicons-unlock-24: Feature flag · :octicons-unlock-24: Feature flag ·
:octicons-beaker-24: Experimental :octicons-beaker-24: Experimental
@ -76,18 +76,18 @@ 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 regardless of order inside a container. Furthermore, this feature is fully
integrated with [instant loading] and persisted across page loads. integrated with [instant loading] and persisted across page loads.
=== ":octicons-check-circle-fill-16: Enabled" === "Feature enabled"
[![content.tabs.link enabled]][content.tabs.link enabled] [![Linked content tabs enabled]][Linked content tabs enabled]
=== ":octicons-skip-16: Disabled" === "Feature disabled"
[![content.tabs.link disabled]][content.tabs.link disabled] [![Linked content tabs disabled]][Linked content tabs disabled]
[link support]: https://github.com/squidfunk/mkdocs-material/releases/tag/8.3.0 [Linked content tabs support]: https://github.com/squidfunk/mkdocs-material/releases/tag/8.3.0
[instant loading]: ../setup/setting-up-navigation.md#instant-loading [instant loading]: ../setup/setting-up-navigation.md#instant-loading
[content.tabs.link enabled]: ../assets/screenshots/content-tabs-link.png [Linked content tabs enabled]: ../assets/screenshots/content-tabs-link.png
[content.tabs.link disabled]: ../assets/screenshots/content-tabs.png [Linked content tabs disabled]: ../assets/screenshots/content-tabs.png
## Usage ## Usage

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

@ -131,7 +131,7 @@ 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 natively integrated with Material for MkDocs and will also work with [instant
loading] via [additional JavaScript]: loading] via [additional JavaScript]:
=== ":octicons-file-code-16: docs/javascripts/tablesort.js" === ":octicons-file-code-16: `docs/javascripts/tablesort.js`"
``` js ``` js
document$.subscribe(function() { document$.subscribe(function() {
@ -142,7 +142,7 @@ loading] via [additional JavaScript]:
}) })
``` ```
=== ":octicons-file-code-16: mkdocs.yml" === ":octicons-file-code-16: `mkdocs.yml`"
``` yaml ``` yaml
extra_javascript: extra_javascript:

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

@ -118,7 +118,7 @@ declarations into dedicated CSS classes:
} }
</style> </style>
=== ":octicons-file-code-16: docs/stylesheets/extra.css" === ":octicons-file-code-16: `docs/stylesheets/extra.css`"
``` css ``` css
.twitter { .twitter {
@ -126,7 +126,7 @@ declarations into dedicated CSS classes:
} }
``` ```
=== ":octicons-file-code-16: mkdocs.yml" === ":octicons-file-code-16: `mkdocs.yml`"
``` yaml ``` yaml
extra_css: extra_css:
@ -155,7 +155,7 @@ 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 using an [additional style sheet], defining a `@keyframes` rule and adding a
dedicated CSS class to the icon: dedicated CSS class to the icon:
=== ":octicons-file-code-16: docs/stylesheets/extra.css" === ":octicons-file-code-16: `docs/stylesheets/extra.css`"
``` css ``` css
@keyframes heart { @keyframes heart {
@ -171,7 +171,7 @@ dedicated CSS class to the icon:
} }
``` ```
=== ":octicons-file-code-16: mkdocs.yml" === ":octicons-file-code-16: `mkdocs.yml`"
``` yaml ``` yaml
extra_css: extra_css:

4
docs/reference/images.md
View File

@ -32,7 +32,7 @@ See additional configuration options:
### Lightbox ### Lightbox
[:octicons-tag-24: 0.1.0][glightbox support] · [:octicons-tag-24: 0.1.0][Lightbox support] ·
[:octicons-cpu-24: Plugin][glightbox] [:octicons-cpu-24: Plugin][glightbox]
If you want to add image zoom functionality to your documentation, the If you want to add image zoom functionality to your documentation, the
@ -53,7 +53,7 @@ plugins:
We recommend checking out the available We recommend checking out the available
[configuration options][glightbox options]. [configuration options][glightbox options].
[glightbox support]: https://github.com/squidfunk/mkdocs-material/releases/tag/0.1.0 [Lightbox support]: https://github.com/squidfunk/mkdocs-material/releases/tag/0.1.0
[glightbox]: https://github.com/blueswen/mkdocs-glightbox [glightbox]: https://github.com/blueswen/mkdocs-glightbox
[glightbox options]: https://github.com/blueswen/mkdocs-glightbox#usage [glightbox options]: https://github.com/blueswen/mkdocs-glightbox#usage

14
docs/reference/index.md
View File

@ -33,7 +33,7 @@ plugins:
The following configuration options are available: The following configuration options are available:
`meta_file`{ #meta-file } [`meta_file`](#+meta.meta_file){ #+meta.meta_file }
: :octicons-milestone-24: Default: `**/.meta.yml` – This option specifies the : :octicons-milestone-24: Default: `**/.meta.yml` – This option specifies the
name of the meta files that the plugin should look for. The default setting name of the meta files that the plugin should look for. The default setting
@ -57,7 +57,7 @@ The following configuration options are available:
The page title can be overridden for a document with the front matter `title` The page title can be overridden for a document with the front matter `title`
property. Add the following lines at the top of a Markdown file: property. Add the following lines at the top of a Markdown file:
``` sh ``` yaml
--- ---
title: Lorem ipsum dolor sit amet # (1)! title: Lorem ipsum dolor sit amet # (1)!
--- ---
@ -79,7 +79,7 @@ title: Lorem ipsum dolor sit amet # (1)!
The page description can be overridden for a document with the front matter The page description can be overridden for a document with the front matter
`description` property. Add the following lines at the top of a Markdown file: `description` property. Add the following lines at the top of a Markdown file:
``` sh ``` yaml
--- ---
description: Nullam urna elit, malesuada eget finibus ut, ac tortor. # (1)! description: Nullam urna elit, malesuada eget finibus ut, ac tortor. # (1)!
--- ---
@ -100,7 +100,7 @@ description: Nullam urna elit, malesuada eget finibus ut, ac tortor. # (1)!
An icon can be assigned to each page, which is then rendered as part of the An icon can be assigned to each page, which is then rendered as part of the
navigation sidebar. Add the following lines at the top of a Markdown file: navigation sidebar. Add the following lines at the top of a Markdown file:
``` sh ``` yaml
--- ---
icon: material/emoticon-happy # (1)! icon: material/emoticon-happy # (1)!
--- ---
@ -153,7 +153,7 @@ The page status can now be set for a document with the front matter `status`
property. For example, you can mark a page as `new` with the following lines at property. For example, you can mark a page as `new` with the following lines at
the top of a Markdown file: the top of a Markdown file:
``` sh ``` yaml
--- ---
status: new status: new
--- ---
@ -173,7 +173,7 @@ If you're using [theme extension] and created a new page template in the
`overrides` directory, you can enable it for a specific page. Add the following `overrides` directory, you can enable it for a specific page. Add the following
lines at the top of a Markdown file: lines at the top of a Markdown file:
``` sh ``` yaml
--- ---
template: custom.html template: custom.html
--- ---
@ -185,7 +185,7 @@ template: custom.html
??? question "How to set a page template for an entire folder?" ??? question "How to set a page template for an entire folder?"
With the help of the [built-in meta plugin], you can set a custom template With the help of the [built-in meta plugin], you can set a custom template
for an entire section and all nested pages, by creating a `.meta.yml` for an entire section and all nested pages, by creating a `.meta.yml` file
in the corresponding folder with the following content: in the corresponding folder with the following content:
``` yaml ``` yaml

4
docs/reference/mathjax.md
View File

@ -21,7 +21,7 @@ This configuration enables support for rendering block and inline block
equations through [MathJax]. Create a configuration file and add the following equations through [MathJax]. Create a configuration file and add the following
lines to `mkdocs.yml`: lines to `mkdocs.yml`:
=== ":octicons-file-code-16: docs/javascripts/mathjax.js" === ":octicons-file-code-16: `docs/javascripts/mathjax.js`"
``` js ``` js
window.MathJax = { window.MathJax = {
@ -44,7 +44,7 @@ lines to `mkdocs.yml`:
1. This integrates MathJax with [instant loading]. 1. This integrates MathJax with [instant loading].
=== ":octicons-file-code-16: mkdocs.yml" === ":octicons-file-code-16: `mkdocs.yml`"
``` yaml ``` yaml
markdown_extensions: markdown_extensions:

23
docs/reference/tooltips.md
View File

@ -4,18 +4,18 @@ icon: material/tooltip-plus
status: new status: new
--- ---
# Tooltips # Abbreviations
Material for MkDocs makes it trivial to add tooltips to links, abbreviations Technical documentation often incurs the usage of many acronyms, which may
and all other elements, which allows for implementing glossary-like need additional explanation, especially for new user of your project. For these
functionality, as well as small hints that are shown when the user hovers or matters, Material for MkDocs uses a combination of Markdown extensions to
focuses an element. enable site-wide glossaries.
## Configuration ## Configuration
This configuration enables support for tooltips and abbreviations and allows to This configuration enables abbreviations and allows to build a simple
build a simple glossary, sourcing definitions from a central location. Add the project-wide glossary, sourcing definitions from a central location. Add the
following lines to `mkdocs.yml`: following line to `mkdocs.yml`:
``` yaml ``` yaml
markdown_extensions: markdown_extensions:
@ -108,7 +108,7 @@ extension:
### Adding abbreviations ### Adding abbreviations
Abbreviations can be defined by using a special syntax similar to [links] and Abbreviations can be defined by using a special syntax similar to URLs and
[footnotes], starting with a `*` and immediately followed by the term or [footnotes], starting with a `*` and immediately followed by the term or
acronym to be associated in square brackets: acronym to be associated in square brackets:
@ -128,7 +128,6 @@ The HTML specification is maintained by the W3C.
</div> </div>
[links]: #adding-tooltips
[footnotes]: footnotes.md [footnotes]: footnotes.md
### Adding a glossary ### Adding a glossary
@ -143,14 +142,14 @@ pages with the following configuration:
`includes` is used), as MkDocs might otherwise complain about an `includes` is used), as MkDocs might otherwise complain about an
unreferenced file. unreferenced file.
=== ":octicons-file-code-16: includes/abbreviations.md" === ":octicons-file-code-16: `includes/abbreviations.md`"
```` markdown ```` markdown
*[HTML]: Hyper Text Markup Language *[HTML]: Hyper Text Markup Language
*[W3C]: World Wide Web Consortium *[W3C]: World Wide Web Consortium
```` ````
=== ":octicons-file-code-16: mkdocs.yml" === ":octicons-file-code-16: `mkdocs.yml`"
```` yaml ```` yaml
markdown_extensions: markdown_extensions:

12
docs/schema/extensions/markdown.json
View File

@ -91,17 +91,17 @@
"type": "object", "type": "object",
"properties": { "properties": {
"title": { "title": {
"markdownDescription": "https://squidfunk.github.io/mkdocs-material/setup/extensions/python-markdown/#toc-title", "markdownDescription": "https://squidfunk.github.io/mkdocs-material/setup/extensions/python-markdown/#+toc.title",
"type": "string" "type": "string"
}, },
"permalink": { "permalink": {
"oneOf": [ "oneOf": [
{ {
"markdownDescription": "https://squidfunk.github.io/mkdocs-material/setup/extensions/python-markdown/#toc-permalink", "markdownDescription": "https://squidfunk.github.io/mkdocs-material/setup/extensions/python-markdown/#+toc.permalink",
"type": "boolean" "type": "boolean"
}, },
{ {
"markdownDescription": "https://squidfunk.github.io/mkdocs-material/setup/extensions/python-markdown/#toc-permalink", "markdownDescription": "https://squidfunk.github.io/mkdocs-material/setup/extensions/python-markdown/#+toc.permalink",
"type": "string" "type": "string"
} }
], ],
@ -113,15 +113,15 @@
"default": false "default": false
}, },
"permalink_title": { "permalink_title": {
"markdownDescription": "https://squidfunk.github.io/mkdocs-material/setup/extensions/python-markdown/#toc-permalink-title", "markdownDescription": "https://squidfunk.github.io/mkdocs-material/setup/extensions/python-markdown/#+toc.permalink_title",
"type": "string" "type": "string"
}, },
"slugify": { "slugify": {
"markdownDescription": "https://squidfunk.github.io/mkdocs-material/setup/extensions/python-markdown/#toc-slugify", "markdownDescription": "https://squidfunk.github.io/mkdocs-material/setup/extensions/python-markdown/#+toc.slugify",
"type": "string" "type": "string"
}, },
"toc_depth": { "toc_depth": {
"markdownDescription": "https://squidfunk.github.io/mkdocs-material/setup/extensions/python-markdown/#toc-depth", "markdownDescription": "https://squidfunk.github.io/mkdocs-material/setup/extensions/python-markdown/#+toc.toc_depth",
"type": "number", "type": "number",
"enum": [ "enum": [
0, 0,

82
docs/schema/extensions/pymdownx.json
View File

@ -127,7 +127,7 @@
"type": "object", "type": "object",
"properties": { "properties": {
"mode": { "mode": {
"markdownDescription": "https://squidfunk.github.io/mkdocs-material/setup/extensions/python-markdown-extensions/#critic-mode", "markdownDescription": "https://squidfunk.github.io/mkdocs-material/setup/extensions/python-markdown-extensions/#+pymdownx.critic.mode",
"enum": [ "enum": [
"view", "view",
"accept", "accept",
@ -158,24 +158,24 @@
"type": "object", "type": "object",
"properties": { "properties": {
"emoji_generator": { "emoji_generator": {
"markdownDescription": "https://facelessuser.github.io/pymdown-extensions/extensions/emoji/#options", "markdownDescription": "https://squidfunk.github.io/mkdocs-material/setup/extensions/python-markdown-extensions/#+pymdownx.emoji.emoji_generator",
"type": "string", "type": "string",
"default": "!!python/name:materialx.emoji.to_svg" "default": "!!python/name:materialx.emoji.to_svg"
}, },
"emoji_index": { "emoji_index": {
"markdownDescription": "https://facelessuser.github.io/pymdown-extensions/extensions/emoji/#options", "markdownDescription": "https://squidfunk.github.io/mkdocs-material/setup/extensions/python-markdown-extensions/#+pymdownx.emoji.emoji_index",
"type": "string", "type": "string",
"default": "!!python/name:materialx.emoji.twemoji" "default": "!!python/name:materialx.emoji.twemoji"
}, },
"options": { "options": {
"markdownDescription": "https://squidfunk.github.io/mkdocs-material/setup/extensions/python-markdown-extensions/#custom-icons", "markdownDescription": "https://squidfunk.github.io/mkdocs-material/setup/extensions/python-markdown-extensions/#+pymdownx.emoji.options.custom_icons",
"type": "object", "type": "object",
"properties": { "properties": {
"custom_icons": { "custom_icons": {
"markdownDescription": "https://squidfunk.github.io/mkdocs-material/setup/extensions/python-markdown-extensions/#custom-icons", "markdownDescription": "https://squidfunk.github.io/mkdocs-material/setup/extensions/python-markdown-extensions/#+pymdownx.emoji.options.custom_icons",
"type": "array", "type": "array",
"items": { "items": {
"markdownDescription": "https://squidfunk.github.io/mkdocs-material/setup/extensions/python-markdown-extensions/#custom-icons", "markdownDescription": "https://squidfunk.github.io/mkdocs-material/setup/extensions/python-markdown-extensions/#+pymdownx.emoji.options.custom_icons",
"type": "string" "type": "string"
}, },
"uniqueItems": true, "uniqueItems": true,
@ -212,11 +212,11 @@
"type": "object", "type": "object",
"properties": { "properties": {
"use_pygments": { "use_pygments": {
"markdownDescription": "https://squidfunk.github.io/mkdocs-material/setup/extensions/python-markdown-extensions/#highlight-use-pygments", "markdownDescription": "https://squidfunk.github.io/mkdocs-material/setup/extensions/python-markdown-extensions/#+pymdownx.highlight.use_pygments",
"type": "boolean" "type": "boolean"
}, },
"auto_title": { "auto_title": {
"markdownDescription": "https://squidfunk.github.io/mkdocs-material/setup/extensions/python-markdown-extensions/#highlight-auto-title", "markdownDescription": "https://squidfunk.github.io/mkdocs-material/setup/extensions/python-markdown-extensions/#+pymdownx.highlight.auto_title",
"type": "boolean" "type": "boolean"
}, },
"auto_title_map": { "auto_title_map": {
@ -224,11 +224,11 @@
"type": "object" "type": "object"
}, },
"linenums": { "linenums": {
"markdownDescription": "https://squidfunk.github.io/mkdocs-material/setup/extensions/python-markdown-extensions/#highlight-linenums", "markdownDescription": "https://squidfunk.github.io/mkdocs-material/setup/extensions/python-markdown-extensions/#+pymdownx.highlight.linenums",
"type": "boolean" "type": "boolean"
}, },
"linenums_style": { "linenums_style": {
"markdownDescription": "https://squidfunk.github.io/mkdocs-material/setup/extensions/python-markdown-extensions/#highlight-linenums-style", "markdownDescription": "https://squidfunk.github.io/mkdocs-material/setup/extensions/python-markdown-extensions/#+pymdownx.highlight.linenums_style",
"enum": [ "enum": [
"inline", "inline",
"pymdownx-inline", "pymdownx-inline",
@ -236,7 +236,7 @@
] ]
}, },
"anchor_linenums": { "anchor_linenums": {
"markdownDescription": "https://squidfunk.github.io/mkdocs-material/setup/extensions/python-markdown-extensions/#highlight-anchor-linenums", "markdownDescription": "https://squidfunk.github.io/mkdocs-material/setup/extensions/python-markdown-extensions/#+pymdownx.highlight.anchor_linenums",
"type": "boolean" "type": "boolean"
} }
}, },
@ -359,7 +359,8 @@
"properties": { "properties": {
"smart_mark": { "smart_mark": {
"markdownDescription": "https://facelessuser.github.io/pymdown-extensions/extensions/mark/#options", "markdownDescription": "https://facelessuser.github.io/pymdown-extensions/extensions/mark/#options",
"type": "boolean" "type": "boolean",
"default": true
} }
}, },
"additionalProperties": false "additionalProperties": false
@ -386,45 +387,50 @@
"markdownDescription": "https://squidfunk.github.io/mkdocs-material/setup/extensions/python-markdown-extensions/#smartsymbols", "markdownDescription": "https://squidfunk.github.io/mkdocs-material/setup/extensions/python-markdown-extensions/#smartsymbols",
"type": "object", "type": "object",
"properties": { "properties": {
"smart_mark": {
"markdownDescription": "https://facelessuser.github.io/pymdown-extensions/extensions/mark/#options",
"type": "boolean"
},
"trademark": { "trademark": {
"markdownDescription": "https://facelessuser.github.io/pymdown-extensions/extensions/mark/#options", "markdownDescription": "https://facelessuser.github.io/pymdown-extensions/extensions/smartsymbols/#options",
"type": "boolean" "type": "boolean",
"default": true
}, },
"copyright": { "copyright": {
"markdownDescription": "https://facelessuser.github.io/pymdown-extensions/extensions/mark/#options", "markdownDescription": "https://facelessuser.github.io/pymdown-extensions/extensions/smartsymbols/#options",
"type": "boolean" "type": "boolean",
"default": true
}, },
"registered": { "registered": {
"markdownDescription": "https://facelessuser.github.io/pymdown-extensions/extensions/mark/#options", "markdownDescription": "https://facelessuser.github.io/pymdown-extensions/extensions/smartsymbols/#options",
"type": "boolean" "type": "boolean",
"default": true
}, },
"care_of": { "care_of": {
"markdownDescription": "https://facelessuser.github.io/pymdown-extensions/extensions/mark/#options", "markdownDescription": "https://facelessuser.github.io/pymdown-extensions/extensions/smartsymbols/#options",
"type": "boolean" "type": "boolean",
"default": true
}, },
"plusminus": { "plusminus": {
"markdownDescription": "https://facelessuser.github.io/pymdown-extensions/extensions/mark/#options", "markdownDescription": "https://facelessuser.github.io/pymdown-extensions/extensions/smartsymbols/#options",
"type": "boolean" "type": "boolean",
"default": true
}, },
"arrows": { "arrows": {
"markdownDescription": "https://facelessuser.github.io/pymdown-extensions/extensions/mark/#options", "markdownDescription": "https://facelessuser.github.io/pymdown-extensions/extensions/smartsymbols/#options",
"type": "boolean" "type": "boolean",
"default": true
}, },
"notequal": { "notequal": {
"markdownDescription": "https://facelessuser.github.io/pymdown-extensions/extensions/mark/#options", "markdownDescription": "https://facelessuser.github.io/pymdown-extensions/extensions/smartsymbols/#options",
"type": "boolean" "type": "boolean",
"default": true
}, },
"fractions": { "fractions": {
"markdownDescription": "https://facelessuser.github.io/pymdown-extensions/extensions/mark/#options", "markdownDescription": "https://facelessuser.github.io/pymdown-extensions/extensions/smartsymbols/#options",
"type": "boolean" "type": "boolean",
"default": true
}, },
"ordinal_numbers": { "ordinal_numbers": {
"markdownDescription": "https://facelessuser.github.io/pymdown-extensions/extensions/mark/#options", "markdownDescription": "https://facelessuser.github.io/pymdown-extensions/extensions/smartsymbols/#options",
"type": "boolean" "type": "boolean",
"default": true
} }
}, },
"additionalProperties": false "additionalProperties": false
@ -496,10 +502,10 @@
"type": "object", "type": "object",
"properties": { "properties": {
"custom_fences": { "custom_fences": {
"markdownDescription": "https://squidfunk.github.io/mkdocs-material/setup/extensions/python-markdown-extensions/#superfences-custom-fences", "markdownDescription": "https://squidfunk.github.io/mkdocs-material/setup/extensions/python-markdown-extensions/#+pymdownx.superfences.custom_fences",
"type": "array", "type": "array",
"items": { "items": {
"markdownDescription": "https://squidfunk.github.io/mkdocs-material/setup/extensions/python-markdown-extensions/#superfences-custom-fences", "markdownDescription": "https://squidfunk.github.io/mkdocs-material/setup/extensions/python-markdown-extensions/#+pymdownx.superfences.custom_fences",
"type": "object", "type": "object",
"properties": { "properties": {
"name": { "name": {
@ -561,12 +567,12 @@
"type": "object", "type": "object",
"properties": { "properties": {
"custom_checkbox": { "custom_checkbox": {
"markdownDescription": "https://squidfunk.github.io/mkdocs-material/setup/extensions/python-markdown-extensions/#tasklist-custom-checkbox", "markdownDescription": "https://squidfunk.github.io/mkdocs-material/setup/extensions/python-markdown-extensions/#+pymdownx.tasklist.custom_checkbox",
"type": "boolean", "type": "boolean",
"default": true "default": true
}, },
"clickable_checkbox": { "clickable_checkbox": {
"markdownDescription": "https://squidfunk.github.io/mkdocs-material/setup/extensions/python-markdown-extensions/#tasklist-clickable-checkbox", "markdownDescription": "https://squidfunk.github.io/mkdocs-material/setup/extensions/python-markdown-extensions/#+pymdownx.tasklist.clickable_checkbox",
"type": "boolean" "type": "boolean"
} }
}, },

28
docs/schema/extra.json
View File

@ -72,17 +72,17 @@
}, },
"name": { "name": {
"title": "Feedback rating name", "title": "Feedback rating name",
"markdownDescription": "https://squidfunk.github.io/mkdocs-material/setup/setting-up-site-analytics/#feedback-rating-name", "markdownDescription": "https://squidfunk.github.io/mkdocs-material/setup/setting-up-site-analytics/#+analytics.feedback.ratings.name",
"type": "string" "type": "string"
}, },
"data": { "data": {
"title": "Feedback rating data", "title": "Feedback rating data",
"markdownDescription": "https://squidfunk.github.io/mkdocs-material/setup/setting-up-site-analytics/#feedback-rating-data", "markdownDescription": "https://squidfunk.github.io/mkdocs-material/setup/setting-up-site-analytics/#+analytics.feedback.ratings.data",
"type": "number" "type": "number"
}, },
"note": { "note": {
"title": "Feedback rating data", "title": "Feedback rating data",
"markdownDescription": "https://squidfunk.github.io/mkdocs-material/setup/setting-up-site-analytics/#feedback-rating-note", "markdownDescription": "https://squidfunk.github.io/mkdocs-material/setup/setting-up-site-analytics/#+analytics.feedback.ratings.note",
"type": "string" "type": "string"
} }
}, },
@ -139,18 +139,18 @@
"properties": { "properties": {
"title": { "title": {
"title": "Cookie consent title", "title": "Cookie consent title",
"markdownDescription": "https://squidfunk.github.io/mkdocs-material/setup/ensuring-data-privacy/#cookie-consent", "markdownDescription": "https://squidfunk.github.io/mkdocs-material/setup/ensuring-data-privacy/#+consent.title",
"type": "string", "type": "string",
"default": "Cookie consent" "default": "Cookie consent"
}, },
"description": { "description": {
"title": "Cookie consent description", "title": "Cookie consent description",
"markdownDescription": "https://squidfunk.github.io/mkdocs-material/setup/ensuring-data-privacy/#cookie-consent", "markdownDescription": "https://squidfunk.github.io/mkdocs-material/setup/ensuring-data-privacy/#+consent.description",
"type": "string" "type": "string"
}, },
"cookies": { "cookies": {
"title": "Cookies", "title": "Cookies",
"markdownDescription": "https://squidfunk.github.io/mkdocs-material/setup/ensuring-data-privacy/#cookie-consent", "markdownDescription": "https://squidfunk.github.io/mkdocs-material/setup/ensuring-data-privacy/#+consent.cookies",
"type": "object", "type": "object",
"properties": { "properties": {
"analytics": { "analytics": {
@ -166,7 +166,7 @@
"defaultSnippets": [ "defaultSnippets": [
{ {
"label": "analytics (default)", "label": "analytics (default)",
"markdownDescription": "https://squidfunk.github.io/mkdocs-material/setup/ensuring-data-privacy/#cookie-consent", "markdownDescription": "https://squidfunk.github.io/mkdocs-material/setup/ensuring-data-privacy/#+consent.cookies",
"body": { "body": {
"analytics": { "analytics": {
"name": "Google Analytics", "name": "Google Analytics",
@ -178,7 +178,7 @@
}, },
"actions": { "actions": {
"title": "Cookie consent actions", "title": "Cookie consent actions",
"markdownDescription": "https://squidfunk.github.io/mkdocs-material/setup/ensuring-data-privacy/#cookie-consent", "markdownDescription": "https://squidfunk.github.io/mkdocs-material/setup/ensuring-data-privacy/#+consent.actions",
"type": "array", "type": "array",
"items": { "items": {
"oneOf": [ "oneOf": [
@ -208,7 +208,7 @@
"defaultSnippets": [ "defaultSnippets": [
{ {
"label": "actions (default)", "label": "actions (default)",
"markdownDescription": "https://squidfunk.github.io/mkdocs-material/setup/ensuring-data-privacy/#cookie-consent", "markdownDescription": "https://squidfunk.github.io/mkdocs-material/setup/ensuring-data-privacy/#+consent.actions",
"body": { "body": {
"actions": [ "actions": [
"accept", "accept",
@ -235,12 +235,12 @@
}, },
"link": { "link": {
"title": "Social link", "title": "Social link",
"markdownDescription": "https://squidfunk.github.io/mkdocs-material/setup/setting-up-the-footer/#social-link", "markdownDescription": "https://squidfunk.github.io/mkdocs-material/setup/setting-up-the-footer/#+social.link",
"type": "string" "type": "string"
}, },
"name": { "name": {
"title": "Social link name", "title": "Social link name",
"markdownDescription": "https://squidfunk.github.io/mkdocs-material/setup/setting-up-the-footer/#social-name", "markdownDescription": "https://squidfunk.github.io/mkdocs-material/setup/setting-up-the-footer/#+social.name",
"type": "string" "type": "string"
} }
}, },
@ -262,17 +262,17 @@
"properties": { "properties": {
"name": { "name": {
"title": "Alternate language name", "title": "Alternate language name",
"markdownDescription": "https://squidfunk.github.io/mkdocs-material/setup/changing-the-language/#language-name", "markdownDescription": "https://squidfunk.github.io/mkdocs-material/setup/changing-the-language/#+alternate.name",
"type": "string" "type": "string"
}, },
"link": { "link": {
"title": "Alternate language link", "title": "Alternate language link",
"markdownDescription": "https://squidfunk.github.io/mkdocs-material/setup/changing-the-language/#language-link", "markdownDescription": "https://squidfunk.github.io/mkdocs-material/setup/changing-the-language/#+alternate.link",
"type": "string" "type": "string"
}, },
"lang": { "lang": {
"title": "Alternate language code (ISO 639-1)", "title": "Alternate language code (ISO 639-1)",
"markdownDescription": "https://squidfunk.github.io/mkdocs-material/setup/changing-the-language/#language-lang", "markdownDescription": "https://squidfunk.github.io/mkdocs-material/setup/changing-the-language/#+alternate.lang",
"type": "string" "type": "string"
} }
}, },

3
docs/schema/plugins.json
View File

@ -22,6 +22,9 @@
"built-in": { "built-in": {
"description": "Built-in plugins", "description": "Built-in plugins",
"oneOf": [ "oneOf": [
{
"$ref": "plugins/blog.json"
},
{ {
"$ref": "plugins/meta.json" "$ref": "plugins/meta.json"
}, },

327
docs/schema/plugins/blog.json Normal file
View File

@ -0,0 +1,327 @@
{
"$schema": "https://json-schema.org/draft-07/schema",
"title": "Built-in blog plugin",
"oneOf": [
{
"markdownDescription": "https://squidfunk.github.io/mkdocs-material/setup/setting-up-a-blog/#built-in-blog-plugin",
"enum": [
"blog"
]
},
{
"type": "object",
"properties": {
"blog": {
"markdownDescription": "https://squidfunk.github.io/mkdocs-material/setup/setting-up-a-blog/#built-in-blog-plugin",
"type": "object",
"properties": {
"enabled": {
"title": "Enable plugin",
"markdownDescription": "https://squidfunk.github.io/mkdocs-material/setup/setting-up-a-blog/#+blog.enabled",
"type": "boolean",
"default": true
},
"blog_dir": {
"title": "Blog directory",
"markdownDescription": "https://squidfunk.github.io/mkdocs-material/setup/setting-up-a-blog/#+blog.blog_dir",
"type": "string",
"default": "blog"
},
"blog_custom_dir": {
"title": "Blog template directory (internal)",
"markdownDescription": "Warning: this option is for internal use only, use at your own risk",
"type": "string"
},
"post_date_format": {
"title": "Format string for post dates",
"markdownDescription": "https://squidfunk.github.io/mkdocs-material/setup/setting-up-a-blog/#+blog.post_date_format",
"oneOf": [
{
"enum": [
"full",
"long",
"medium",
"short"
]
},
{
"type": "string"
}
],
"default": "long"
},
"post_url_date_format": {
"title": "Format string for post dates in URLs",
"markdownDescription": "https://squidfunk.github.io/mkdocs-material/setup/setting-up-a-blog/#+blog.post_url_date_format",
"oneOf": [
{
"enum": [
"YYYY",
"YYYY/MM",
"YYYY/MM/dd"
]
},
{
"type": "string"
}
],
"default": "YYYY"
},
"post_url_format": {
"title": "Format string for post URLs",
"markdownDescription": "https://squidfunk.github.io/mkdocs-material/setup/setting-up-a-blog/#+blog.post_url_format",
"oneOf": [
{
"enum": [
"\"{date}/{slug}\"",
"\"{slug}\""
]
},
{
"type": "string"
}
]
},
"post_slugify": {
"title": "Post slugify function",
"markdownDescription": "https://squidfunk.github.io/mkdocs-material/setup/setting-up-a-blog/#+blog.post_slugify",
"type": "string",
"default": "!!python/name:pymdownx.slugs.uslugify"
},
"post_slugify_separator": {
"title": "Post slugify separator",
"markdownDescription": "https://squidfunk.github.io/mkdocs-material/setup/setting-up-a-blog/#+blog.post_slugify_separator",
"type": "string",
"default": "\"-\""
},
"post_excerpt": {
"title": "Post excerpts",
"markdownDescription": "https://squidfunk.github.io/mkdocs-material/setup/setting-up-a-blog/#+blog.post_excerpt",
"oneOf": [
{
"title": "Post excerpts are optional",
"enum": [
"optional"
]
},
{
"title": "Post excerpts are required, thus the build will fail",
"enum": [
"required"
]
}
],
"default": "optional"
},
"post_excerpt_separator": {
"title": "Post excerpt separator",
"markdownDescription": "https://squidfunk.github.io/mkdocs-material/setup/setting-up-a-blog/#+blog.post_excerpt_separator",
"type": "string",
"default": "<!-- more -->"
},
"post_readtime": {
"title": "Post reading time computation",
"markdownDescription": "https://squidfunk.github.io/mkdocs-material/setup/setting-up-a-blog/#+blog.post_readtime",
"type": "boolean",
"default": true
},
"post_readtime_words_per_minute": {
"title": "Post reading time words per minute",
"markdownDescription": "https://squidfunk.github.io/mkdocs-material/setup/setting-up-a-blog/#+blog.post_readtime_words_per_minute",
"type": "number",
"default": 265
},
"archive": {
"title": "Archive",
"markdownDescription": "https://squidfunk.github.io/mkdocs-material/setup/setting-up-a-blog/#+blog.archive",
"type": "boolean",
"default": true
},
"archive_name": {
"title": "Archive name",
"markdownDescription": "https://squidfunk.github.io/mkdocs-material/setup/setting-up-a-blog/#+blog.archive_name",
"type": "string",
"default": "Archive"
},
"archive_date_format": {
"title": "Format string for archive dates",
"markdownDescription": "https://squidfunk.github.io/mkdocs-material/setup/setting-up-a-blog/#+blog.archive_date_format",
"oneOf": [
{
"enum": [
"YYYY",
"MMMM YYYY"
]
},
{
"type": "string"
}
],
"default": "YYYY"
},
"archive_url_date_format": {
"title": "Format string for archive dates in URLs",
"markdownDescription": "https://squidfunk.github.io/mkdocs-material/setup/setting-up-a-blog/#+blog.archive_url_date_format",
"oneOf": [
{
"enum": [
"YYYY",
"YYYY/MM"
]
},
{
"type": "string"
}
],
"default": "YYYY"
},
"archive_url_format": {
"title": "Format string for archive URLs",
"markdownDescription": "https://squidfunk.github.io/mkdocs-material/setup/setting-up-a-blog/#+blog.archive_url_format",
"oneOf": [
{
"enum": [
"\"archive/{date}\""
]
},
{
"type": "string"
}
]
},
"categories": {
"title": "Categories",
"markdownDescription": "https://squidfunk.github.io/mkdocs-material/setup/setting-up-a-blog/#+blog.categories",
"type": "boolean",
"default": true
},
"categories_name": {
"title": "Categories name",
"markdownDescription": "https://squidfunk.github.io/mkdocs-material/setup/setting-up-a-blog/#+blog.categories_name",
"type": "string",
"default": "Categories"
},
"categories_url_format": {
"title": "Format string for category URLs",
"markdownDescription": "https://squidfunk.github.io/mkdocs-material/setup/setting-up-a-blog/#+blog.categories_url_format",
"oneOf": [
{
"enum": [
"\"category/{slug}\"",
"\"{slug}\""
]
},
{
"type": "string"
}
]
},
"categories_slugify": {
"title": "Categories slugify function",
"markdownDescription": "https://squidfunk.github.io/mkdocs-material/setup/setting-up-a-blog/#+blog.categories_slugify",
"type": "string",
"default": "!!python/name:pymdownx.slugs.uslugify"
},
"categories_slugify_separator": {
"title": "Categories slugify separator",
"markdownDescription": "https://squidfunk.github.io/mkdocs-material/setup/setting-up-a-blog/#+blog.categories_slugify_separator",
"type": "string",
"default": "\"-\""
},
"categories_allowed": {
"title": "Categories allowed",
"markdownDescription": "https://squidfunk.github.io/mkdocs-material/setup/setting-up-a-blog/#+blog.categories_allowed",
"type": "array",
"items": {
"type": "string"
},
"default": []
},
"pagination": {
"title": "Pagination",
"markdownDescription": "https://squidfunk.github.io/mkdocs-material/setup/setting-up-a-blog/#+blog.pagination",
"type": "boolean",
"default": true
},
"pagination_per_page": {
"title": "Posts per page",
"markdownDescription": "https://squidfunk.github.io/mkdocs-material/setup/setting-up-a-blog/#+blog.pagination_per_page",
"type": "number",
"default": 10
},
"pagination_url_format": {
"title": "Format string for pagination URLs",
"markdownDescription": "https://squidfunk.github.io/mkdocs-material/setup/setting-up-a-blog/#+blog.pagination_url_format",
"oneOf": [
{
"enum": [
"\"page/{page}\"",
"\"{page}\""
]
},
{
"type": "string"
}
]
},
"pagination_template": {
"title": "Template string for pagination",
"markdownDescription": "https://squidfunk.github.io/mkdocs-material/setup/setting-up-a-blog/#+blog.pagination_template",
"oneOf": [
{
"enum": [
"~2~",
"$link_first $link_previous ~2~ $link_next $link_last",
"$link_previous $page $link_next"
]
},
{
"type": "string"
}
],
"default": "~2~"
},
"authors": {
"title": "Author info",
"markdownDescription": "https://squidfunk.github.io/mkdocs-material/setup/setting-up-a-blog/#+blog.authors",
"type": "boolean",
"default": true
},
"authors_file": {
"title": "Authors file",
"markdownDescription": "https://squidfunk.github.io/mkdocs-material/setup/setting-up-a-blog/#+blog.authors_file",
"type": "string",
"default": ".authors.yml"
},
"authors_in_excerpt": {
"title": "Number of authors to render in post excerpts",
"markdownDescription": "https://squidfunk.github.io/mkdocs-material/setup/setting-up-a-blog/#+blog.authors_in_excerpt",
"type": "number",
"default": 1
},
"draft": {
"title": "Render posts marked as drafts",
"markdownDescription": "https://squidfunk.github.io/mkdocs-material/setup/setting-up-a-blog/#+blog.draft",
"type": "boolean",
"default": false
},
"draft_on_serve": {
"title": "Render posts marked as drafts when previewing",
"markdownDescription": "https://squidfunk.github.io/mkdocs-material/setup/setting-up-a-blog/#+blog.draft_on_serve",
"type": "boolean",
"default": true
},
"draft_if_future_date": {
"title": "Automatically mark posts with future dates as drafts",
"markdownDescription": "https://squidfunk.github.io/mkdocs-material/setup/setting-up-a-blog/#+blog.draft_if_future_date",
"type": "boolean",
"default": false
}
},
"additionalProperties": false
}
},
"additionalProperties": false
}
]
}

4
docs/schema/plugins/external/git-committers.json vendored
View File

@ -23,12 +23,12 @@
}, },
"repository": { "repository": {
"title": "Repository slug", "title": "Repository slug",
"markdownDescription": "https://github.com/ojacques/mkdocs-git-committers-plugin-2#config", "markdownDescription": "https://squidfunk.github.io/mkdocs-material/setup/adding-a-git-repository/#+git-committers.repository",
"type": "string" "type": "string"
}, },
"token": { "token": {
"title": "Personal access token", "title": "Personal access token",
"markdownDescription": "https://github.com/ojacques/mkdocs-git-committers-plugin-2#config", "markdownDescription": "https://squidfunk.github.io/mkdocs-material/setup/adding-a-git-repository/#+git-committers.token",
"type": "string" "type": "string"
} }
}, },

2
docs/schema/plugins/meta.json
View File

@ -17,7 +17,7 @@
"properties": { "properties": {
"meta_file": { "meta_file": {
"title": "Meta file name", "title": "Meta file name",
"markdownDescription": "https://squidfunk.github.io/mkdocs-material/reference/#meta-file", "markdownDescription": "https://squidfunk.github.io/mkdocs-material/reference/#+meta.meta_file",
"pattern": "\\.yml$", "pattern": "\\.yml$",
"default": "\"**/.meta.yml\"" "default": "\"**/.meta.yml\""
} }

2
docs/schema/plugins/offline.json
View File

@ -17,7 +17,7 @@
"properties": { "properties": {
"enabled": { "enabled": {
"title": "Enable plugin", "title": "Enable plugin",
"markdownDescription": "https://squidfunk.github.io/mkdocs-material/setup/building-for-offline-usage/#enabled", "markdownDescription": "https://squidfunk.github.io/mkdocs-material/setup/building-for-offline-usage/#+offline.enabled",
"type": "boolean", "type": "boolean",
"default": true "default": true
} }

10
docs/schema/plugins/privacy.json
View File

@ -17,13 +17,13 @@
"properties": { "properties": {
"enabled": { "enabled": {
"title": "Enable plugin", "title": "Enable plugin",
"markdownDescription": "https://squidfunk.github.io/mkdocs-material/setup/ensuring-data-privacy/#enabled", "markdownDescription": "https://squidfunk.github.io/mkdocs-material/setup/ensuring-data-privacy/#+privacy.enabled",
"type": "boolean", "type": "boolean",
"default": true "default": true
}, },
"externals": { "externals": {
"title": "External assets", "title": "External assets",
"markdownDescription": "https://squidfunk.github.io/mkdocs-material/setup/ensuring-data-privacy/#externals", "markdownDescription": "https://squidfunk.github.io/mkdocs-material/setup/ensuring-data-privacy/#+privacy.externals",
"oneOf": [ "oneOf": [
{ {
"title": "Bundle external assets", "title": "Bundle external assets",
@ -42,17 +42,17 @@
}, },
"externals_dir": { "externals_dir": {
"title": "External assets download directory", "title": "External assets download directory",
"markdownDescription": "https://squidfunk.github.io/mkdocs-material/setup/ensuring-data-privacy/#externals-dir", "markdownDescription": "https://squidfunk.github.io/mkdocs-material/setup/ensuring-data-privacy/#+privacy.externals_dir",
"type": "string", "type": "string",
"default": "assets/externals" "default": "assets/externals"
}, },
"externals_exclude": { "externals_exclude": {
"title": "External assets to be excluded", "title": "External assets to be excluded",
"markdownDescription": "https://squidfunk.github.io/mkdocs-material/setup/ensuring-data-privacy/#externals-exclude", "markdownDescription": "https://squidfunk.github.io/mkdocs-material/setup/ensuring-data-privacy/#+privacy.externals_exclude",
"type": "array", "type": "array",
"items": { "items": {
"title": "External assets matching this pattern will not be bundled", "title": "External assets matching this pattern will not be bundled",
"markdownDescription": "https://squidfunk.github.io/mkdocs-material/setup/ensuring-data-privacy/#externals-exclude", "markdownDescription": "https://squidfunk.github.io/mkdocs-material/setup/ensuring-data-privacy/#+privacy.externals_exclude",
"pattern": ".*" "pattern": ".*"
}, },
"uniqueItems": true, "uniqueItems": true,

8
docs/schema/plugins/search.json
View File

@ -33,17 +33,17 @@
}, },
"separator": { "separator": {
"title": "Separator for indexing and query tokenization", "title": "Separator for indexing and query tokenization",
"markdownDescription": "https://squidfunk.github.io/mkdocs-material/setup/setting-up-site-search/#search-separator", "markdownDescription": "https://squidfunk.github.io/mkdocs-material/setup/setting-up-site-search/#+search.separator",
"type": "string" "type": "string"
}, },
"jieba_dict": { "jieba_dict": {
"title": "Jieba dictionary replacement", "title": "Jieba dictionary replacement",
"markdownDescription": "https://squidfunk.github.io/mkdocs-material/setup/setting-up-site-search/#jieba-dict", "markdownDescription": "https://squidfunk.github.io/mkdocs-material/setup/setting-up-site-search/#+search.jieba_dict",
"type": "string" "type": "string"
}, },
"jieba_dict_user": { "jieba_dict_user": {
"title": "Jieba dictionary augmentation", "title": "Jieba dictionary augmentation",
"markdownDescription": "https://squidfunk.github.io/mkdocs-material/setup/setting-up-site-search/#jieba-dict", "markdownDescription": "https://squidfunk.github.io/mkdocs-material/setup/setting-up-site-search/#+search.jieba_dict_user",
"type": "string" "type": "string"
} }
}, },
@ -56,7 +56,7 @@
"definitions": { "definitions": {
"lang": { "lang": {
"title": "Site search language", "title": "Site search language",
"markdownDescription": "https://squidfunk.github.io/mkdocs-material/setup/setting-up-site-search/#search-lang", "markdownDescription": "https://squidfunk.github.io/mkdocs-material/setup/setting-up-site-search/#+search.lang",
"oneOf": [ "oneOf": [
{ {
"title": "Site search language: Arabic", "title": "Site search language: Arabic",

10
docs/schema/plugins/social.json
View File

@ -17,23 +17,23 @@
"properties": { "properties": {
"cards": { "cards": {
"title": "Social card generation", "title": "Social card generation",
"markdownDescription": "https://squidfunk.github.io/mkdocs-material/setup/setting-up-social-cards/#cards", "markdownDescription": "https://squidfunk.github.io/mkdocs-material/setup/setting-up-social-cards/#+social.cards",
"type": "boolean", "type": "boolean",
"default": true "default": true
}, },
"cards_color": { "cards_color": {
"title": "Social card color palette", "title": "Social card color palette",
"markdownDescription": "https://squidfunk.github.io/mkdocs-material/setup/setting-up-social-cards/#cards-color", "markdownDescription": "https://squidfunk.github.io/mkdocs-material/setup/setting-up-social-cards/#+social.cards_color",
"type": "object", "type": "object",
"properties": { "properties": {
"fill": { "fill": {
"title": "Background fill color", "title": "Background fill color",
"markdownDescription": "https://squidfunk.github.io/mkdocs-material/setup/setting-up-social-cards/#cards-color", "markdownDescription": "https://squidfunk.github.io/mkdocs-material/setup/setting-up-social-cards/#+social.cards_color",
"type": "string" "type": "string"
}, },
"text": { "text": {
"title": "Foreground text color", "title": "Foreground text color",
"markdownDescription": "https://squidfunk.github.io/mkdocs-material/setup/setting-up-social-cards/#cards-color", "markdownDescription": "https://squidfunk.github.io/mkdocs-material/setup/setting-up-social-cards/#+social.cards_color",
"type": "string" "type": "string"
} }
}, },
@ -48,7 +48,7 @@
}, },
"cards_dir": { "cards_dir": {
"title": "Social card directory", "title": "Social card directory",
"markdownDescription": "https://squidfunk.github.io/mkdocs-material/setup/setting-up-social-cards/#cards-dir", "markdownDescription": "https://squidfunk.github.io/mkdocs-material/setup/setting-up-social-cards/#+social.cards_dir",
"type": "string", "type": "string",
"default": "assets/images/social" "default": "assets/images/social"
} }

4
docs/schema/plugins/tags.json
View File

@ -17,13 +17,13 @@
"properties": { "properties": {
"tags_file": { "tags_file": {
"title": "Markdown file to render tags index", "title": "Markdown file to render tags index",
"markdownDescription": "https://squidfunk.github.io/mkdocs-material/setup/setting-up-tags/#tags-file", "markdownDescription": "https://squidfunk.github.io/mkdocs-material/setup/setting-up-tags/#+tags.tags_file",
"pattern": "\\.md$", "pattern": "\\.md$",
"default": "tags.md" "default": "tags.md"
}, },
"tags_extra_files": { "tags_extra_files": {
"title": "Markdown files to render additional tags indexes", "title": "Markdown files to render additional tags indexes",
"markdownDescription": "https://squidfunk.github.io/mkdocs-material/setup/setting-up-tags/#tags-extra-files", "markdownDescription": "https://squidfunk.github.io/mkdocs-material/setup/setting-up-tags/#+tags.tags_extra_files",
"type": "object", "type": "object",
"patternProperties": { "patternProperties": {
"\\.md$": { "\\.md$": {

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

@ -42,24 +42,14 @@ Before you can use [Giscus], you need to complete the following steps:
</script> </script>
``` ```
You can either integrate [Giscus] on every page by overriding the `main.html` The by default empty [`comments.html`][comments] partial is the best place to
template, or create a new template (e.g. `blog.html`) to extend from `main.html` add the code snippet generated by [Giscus]. Follow the guide on [theme extension]
which includes the comment system, so you can decide for each page whether you and [override the `comments.html` partial][overriding partials] with:
want to allow comments or not.
In order to integrate [Giscus], follow the guide on [theme extension] and ``` html hl_lines="3"
[override the `content` block][overriding blocks], extending the default by {% if page.meta.comments %}
calling the `super()` function at the beginning of the block:
``` html hl_lines="8"
{% extends "base.html" %}
{% block content %}
{{ super() }}
<!-- Giscus -->
<h2 id="__comments">{{ lang.t("meta.comments") }}</h2> <h2 id="__comments">{{ lang.t("meta.comments") }}</h2>
<!-- Replace with generated snippet --> <!-- Insert generated code here -->
<!-- Synchronize Giscus theme with palette --> <!-- Synchronize Giscus theme with palette -->
<script> <script>
@ -90,7 +80,7 @@ calling the `super()` function at the beginning of the block:
}) })
}) })
</script> </script>
{% endblock %} {% endif %}
``` ```
1. This code block ensures that [Giscus] renders with a dark theme when the 1. This code block ensures that [Giscus] renders with a dark theme when the
@ -98,12 +88,24 @@ calling the `super()` function at the beginning of the block:
so you can change it to your liking. so you can change it to your liking.
Replace the highlighted line with the snippet you generated with the [Giscus] Replace the highlighted line with the snippet you generated with the [Giscus]
configuration tool in the previous step. If you extended `main.html`, you should configuration tool in the previous step. If you copied the snippet from above,
now see the [Giscus] comment system at the bottom of each page. If you created you can enable comments on a page by setting the `comments` front matter
a new, separate template, you can enable Giscus by [setting the page template] property to `true`:
via front matter.
``` yaml
---
comments: true
---
# Document title
...
```
If you wish to enable comments for an entire folder, you can use the
[built-in meta plugin].
[Giscus GitHub App]: https://github.com/apps/giscus [Giscus GitHub App]: https://github.com/apps/giscus
[theme extension]: ../customization.md#extending-the-theme [theme extension]: ../customization.md#extending-the-theme
[overriding blocks]: ../customization.md#overriding-blocks [comments]: https://github.com/squidfunk/mkdocs-material/blob/master/src/partials/comments.html
[setting the page template]: ../reference/index.md#setting-the-page-template [overriding partials]: ../customization.md#overriding-partials
[built-in meta plugin]: ../reference/index.md#built-in-meta-plugin

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

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

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

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

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

@ -18,7 +18,7 @@ fit your brand's identity by using [CSS variables][custom colors].
#### Color scheme #### Color scheme
[:octicons-tag-24: 5.2.0][palette.scheme support] · [:octicons-tag-24: 5.2.0][Color scheme support] ·
:octicons-milestone-24: Default: `default` :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
@ -50,11 +50,11 @@ Click on a tile to change the color scheme:
}) })
</script> </script>
[palette.scheme support]: https://github.com/squidfunk/mkdocs-material/releases/tag/5.2.0 [Color scheme support]: https://github.com/squidfunk/mkdocs-material/releases/tag/5.2.0
#### Primary color #### Primary color
[:octicons-tag-24: 0.2.0][palette.primary support] · [:octicons-tag-24: 0.2.0][Primary color support] ·
:octicons-milestone-24: Default: `indigo` :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
@ -105,11 +105,11 @@ Click on a tile to change the primary color:
}) })
</script> </script>
[palette.primary support]: https://github.com/squidfunk/mkdocs-material/releases/tag/0.2.0 [Primary color support]: https://github.com/squidfunk/mkdocs-material/releases/tag/0.2.0
#### Accent color #### Accent color
[:octicons-tag-24: 0.2.0][palette.accent support] · [:octicons-tag-24: 0.2.0][Accent color support] ·
:octicons-milestone-24: Default: `indigo` :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.
@ -162,11 +162,11 @@ Click on a tile to change the accent color:
}) })
</script> </script>
[palette.accent support]: https://github.com/squidfunk/mkdocs-material/releases/tag/0.2.0 [Accent color support]: https://github.com/squidfunk/mkdocs-material/releases/tag/0.2.0
### Color palette toggle ### Color palette toggle
[:octicons-tag-24: 7.1.0][palette.toggle support] · [:octicons-tag-24: 7.1.0][Color palette toggle support] ·
:octicons-milestone-24: Default: _none_ :octicons-milestone-24: Default: _none_
Offering a light _and_ dark color palette makes your documentation pleasant to Offering a light _and_ dark color palette makes your documentation pleasant to
@ -209,9 +209,9 @@ and [`accent`][palette.accent] per color palette.
The following properties must be set for each toggle: The following properties must be set for each toggle:
`icon`{ #toggle-icon } [`icon`](#+palette.toggle.icon){ #+palette.toggle.icon }
: :octicons-milestone-24: Default: _none_ · :octicons-alert-24: Required – : :octicons-milestone-24: Default: _none_ · :octicons-alert-24: __Required__ –
This property must point to a valid icon path referencing any icon bundled This property must point to a valid icon path referencing any icon bundled
with the theme, or the build will not succeed. Some popular combinations: with the theme, or the build will not succeed. Some popular combinations:
@ -221,13 +221,13 @@ The following properties must be set for each toggle:
* :material-eye: + :material-eye-outline: – `material/eye` + `material/eye-outline` * :material-eye: + :material-eye-outline: – `material/eye` + `material/eye-outline`
* :material-lightbulb: + :material-lightbulb-outline: – `material/lightbulb` + `material/lightbulb-outline` * :material-lightbulb: + :material-lightbulb-outline: – `material/lightbulb` + `material/lightbulb-outline`
`name`{ #toggle-name } [`name`](#+palette.toggle.name){ #+palette.toggle.name }
: :octicons-milestone-24: Default: _none_ · :octicons-alert-24: Required – : :octicons-milestone-24: Default: _none_ · :octicons-alert-24: __Required__ –
This property is used as the toggle's `title` attribute and should be set to This property is used as the toggle's `title` attribute and should be set to
a discernable name to improve accessibility. It's rendered as a [tooltip]. a discernable name to improve accessibility. It's rendered as a [tooltip].
[palette.toggle support]: https://github.com/squidfunk/mkdocs-material/releases/tag/7.1.0 [Color palette toggle support]: https://github.com/squidfunk/mkdocs-material/releases/tag/7.1.0
[palette.scheme]: #color-scheme [palette.scheme]: #color-scheme
[palette.primary]: #primary-color [palette.primary]: #primary-color
[palette.accent]: #accent-color [palette.accent]: #accent-color
@ -236,7 +236,7 @@ The following properties must be set for each toggle:
### System preference ### System preference
[:octicons-tag-24: 7.1.0][palette.media support] · [:octicons-tag-24: 7.1.0][System preference support] ·
:octicons-milestone-24: Default: _none_ :octicons-milestone-24: Default: _none_
Each color palette can be linked to the user's system preference for light and Each color palette can be linked to the user's system preference for light and
@ -266,7 +266,7 @@ When the user first visits your site, the media queries are evaluated in the
order of their definition. The first media query that matches selects the order of their definition. The first media query that matches selects the
default color palette. default color palette.
[palette.media support]: https://github.com/squidfunk/mkdocs-material/releases/tag/7.1.0 [System preference support]: https://github.com/squidfunk/mkdocs-material/releases/tag/7.1.0
#### Automatic light / dark mode #### Automatic light / dark mode
@ -327,7 +327,7 @@ Let's say you're :fontawesome-brands-youtube:{ style="color: #EE0F0F" }
__YouTube__, and want to set the primary color to your brand's palette. Just __YouTube__, and want to set the primary color to your brand's palette. Just
add: add:
=== ":octicons-file-code-16: docs/stylesheets/extra.css" === ":octicons-file-code-16: `docs/stylesheets/extra.css`"
``` css ``` css
:root > * { :root > * {
@ -337,7 +337,7 @@ add:
} }
``` ```
=== ":octicons-file-code-16: mkdocs.yml" === ":octicons-file-code-16: `mkdocs.yml`"
``` yaml ``` yaml
extra_css: extra_css:
@ -358,7 +358,7 @@ by wrapping the definitions in a `[data-md-color-scheme="..."]`
[attribute selector], which you can then set via `mkdocs.yml` as described [attribute selector], which you can then set via `mkdocs.yml` as described
in the [color schemes][palette.scheme] section: in the [color schemes][palette.scheme] section:
=== ":octicons-file-code-16: docs/stylesheets/extra.css" === ":octicons-file-code-16: `docs/stylesheets/extra.css`"
``` css ``` css
[data-md-color-scheme="youtube"] { [data-md-color-scheme="youtube"] {
@ -368,7 +368,7 @@ in the [color schemes][palette.scheme] section:
} }
``` ```
=== ":octicons-file-code-16: mkdocs.yml" === ":octicons-file-code-16: `mkdocs.yml`"
``` yaml ``` yaml
theme: theme:

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

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

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

@ -13,7 +13,7 @@ available.
### Site language ### Site language
[:octicons-tag-24: 1.12.0][language support] · [:octicons-tag-24: 1.12.0][Site language support] ·
:octicons-milestone-24: Default: `en` :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:
@ -100,7 +100,7 @@ The following languages are supported:
Note that some languages will produce unreadable anchor links due to the way 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]. the default slug function works. Consider using a [Unicode-aware slug function].
[language support]: https://github.com/squidfunk/mkdocs-material/releases/tag/1.12.0 [Site language support]: https://github.com/squidfunk/mkdocs-material/releases/tag/1.12.0
[single language per document]: https://www.w3.org/International/questions/qa-html-language-declarations.en#attributes [single language per document]: https://www.w3.org/International/questions/qa-html-language-declarations.en#attributes
[language selector]: #site-language-selector [language selector]: #site-language-selector
[Unicode-aware slug function]: extensions/python-markdown.md#toc-slugify [Unicode-aware slug function]: extensions/python-markdown.md#toc-slugify
@ -108,7 +108,7 @@ the default slug function works. Consider using a [Unicode-aware slug function].
### Site language selector ### Site language selector
[:octicons-tag-24: 7.0.0][alternate support] · [:octicons-tag-24: 7.0.0][Site language selector support] ·
:octicons-milestone-24: Default: _none_ · :octicons-milestone-24: Default: _none_ ·
:octicons-beaker-24: Experimental :octicons-beaker-24: Experimental
@ -133,35 +133,35 @@ extra:
The following properties are available for each alternate language: The following properties are available for each alternate language:
`name`{ #language-name } [`name`](#+alternate.name){ #+alternate.name }
: :octicons-milestone-24: Default: _none_ · :octicons-alert-24: Required – : :octicons-milestone-24: Default: _none_ · :octicons-alert-24: __Required__ –
This value of this property is used inside the language selector as the This value of this property is used inside the language selector as the
name of the language and must be set to a non-empty string. name of the language and must be set to a non-empty string.
`link`{ #language-link } [`link`](#+alternate.link){ #+alternate.link }
: :octicons-milestone-24: Default: _none_ · :octicons-alert-24: Required – : :octicons-milestone-24: Default: _none_ · :octicons-alert-24: __Required__ –
This property must be set to an absolute link, which might also point to This property must be set to an absolute link, which might also point to
another domain or subdomain not necessarily generated with MkDocs. another domain or subdomain not necessarily generated with MkDocs.
`lang`{ #language-lang } [`lang`](#+alternate.lang){ #+alternate.lang }
: :octicons-milestone-24: Default: _none_ · :octicons-alert-24: Required – : :octicons-milestone-24: Default: _none_ · :octicons-alert-24: __Required__ –
This property must contain an [ISO 639-1 language code] and is used for This property must contain an [ISO 639-1 language code] and is used for
the `hreflang` attribute of the link, improving discoverability via search the `hreflang` attribute of the link, improving discoverability via search
engines. engines.
[![Language selector preview]][Language selector preview] [![Language selector preview]][Language selector preview]
[alternate support]: https://github.com/squidfunk/mkdocs-material/releases/tag/7.0.0 [Site language selector support]: https://github.com/squidfunk/mkdocs-material/releases/tag/7.0.0
[site_url]: https://www.mkdocs.org/user-guide/configuration/#site_url [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 [ISO 639-1 language code]: https://en.wikipedia.org/wiki/List_of_ISO_639-1_codes
[Language selector preview]: ../assets/screenshots/language-selection.png [Language selector preview]: ../assets/screenshots/language-selection.png
### Directionality ### Directionality
[:octicons-tag-24: 2.5.0][direction support] · [:octicons-tag-24: 2.5.0][Directionality support] ·
:octicons-milestone-24: Default: _automatically set_ :octicons-milestone-24: Default: _automatically set_
While many languages are read `ltr` (left-to-right), Material for MkDocs also While many languages are read `ltr` (left-to-right), Material for MkDocs also
@ -192,7 +192,7 @@ Click on a tile to change the directionality:
}) })
</script> </script>
[direction support]: https://github.com/squidfunk/mkdocs-material/releases/tag/2.5.0 [Directionality support]: https://github.com/squidfunk/mkdocs-material/releases/tag/2.5.0
## Customization ## Customization
@ -203,7 +203,7 @@ the guide on [theme extension] and create a new partial in the `overrides`
folder. Then, import the [translations] of the language as a fallback and only folder. Then, import the [translations] of the language as a fallback and only
adjust the ones you want to override: adjust the ones you want to override:
=== ":octicons-file-code-16: overrides/partials/languages/custom.html" === ":octicons-file-code-16: `overrides/partials/languages/custom.html`"
``` html ``` html
<!-- Import translations for language and fallback --> <!-- Import translations for language and fallback -->
@ -228,7 +228,7 @@ adjust the ones you want to override:
2. Check the [list of available languages], pick the translation you want 2. Check the [list of available languages], pick the translation you want
to override for your language and add them here. to override for your language and add them here.
=== ":octicons-file-code-16: mkdocs.yml" === ":octicons-file-code-16: `mkdocs.yml`"
``` yaml ``` yaml
theme: theme:

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

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

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

@ -9,15 +9,15 @@ as it offers a native [cookie consent] solution to seek explicit consent from
users before setting up [tracking]. Additionally, external assets can be users before setting up [tracking]. Additionally, external assets can be
automatically downloaded for [self-hosting]. automatically downloaded for [self-hosting].
[cookie consent]: #native-cookie-consent [cookie consent]: #cookie-consent
[tracking]: setting-up-site-analytics.md [tracking]: setting-up-site-analytics.md
[self-hosting]: #built-in-privacy-plugin [self-hosting]: #built-in-privacy-plugin
## Configuration ## Configuration
### Cookie consent { #native-cookie-consent } ### Cookie consent { #cookie-consent }
[:octicons-tag-24: 8.4.0][cookie consent support] · [:octicons-tag-24: 8.4.0][Cookie consent support] ·
:octicons-milestone-24: Default: _none_ · :octicons-milestone-24: Default: _none_ ·
:octicons-beaker-24: Experimental :octicons-beaker-24: Experimental
@ -41,19 +41,19 @@ extra:
The following properties are available: The following properties are available:
`title`{ #consent-title } [`title`](#+consent.title){ #+consent.title }
: :octicons-milestone-24: Default: _none_ · :octicons-alert-24: Required – : :octicons-milestone-24: Default: _none_ · :octicons-alert-24: __Required__ –
This property sets the title of the cookie consent, which is rendered at the This property sets the title of the cookie consent, which is rendered at the
top of the form and must be set to a non-empty string. top of the form and must be set to a non-empty string.
`description`{ #consent-description } [`description`](#+consent.description){ #+consent.description }
: :octicons-milestone-24: Default: _none_ · :octicons-alert-24: Required – : :octicons-milestone-24: Default: _none_ · :octicons-alert-24: __Required__ –
This property sets the description of the cookie consent, is rendered below This property sets the description of the cookie consent, is rendered below
the title, and may include raw HTML (e.g. a links to the terms of service). the title, and may include raw HTML (e.g. a links to the terms of service).
`cookies`{ #consent-cookies } [`cookies`](#+consent.cookies){ #+consent.cookies }
: :octicons-milestone-24: Default: _none_ – This property allows to add custom : :octicons-milestone-24: Default: _none_ – This property allows to add custom
cookies or change the initial `checked` state and name of the `analytics` cookies or change the initial `checked` state and name of the `analytics`
@ -99,7 +99,7 @@ The following properties are available:
If Google Analytics was configured via `mkdocs.yml`, the cookie consent will automatically include a setting for the user to disable it. [Custom cookies] If Google Analytics was configured via `mkdocs.yml`, the cookie consent will automatically include a setting for the user to disable it. [Custom cookies]
can be used from JavaScript. can be used from JavaScript.
`actions`{ #consent-actions } [`actions`](#+consent.actions){ #+consent.actions }
: :octicons-milestone-24: Default: `[accept, manage]` – This property defines : :octicons-milestone-24: Default: `[accept, manage]` – This property defines
which buttons are shown and in which order, e.g. to allow the user to accept which buttons are shown and in which order, e.g. to allow the user to accept
@ -121,11 +121,11 @@ The following properties are available:
When a user first visits your site, a cookie consent form is rendered: When a user first visits your site, a cookie consent form is rendered:
[![cookie consent enabled]][cookie consent enabled] [![Cookie consent enabled]][Cookie consent enabled]
[Custom cookies]: #custom-cookies [Custom cookies]: #custom-cookies
[cookie consent support]: https://github.com/squidfunk/mkdocs-material/releases/tag/8.4.0 [Cookie consent support]: https://github.com/squidfunk/mkdocs-material/releases/tag/8.4.0
[cookie consent enabled]: ../assets/screenshots/consent.png [Cookie consent enabled]: ../assets/screenshots/consent.png
#### Change cookie settings #### Change cookie settings
@ -168,7 +168,7 @@ plugins:
The following configuration options are available: The following configuration options are available:
`enabled`{ #enabled } [`enabled`](#+privacy.enabled){ #+privacy.enabled }
: :octicons-milestone-24: Default: `true` – This option specifies whether : :octicons-milestone-24: Default: `true` – This option specifies whether
the plugin is enabled when building your project. If you want to switch the plugin is enabled when building your project. If you want to switch
@ -180,7 +180,7 @@ The following configuration options are available:
enabled: !ENV [PRIVACY, false] enabled: !ENV [PRIVACY, false]
``` ```
`externals`{ #externals } [`externals`](#+privacy.externals){ #+privacy.externals }
: :octicons-milestone-24: Default: `bundle` – This option specifies what the : :octicons-milestone-24: Default: `bundle` – This option specifies what the
plugin should do when encountering external assets. There are two options: plugin should do when encountering external assets. There are two options:
@ -204,7 +204,7 @@ The following configuration options are available:
[customization]: ../customization.md [customization]: ../customization.md
[strict mode]: https://www.mkdocs.org/user-guide/configuration/#strict [strict mode]: https://www.mkdocs.org/user-guide/configuration/#strict
`externals_dir`{ #externals-dir } [`externals_dir`](#+privacy.externals_dir){ #+privacy.externals_dir }
: :octicons-milestone-24: Default: `assets/externals` – This option : :octicons-milestone-24: Default: `assets/externals` – This option
specifies where the downloaded [external assets] will be stored. It's specifies where the downloaded [external assets] will be stored. It's
@ -216,7 +216,7 @@ The following configuration options are available:
externals_dir: assets/externals externals_dir: assets/externals
``` ```
`externals_exclude`{ #externals-exclude } [`externals_exclude`](#+privacy.externals_exclude){ #+privacy.externals_exclude }
: :octicons-milestone-24: Default: _none_ – This option allows to exclude : :octicons-milestone-24: Default: _none_ – This option allows to exclude
certain external assets from processing by the privacy plugin, so they will certain external assets from processing by the privacy plugin, so they will
@ -440,7 +440,7 @@ If you've customized the [cookie consent] and added a `custom` cookie, the user
will be prompted to accept your custom cookie. Use [additional JavaScript] to will be prompted to accept your custom cookie. Use [additional JavaScript] to
check whether the user accepted it: check whether the user accepted it:
=== ":octicons-file-code-16: docs/javascripts/consent.js" === ":octicons-file-code-16: `docs/javascripts/consent.js`"
``` js ``` js
var consent = __md_get("__consent") var consent = __md_get("__consent")
@ -449,7 +449,7 @@ check whether the user accepted it:
} }
``` ```
=== ":octicons-file-code-16: mkdocs.yml" === ":octicons-file-code-16: `mkdocs.yml`"
``` yaml ``` yaml
extra_javascript: extra_javascript:

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

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

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

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

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

File diff suppressed because it is too large Load Diff

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

@ -6,19 +6,18 @@ template: overrides/main.html
A clear and concise navigation structure is an important aspect of good project A clear and concise navigation structure is an important aspect of good project
documentation. Material for MkDocs provides a multitude of options to configure documentation. Material for MkDocs provides a multitude of options to configure
the behavior of navigational elements, including [tabs][navigation.tabs] and the behavior of navigational elements, including [tabs] and [sections], and one
[sections][navigation.sections], and its flag-ship feature: [instant loading] of its flag-ship feature: [instant loading].
[navigation.instant].
[navigation.tabs]: #navigation-tabs [tabs]: #navigation-tabs
[navigation.sections]: #navigation-sections [sections]: #navigation-sections
[navigation.instant]: #instant-loading [instant loading]: #instant-loading
## Configuration ## Configuration
### Instant loading ### Instant loading
[:octicons-tag-24: 5.0.0][navigation.instant support] · [:octicons-tag-24: 5.0.0][Instant loading support] ·
:octicons-unlock-24: Feature flag :octicons-unlock-24: Feature flag
When instant loading is enabled, clicks on all internal links will be When instant loading is enabled, clicks on all internal links will be
@ -36,7 +35,7 @@ are rebound automatically, i.e., __Material for MkDocs now behaves like a Single
Page Application__. Now, the search index survives navigation, which is Page Application__. Now, the search index survives navigation, which is
especially useful for large documentation sites. especially useful for large documentation sites.
[navigation.instant support]: https://github.com/squidfunk/mkdocs-material/releases/tag/5.2.0 [Instant loading support]: https://github.com/squidfunk/mkdocs-material/releases/tag/5.2.0
[XHR]: https://developer.mozilla.org/en-US/docs/Web/API/XMLHttpRequest [XHR]: https://developer.mozilla.org/en-US/docs/Web/API/XMLHttpRequest
### Anchor tracking ### Anchor tracking
@ -59,7 +58,7 @@ theme:
### Navigation tabs ### Navigation tabs
[:octicons-tag-24: 1.1.0][navigation.tabs support] · [:octicons-tag-24: 1.1.0][Navigation tabs support] ·
:octicons-unlock-24: Feature flag :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
@ -81,21 +80,21 @@ theme:
- navigation.tabs - navigation.tabs
``` ```
=== ":octicons-check-circle-fill-16: Enabled" === "With tabs"
[![navigation.tabs enabled]][navigation.tabs enabled] [![Navigation tabs enabled]][Navigation tabs enabled]
=== ":octicons-skip-16: Disabled" === "Without"
[![navigation.tabs disabled]][navigation.tabs disabled] [![Navigation tabs disabled]][Navigation tabs disabled]
[navigation.tabs support]: https://github.com/squidfunk/mkdocs-material/releases/tag/1.1.0 [Navigation tabs support]: https://github.com/squidfunk/mkdocs-material/releases/tag/1.1.0
[navigation.tabs enabled]: ../assets/screenshots/navigation-tabs.png [Navigation tabs enabled]: ../assets/screenshots/navigation-tabs.png
[navigation.tabs disabled]: ../assets/screenshots/navigation.png [Navigation tabs disabled]: ../assets/screenshots/navigation.png
#### Sticky navigation tabs #### Sticky navigation tabs
[:octicons-tag-24: 7.3.0][navigation.tabs.sticky support] · [:octicons-tag-24: 7.3.0][Sticky navigation tabs support] ·
:octicons-unlock-24: Feature flag :octicons-unlock-24: Feature flag
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
@ -109,21 +108,21 @@ theme:
- navigation.tabs.sticky - navigation.tabs.sticky
``` ```
=== ":octicons-check-circle-fill-16: Enabled" === "With sticky tabs"
[![navigation.tabs.sticky enabled]][navigation.tabs.sticky enabled] [![Sticky navigation tabs enabled]][Sticky navigation tabs enabled]
=== ":octicons-skip-16: Disabled" === "Without"
[![navigation.tabs.sticky disabled]][navigation.tabs.sticky disabled] [![Sticky navigation tabs disabled]][Sticky navigation tabs disabled]
[navigation.tabs.sticky support]: https://github.com/squidfunk/mkdocs-material/releases/tag/7.3.0 [Sticky navigation tabs support]: https://github.com/squidfunk/mkdocs-material/releases/tag/7.3.0
[navigation.tabs.sticky enabled]: ../assets/screenshots/navigation-tabs-sticky.png [Sticky navigation tabs enabled]: ../assets/screenshots/navigation-tabs-sticky.png
[navigation.tabs.sticky disabled]: ../assets/screenshots/navigation-tabs-collapsed.png [Sticky navigation tabs disabled]: ../assets/screenshots/navigation-tabs-collapsed.png
### Navigation sections ### Navigation sections
[:octicons-tag-24: 6.2.0][navigation.sections support] · [:octicons-tag-24: 6.2.0][Navigation sections support] ·
:octicons-unlock-24: Feature flag :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
@ -136,26 +135,25 @@ theme:
- navigation.sections - navigation.sections
``` ```
=== ":octicons-check-circle-fill-16: Enabled" === "With sections"
[![navigation.sections enabled]][navigation.sections enabled] [![Navigation sections enabled]][Navigation sections enabled]
=== ":octicons-skip-16: Disabled" === "Without"
[![navigation.sections disabled]][navigation.sections disabled] [![Navigation sections disabled]][Navigation sections disabled]
[navigation.sections support]: https://github.com/squidfunk/mkdocs-material/releases/tag/6.2.0 [Navigation sections support]: https://github.com/squidfunk/mkdocs-material/releases/tag/6.2.0
[navigation.sections enabled]: ../assets/screenshots/navigation-sections.png [Navigation sections enabled]: ../assets/screenshots/navigation-sections.png
[navigation.sections disabled]: ../assets/screenshots/navigation.png [Navigation sections disabled]: ../assets/screenshots/navigation.png
Both feature flags, [`navigation.tabs`][navigation.tabs] and Both feature flags, [`navigation.tabs`][tabs] and
[`navigation.sections`][navigation.sections], can be combined with each other. [`navigation.sections`][sections], can be combined with each other. If both
If both feature flags are enabled, sections are rendered for level 2 navigation feature flags are enabled, sections are rendered for level 2 navigation items.
items.
### Navigation expansion ### Navigation expansion
[:octicons-tag-24: 6.2.0][navigation.expand support] · [:octicons-tag-24: 6.2.0][Navigation expansion support] ·
:octicons-unlock-24: Feature flag :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
@ -168,17 +166,17 @@ theme:
- navigation.expand - navigation.expand
``` ```
=== ":octicons-check-circle-fill-16: Enabled" === "With expansion"
[![navigation.expand enabled]][navigation.expand enabled] [![Navigation expansion enabled]][Navigation expansion enabled]
=== ":octicons-skip-16: Disabled" === "Without"
[![navigation.expand disabled]][navigation.expand disabled] [![Navigation expansion disabled]][Navigation expansion disabled]
[navigation.expand support]: https://github.com/squidfunk/mkdocs-material/releases/tag/6.2.0 [Navigation expansion support]: https://github.com/squidfunk/mkdocs-material/releases/tag/6.2.0
[navigation.expand enabled]: ../assets/screenshots/navigation-expand.png [Navigation expansion enabled]: ../assets/screenshots/navigation-expand.png
[navigation.expand disabled]: ../assets/screenshots/navigation.png [Navigation expansion disabled]: ../assets/screenshots/navigation.png
### Navigation pruning ### Navigation pruning
@ -209,7 +207,7 @@ page in that section (or the section index page).
### Section index pages ### Section index pages
[:octicons-tag-24: 7.3.0][navigation.indexes support] · [:octicons-tag-24: 7.3.0][Section index pages support] ·
:octicons-unlock-24: Feature flag :octicons-unlock-24: Feature flag
When section index pages are enabled, documents can be directly attached to When section index pages are enabled, documents can be directly attached to
@ -225,13 +223,13 @@ theme:
1. This feature flag is not compatible with [`toc.integrate`][toc.integrate], 1. This feature flag is not compatible with [`toc.integrate`][toc.integrate],
as sections cannot host the table of contents due to missing space. as sections cannot host the table of contents due to missing space.
=== ":octicons-check-circle-fill-16: Enabled" === "With section index pages"
[![navigation.indexes enabled]][navigation.indexes enabled] [![Section index pages enabled]][Section index pages enabled]
=== ":octicons-skip-16: Disabled" === "Without"
[![navigation.indexes disabled]][navigation.indexes disabled] [![Section index pages disabled]][Section index pages disabled]
In order to link a page to a section, create a new document with the name 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 `index.md` in the respective folder, and add it to the beginning of your
@ -246,9 +244,9 @@ nav:
- Page n: section/page-n.md - Page n: section/page-n.md
``` ```
[navigation.indexes support]: https://github.com/squidfunk/mkdocs-material/releases/tag/7.3.0 [Section index pages support]: https://github.com/squidfunk/mkdocs-material/releases/tag/7.3.0
[navigation.indexes enabled]: ../assets/screenshots/navigation-index-on.png [Section index pages enabled]: ../assets/screenshots/navigation-index-on.png
[navigation.indexes disabled]: ../assets/screenshots/navigation-index-off.png [Section index pages disabled]: ../assets/screenshots/navigation-index-off.png
[toc.integrate]: #navigation-integration [toc.integrate]: #navigation-integration
### Table of contents ### Table of contents
@ -273,7 +271,7 @@ theme:
#### Navigation integration #### Navigation integration
[:octicons-tag-24: 6.2.0][toc.integrate support] · [:octicons-tag-24: 6.2.0][Navigation integration support] ·
:octicons-unlock-24: Feature flag :octicons-unlock-24: Feature flag
When navigation integration for the [table of contents] is enabled, it is always When navigation integration for the [table of contents] is enabled, it is always
@ -290,23 +288,23 @@ theme:
[`navigation.indexes`][navigation.indexes], as sections cannot host the [`navigation.indexes`][navigation.indexes], as sections cannot host the
table of contents due to missing space. table of contents due to missing space.
=== ":octicons-check-circle-fill-16: Enabled" === "With navigation integration"
[![toc.integrate enabled]][toc.integrate enabled] [![Navigation integration enabled]][Navigation integration enabled]
=== ":octicons-skip-16: Disabled" === "Without"
[![toc.integrate disabled]][toc.integrate disabled] [![Navigation integration disabled]][Navigation integration disabled]
[table of contents]: extensions/python-markdown.md#table-of-contents [table of contents]: extensions/python-markdown.md#table-of-contents
[toc.integrate support]: https://github.com/squidfunk/mkdocs-material/releases/tag/7.3.0 [Navigation integration support]: https://github.com/squidfunk/mkdocs-material/releases/tag/7.3.0
[toc.integrate enabled]: ../assets/screenshots/toc-integrate.png [Navigation integration enabled]: ../assets/screenshots/toc-integrate.png
[toc.integrate disabled]: ../assets/screenshots/navigation-tabs.png [Navigation integration disabled]: ../assets/screenshots/navigation-tabs.png
[navigation.indexes]: #section-index-pages [navigation.indexes]: #section-index-pages
### Back-to-top button ### Back-to-top button
[:octicons-tag-24: 7.1.0][navigation.top support] · [:octicons-tag-24: 7.1.0][Back-to-top button support] ·
:octicons-unlock-24: Feature flag :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
@ -319,7 +317,7 @@ theme:
- navigation.top - navigation.top
``` ```
[navigation.top support]: https://github.com/squidfunk/mkdocs-material/releases/tag/7.1.0 [Back-to-top button support]: https://github.com/squidfunk/mkdocs-material/releases/tag/7.1.0
## Usage ## Usage
@ -329,7 +327,7 @@ The navigation and/or table of contents sidebars can be hidden for a document
with the front matter `hide` property. Add the following lines at the top of a with the front matter `hide` property. Add the following lines at the top of a
Markdown file: Markdown file:
``` sh ``` yaml
--- ---
hide: hide:
- navigation - navigation
@ -342,19 +340,19 @@ hide:
=== "Hide navigation" === "Hide navigation"
[![hide.navigation enabled]][hide.navigation enabled] [![Hide navigation enabled]][Hide navigation enabled]
=== "Hide table of contents" === "Hide table of contents"
[![hide.toc enabled]][hide.toc enabled] [![Hide table of contents enabled]][Hide table of contents enabled]
=== "Hide both" === "Hide both"
[![hide.* enabled]][hide.* enabled] [![Hide both enabled]][Hide both enabled]
[hide.navigation enabled]: ../assets/screenshots/hide-navigation.png [Navigation hiding enabled]: ../assets/screenshots/hide-navigation.png
[hide.toc enabled]: ../assets/screenshots/hide-toc.png [Hide table of contents enabled]: ../assets/screenshots/hide-toc.png
[hide.* enabled]: ../assets/screenshots/hide-navigation-toc.png [Hide both enabled]: ../assets/screenshots/hide-navigation-toc.png
## Customization ## Customization
@ -363,7 +361,7 @@ hide:
Material for MkDocs includes several keyboard shortcuts that make it possible Material for MkDocs includes several keyboard shortcuts that make it possible
to navigate your project documentation via keyboard. There are two modes: to navigate your project documentation via keyboard. There are two modes:
`search`{ #mode-search } [`search`](#mode:search){ #mode:search }
: This mode is active when the _search is focused_. It provides several key : This mode is active when the _search is focused_. It provides several key
bindings to make search accessible and navigable via keyboard: bindings to make search accessible and navigable via keyboard:
@ -372,7 +370,7 @@ to navigate your project documentation via keyboard. There are two modes:
* ++esc++ , ++tab++ : close search dialog * ++esc++ , ++tab++ : close search dialog
* ++enter++ : follow selected result * ++enter++ : follow selected result
`global`{ #mode-global } [`global`](#mode:global){ #mode:global }
: This mode is active when _search is not focussed_ and when there's no other : 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 focussed element that is susceptible to keyboard input. The following keys
@ -386,7 +384,7 @@ Let's say you want to bind some action to the ++x++ key. By using [additional
JavaScript], you can subscribe to the `keyboard$` observable and attach JavaScript], you can subscribe to the `keyboard$` observable and attach
your custom event listener: your custom event listener:
=== ":octicons-file-code-16: docs/javascripts/shortcuts.js" === ":octicons-file-code-16: `docs/javascripts/shortcuts.js`"
``` js ``` js
keyboard$.subscribe(function(key) { keyboard$.subscribe(function(key) {
@ -401,7 +399,7 @@ your custom event listener:
underlying event, so the keypress will not propagate further and underlying event, so the keypress will not propagate further and
touch other event listeners. touch other event listeners.
=== ":octicons-file-code-16: mkdocs.yml" === ":octicons-file-code-16: `mkdocs.yml`"
``` yaml ``` yaml
extra_javascript: extra_javascript:
@ -421,7 +419,7 @@ stretch to the entire available space.
This can easily be achieved with an [additional style sheet] and a few lines This can easily be achieved with an [additional style sheet] and a few lines
of CSS: of CSS:
=== ":octicons-file-code-16: docs/stylesheets/extra.css" === ":octicons-file-code-16: `docs/stylesheets/extra.css`"
``` css ``` css
.md-grid { .md-grid {
@ -438,7 +436,7 @@ of CSS:
} }
``` ```
=== ":octicons-file-code-16: mkdocs.yml" === ":octicons-file-code-16: `mkdocs.yml`"
``` yaml ``` yaml
extra_css: extra_css:

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

@ -10,7 +10,7 @@ MkDocs natively integrates with [Google Analytics] and offers a customizable
[cookie consent] and a [feedback widget]. [cookie consent] and a [feedback widget].
[Google Analytics]: https://developers.google.com/analytics [Google Analytics]: https://developers.google.com/analytics
[cookie consent]: ensuring-data-privacy.md#native-cookie-consent [cookie consent]: ensuring-data-privacy.md#cookie-consent
[feedback widget]: #was-this-page-helpful [feedback widget]: #was-this-page-helpful
## Configuration ## Configuration
@ -70,7 +70,7 @@ following lines to `mkdocs.yml`:
### Was this page helpful? ### Was this page helpful?
[:octicons-tag-24: 8.4.0][feedback support] · [:octicons-tag-24: 8.4.0][Was this page helpful? support] ·
:octicons-milestone-24: Default: _none_ · :octicons-milestone-24: Default: _none_ ·
:octicons-beaker-24: Experimental :octicons-beaker-24: Experimental
@ -169,9 +169,9 @@ integrated with the [cookie consent] feature[^1].
The following properties are available for each rating: The following properties are available for each rating:
`icon`{ #feedback-rating-icon } [`icon`](#+analytics.feedback.ratings.icon){ #+analytics.feedback.ratings.icon }
: :octicons-milestone-24: Default: _none_ · :octicons-alert-24: Required – : :octicons-milestone-24: Default: _none_ · :octicons-alert-24: __Required__ –
This property must point to a valid icon path referencing [any icon bundled This property must point to a valid icon path referencing [any icon bundled
with the theme][custom icons], or the build will not succeed. Some popular with the theme][custom icons], or the build will not succeed. Some popular
combinations: combinations:
@ -180,24 +180,24 @@ The following properties are available for each rating:
* :material-thumb-up-outline: + :material-thumb-down-outline: – `material/thumb-up-outline` + `material/thumb-down-outline` * :material-thumb-up-outline: + :material-thumb-down-outline: – `material/thumb-up-outline` + `material/thumb-down-outline`
* :material-heart: + :material-heart-broken: – `material/heart` + `material/heart-broken` * :material-heart: + :material-heart-broken: – `material/heart` + `material/heart-broken`
`name`{ #feedback-rating-name } [`name`](#+analytics.feedback.ratings.name){ #+analytics.feedback.ratings.name }
: :octicons-milestone-24: Default: _none_ · :octicons-alert-24: Required – : :octicons-milestone-24: Default: _none_ · :octicons-alert-24: __Required__ –
The value of this property is shown on user interaction (i.e. keyboard focus The value of this property is shown on user interaction (i.e. keyboard focus
or mouse hover), explaining the meaning of the rating behind the icon. or mouse hover), explaining the meaning of the rating behind the icon.
`data`{ #feedback-rating-data } [`data`](#+analytics.feedback.ratings.data){ #+analytics.feedback.ratings.data }
: :octicons-milestone-24: Default: _none_ · :octicons-alert-24: Required – : :octicons-milestone-24: Default: _none_ · :octicons-alert-24: __Required__ –
The value of this property is sent as a data value with the custom event The value of this property is sent as a data value with the custom event
that is transmitted to Google Analytics[^2] (or any custom integration). that is transmitted to Google Analytics[^2] (or any custom integration).
[^2]: [^2]:
Note that for Google Analytics, the data value must be an integer. Note that for Google Analytics, the data value must be an integer.
`note`{ #feedback-rating-note } [`note`](#+analytics.feedback.ratings.note){ #+analytics.feedback.ratings.note }
: :octicons-milestone-24: Default: _none_ · :octicons-alert-24: Required – : :octicons-milestone-24: Default: _none_ · :octicons-alert-24: __Required__ –
The value of this property is shown after the user selected the rating. The value of this property is shown after the user selected the rating.
It may contain arbitrary HTML tags, which is especially useful to ask the It may contain arbitrary HTML tags, which is especially useful to ask the
user to provide more detailed feedback for the current page through a form. user to provide more detailed feedback for the current page through a form.
@ -221,7 +221,7 @@ The following properties are available for each rating:
An alternative to GitHub issues is [Google Forms]. An alternative to GitHub issues is [Google Forms].
[feedback support]: https://github.com/squidfunk/mkdocs-material/releases/tag/8.4.0 [Was this page helpful? support]: https://github.com/squidfunk/mkdocs-material/releases/tag/8.4.0
[feedback widget]: #feedback [feedback widget]: #feedback
[analytics]: #google-analytics [analytics]: #google-analytics
[feedback report]: ../assets/screenshots/feedback-report.png [feedback report]: ../assets/screenshots/feedback-report.png
@ -235,7 +235,7 @@ The following properties are available for each rating:
The [feedback widget] can be hidden for a document with the front matter `hide` property. Add the following lines at the top of a Markdown file: The [feedback widget] can be hidden for a document with the front matter `hide` property. Add the following lines at the top of a Markdown file:
``` sh ``` yaml
--- ---
hide: hide:
- feedback - feedback
@ -254,7 +254,7 @@ JavaScript-based tracking solution, just follow the guide on [theme extension]
and create a new partial in the `overrides` folder. The name of the partial is and create a new partial in the `overrides` folder. The name of the partial is
used to configure the custom integration via `mkdocs.yml`: used to configure the custom integration via `mkdocs.yml`:
=== ":octicons-file-code-16: overrides/partials/integrations/analytics/custom.html" === ":octicons-file-code-16: `overrides/partials/integrations/analytics/custom.html`"
``` html ``` html
<script> <script>
@ -276,7 +276,7 @@ used to configure the custom integration via `mkdocs.yml`:
observable to listen for navigation events, which always emits the observable to listen for navigation events, which always emits the
current `URL`. current `URL`.
=== ":octicons-file-code-16: mkdocs.yml" === ":octicons-file-code-16: `mkdocs.yml`"
``` yaml ``` yaml
extra: extra:
@ -298,7 +298,7 @@ A custom feedback widget integration just needs to process the events that are
generated by users interacting with the feedback widget with the help of some generated by users interacting with the feedback widget with the help of some
[additional JavaScript]: [additional JavaScript]:
=== ":octicons-file-code-16: docs/javascripts/feedback.js" === ":octicons-file-code-16: `docs/javascripts/feedback.js`"
``` js ``` js
var feedback = document.forms.feedback var feedback = document.forms.feedback
@ -314,7 +314,7 @@ generated by users interacting with the feedback widget with the help of some
}) })
``` ```
=== ":octicons-file-code-16: mkdocs.yml" === ":octicons-file-code-16: `mkdocs.yml`"
``` yaml ``` yaml
extra_javascript: extra_javascript:

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

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

20
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 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 a link to your project documentation is shared on social media. Material for
MkDocs can generate beautiful social cards automatically, using the [colors] MkDocs can generate beautiful social cards automatically, using the [colors],
[palette.primary], [fonts][font.text] and [logo][^1] defined in `mkdocs.yml`, [fonts] and [logo][^1] defined in `mkdocs.yml`,
e.g.: e.g.:
<figure markdown> <figure markdown>
@ -28,8 +28,8 @@ The social preview image for the page on [setting up site analytics].
color used in the header (white or black), which depends on the primary color used in the header (white or black), which depends on the primary
color. color.
[palette.primary]: changing-the-colors.md#primary-color [colors]: changing-the-colors.md#primary-color
[font.text]: changing-the-fonts.md#regular-font [fonts]: changing-the-fonts.md#regular-font
[logo]: changing-the-logo-and-icons.md#logo [logo]: changing-the-logo-and-icons.md#logo
[Social cards preview]: ../assets/screenshots/social-cards.png [Social cards preview]: ../assets/screenshots/social-cards.png
[setting up site analytics]: setting-up-site-analytics.md [setting up site analytics]: setting-up-site-analytics.md
@ -59,7 +59,7 @@ plugins:
The following configuration options are available: The following configuration options are available:
`cards`{ #cards } [`cards`](#+social.cards){ #+social.cards }
: :octicons-milestone-24: Default: `true` – This option specifies whether : :octicons-milestone-24: Default: `true` – This option specifies whether
to generate social card images. If you want to switch the plugin off, e.g. to generate social card images. If you want to switch the plugin off, e.g.
@ -71,7 +71,7 @@ The following configuration options are available:
cards: !ENV [CARDS, false] cards: !ENV [CARDS, false]
``` ```
`cards_color`{ #cards-color } [`cards_color`](#+social.cards_color){ #+social.cards_color }
: [:octicons-tag-24: insiders-2.13.0][Insiders] · :octicons-milestone-24: : [:octicons-tag-24: insiders-2.13.0][Insiders] · :octicons-milestone-24:
Default: [`theme.palette.primary`][palette.primary] – This option specifies Default: [`theme.palette.primary`][palette.primary] – This option specifies
@ -89,7 +89,7 @@ The following configuration options are available:
1. Colors can either be defined as HEX colors, or as [CSS color keywords]. 1. Colors can either be defined as HEX colors, or as [CSS color keywords].
Note that HEX colors must be enclosed in quotes. Note that HEX colors must be enclosed in quotes.
`cards_font`{ #cards-font } [`cards_font`](#+social.cards_font){ #+social.cards_font }
: [:octicons-tag-24: insiders-4.3.0][Insiders] · :octicons-milestone-24: : [:octicons-tag-24: insiders-4.3.0][Insiders] · :octicons-milestone-24:
Default: [`theme.font.text`][font.text] – This option specifies which font Default: [`theme.font.text`][font.text] – This option specifies which font
@ -102,7 +102,7 @@ The following configuration options are available:
cards_font: Roboto cards_font: Roboto
``` ```
`cards_dir`{ #cards-dir } [`cards_dir`](#+social.cards_dir){ #+social.cards_dir }
: :octicons-milestone-24: Default: `assets/images/social` – This option : :octicons-milestone-24: Default: `assets/images/social` – This option
specifies where the generated social card images will be written to. It's specifies where the generated social card images will be written to. It's
@ -111,13 +111,15 @@ The following configuration options are available:
``` yaml ``` yaml
plugins: plugins:
- social: - social:
cards_dir: assets/images/social cards_dir: path/to/folder
``` ```
[Insiders]: ../insiders/index.md [Insiders]: ../insiders/index.md
[dependencies]: #dependencies [dependencies]: #dependencies
[site_url]: https://www.mkdocs.org/user-guide/configuration/#site_url [site_url]: https://www.mkdocs.org/user-guide/configuration/#site_url
[built-in plugins]: ../insiders/getting-started.md#built-in-plugins [built-in plugins]: ../insiders/getting-started.md#built-in-plugins
[palette.primary]: changing-the-colors.md#primary-color
[font.text]: changing-the-fonts.md#regular-font
[environment variable]: https://www.mkdocs.org/user-guide/configuration/#environment-variables [environment variable]: https://www.mkdocs.org/user-guide/configuration/#environment-variables
[CSS color keywords]: https://developer.mozilla.org/en-US/docs/Web/CSS/color_value#color_keywords [CSS color keywords]: https://developer.mozilla.org/en-US/docs/Web/CSS/color_value#color_keywords
[Google Fonts]: https://fonts.google.com [Google Fonts]: https://fonts.google.com

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

@ -15,7 +15,7 @@ can help to discover relevant information faster.
### Built-in tags plugin ### Built-in tags plugin
[:octicons-tag-24: 8.2.0][tags support] · [:octicons-tag-24: 8.2.0][Tags support] ·
:octicons-cpu-24: Plugin · :octicons-cpu-24: Plugin ·
:octicons-beaker-24: Experimental :octicons-beaker-24: Experimental
@ -30,7 +30,7 @@ plugins:
The following configuration options are available: The following configuration options are available:
`tags_file`{ #tags-file } [`tags_file`](#+tags.tags_file){ #+tags.tags_file }
: :octicons-milestone-24: Default: _none_ – This option specifies which file : :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 should be used to render the tags index. See the section on [adding a tags
@ -48,7 +48,7 @@ The following configuration options are available:
of `mkdocs.yml`. Note, however, that this options is not required – only use of `mkdocs.yml`. Note, however, that this options is not required – only use
it if you want a tags index page. it if you want a tags index page.
`tags_extra_files`{ #tags-extra-files } :material-alert-decagram:{ .mdx-pulse title="Added on July 7, 2022" } [`tags_extra_files`](#+tags.tags_extra_files){ #+tags.tags_extra_files } :material-alert-decagram:{ .mdx-pulse title="Added on July 7, 2022" }
: [:octicons-tag-24: insiders-4.20.0][Insiders] · :octicons-milestone-24: : [:octicons-tag-24: insiders-4.20.0][Insiders] · :octicons-milestone-24:
Default: _none_ – This option allows to define additional pages to render Default: _none_ – This option allows to define additional pages to render
@ -86,7 +86,7 @@ The following configuration options are available:
See #3864 for additional use cases. See #3864 for additional use cases.
[tags support]: https://github.com/squidfunk/mkdocs-material/releases/tag/8.2.0 [Tags support]: https://github.com/squidfunk/mkdocs-material/releases/tag/8.2.0
[tag identifiers]: #tag-icons [tag identifiers]: #tag-icons
### Tag icons ### Tag icons
@ -197,7 +197,7 @@ search preview, which now allows to __find pages by tags__.
With the help of the [built-in meta plugin], you can ensure that tags are With the help of the [built-in meta plugin], you can ensure that tags are
set for an entire section and all nested pages, by creating a `.meta.yml` set for an entire section and all nested pages, by creating a `.meta.yml`
in the corresponding folder with the following content: file in the corresponding folder with the following content:
``` yaml ``` yaml
tags: tags:
@ -232,10 +232,10 @@ The `[TAGS]` marker specifies the position of the tags index, i.e. it is
replaced with the actual tags index when the page is rendered. You can include replaced with the actual tags index when the page is rendered. You can include
arbitrary content before and after the marker: arbitrary content before and after the marker:
[![Tags index][9]][9] [![Tags index][tags index enabled]][tags index enabled]
[tags.tags_file]: #tags-file [tags.tags_file]: #tags-file
[9]: ../assets/screenshots/tags-index.png [tags index enabled]: ../assets/screenshots/tags-index.png
### Hiding tags on a page ### Hiding tags on a page
@ -243,7 +243,7 @@ While the tags are rendered above the main headline, sometimes, it might be
desirable to hide them for a specific page, which can be achieved with the desirable to hide them for a specific page, which can be achieved with the
front matter `hide` property: front matter `hide` property:
``` sh ``` yaml
--- ---
hide: hide:
- tags - tags

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

@ -14,7 +14,7 @@ configure via `mkdocs.yml`.
### Social links ### Social links
[:octicons-tag-24: 1.0.0][social support] · [:octicons-tag-24: 1.0.0][Social links support] ·
:octicons-milestone-24: Default: _none_ :octicons-milestone-24: Default: _none_
Social links are rendered next to the copyright notice as part of the Social links are rendered next to the copyright notice as part of the
@ -41,14 +41,12 @@ extra:
The following properties are available for each link: The following properties are available for each link:
`icon`{ #social-icon } [`icon`](#+social.icon){ #+social.icon }
: [:octicons-tag-24: 5.0.0][social.icon support] · :octicons-milestone-24: : :octicons-milestone-24: Default: _none_ · :octicons-alert-24: __Required__ –
Default: _none_ · :octicons-alert-24: Required – This property must contain This property must contain a valid path to any icon bundled with the theme,
a valid path to any icon bundled with the theme, or the or the build will not succeed. Some popular choices:
build will not succeed. Some popular choices:
* :fontawesome-brands-behance: – `fontawesome/brands/behance`
* :fontawesome-brands-docker: – `fontawesome/brands/docker` * :fontawesome-brands-docker: – `fontawesome/brands/docker`
* :fontawesome-brands-facebook: – `fontawesome/brands/facebook` * :fontawesome-brands-facebook: – `fontawesome/brands/facebook`
* :fontawesome-brands-github: – `fontawesome/brands/github` * :fontawesome-brands-github: – `fontawesome/brands/github`
@ -60,9 +58,9 @@ The following properties are available for each link:
* :fontawesome-brands-slack: – `fontawesome/brands/slack` * :fontawesome-brands-slack: – `fontawesome/brands/slack`
* :fontawesome-brands-twitter: – `fontawesome/brands/twitter` * :fontawesome-brands-twitter: – `fontawesome/brands/twitter`
`link`{ #social-link } [`link`](#+social.link){ #+social.link }
: :octicons-milestone-24: Default: _none_ · :octicons-alert-24: Required – : :octicons-milestone-24: Default: _none_ · :octicons-alert-24: __Required__ –
This property must be set to a relative or absolute URL including the URI This property must be set to a relative or absolute URL including the URI
scheme. All URI schemes are supported, including `mailto` and `bitcoin`: scheme. All URI schemes are supported, including `mailto` and `bitcoin`:
@ -84,12 +82,11 @@ The following properties are available for each link:
link: mailto:<email-address> link: mailto:<email-address>
``` ```
`name`{ #social-name } [`name`](#+social.name){ #+social.name }
: [:octicons-tag-24: 5.1.5][social.name support] · :octicons-milestone-24: : :octicons-milestone-24: Default: _domain name from_ `link`_, if available_ –
Default: _domain name from_ `link`_, if available_ – This property is used This property is used as the link's `title` attribute and can be set to a
as the link's `title` attribute and can be set to a discernable name to discernable name to improve accessibility:
improve accessibility:
``` yaml ``` yaml
extra: extra:
@ -100,9 +97,7 @@ The following properties are available for each link:
``` ```
[icon search]: ../reference/icons-emojis.md#search [icon search]: ../reference/icons-emojis.md#search
[social support]: https://github.com/squidfunk/mkdocs-material/releases/tag/1.0.0 [Social links support]: https://github.com/squidfunk/mkdocs-material/releases/tag/1.0.0
[social.icon support]: https://github.com/squidfunk/mkdocs-material/releases/tag/5.0.0
[social.name support]: https://github.com/squidfunk/mkdocs-material/releases/tag/5.1.5
### Copyright notice ### Copyright notice
@ -156,7 +151,7 @@ The footer navigation showing links to the previous and next page can be hidden
with the front matter `hide` property. Add the following lines at the top of a with the front matter `hide` property. Add the following lines at the top of a
Markdown file: Markdown file:
``` sh ``` yaml
--- ---
hide: hide:
- footer - footer
@ -174,7 +169,7 @@ hide:
:octicons-file-symlink-file-24: Customization :octicons-file-symlink-file-24: Customization
In order to customize and override the [copyright notice], [extend the theme] In order to customize and override the [copyright notice], [extend the theme]
and [override the `copyright` partial][overriding partials], which normally and [override the `copyright.html` partial][overriding partials], which normally
includes the `copyright` property set in `mkdocs.yml`. includes the `copyright` property set in `mkdocs.yml`.
[Custom copyright support]: https://github.com/squidfunk/mkdocs-material/releases/tag/8.0.0 [Custom copyright support]: https://github.com/squidfunk/mkdocs-material/releases/tag/8.0.0

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

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

58
docs/upgrade.md
View File

@ -133,7 +133,7 @@ matches the new structure:
- If you've overridden a __template__, check the respective `*.html` file for - If you've overridden a __template__, check the respective `*.html` file for
potential changes potential changes
=== ":octicons-file-code-16: base.html" === ":octicons-file-code-16: `base.html`"
``` diff ``` diff
@@ -13,11 +13,6 @@ @@ -13,11 +13,6 @@
@ -363,7 +363,7 @@ matches the new structure:
</div> </div>
``` ```
=== ":octicons-file-code-16: partials/copyright.html" === ":octicons-file-code-16: `partials/copyright.html`"
``` diff ``` diff
@@ -0,0 +1,16 @@ @@ -0,0 +1,16 @@
@ -385,7 +385,7 @@ matches the new structure:
+</div> +</div>
``` ```
=== ":octicons-file-code-16: partials/footer.html" === ":octicons-file-code-16: `partials/footer.html`"
``` diff ``` diff
@@ -41,21 +40,10 @@ @@ -41,21 +40,10 @@
@ -416,7 +416,7 @@ matches the new structure:
</footer> </footer>
``` ```
=== ":octicons-file-code-16: partials/social.html" === ":octicons-file-code-16: `partials/social.html`"
``` diff ``` diff
@@ -4,17 +4,15 @@ @@ -4,17 +4,15 @@
@ -492,7 +492,7 @@ matches the new structure:
- If you've overridden a __template__, check the respective `*.html` file for - If you've overridden a __template__, check the respective `*.html` file for
potential changes potential changes
=== ":octicons-file-code-16: base.html" === ":octicons-file-code-16: `base.html`"
``` diff ``` diff
@@ -61,7 +61,7 @@ @@ -61,7 +61,7 @@
@ -581,7 +581,7 @@ matches the new structure:
{% endfor %} {% endfor %}
``` ```
=== ":octicons-file-code-16: partials/footer.html" === ":octicons-file-code-16: `partials/footer.html`"
``` diff ``` diff
- <div class="md-footer-nav"> - <div class="md-footer-nav">
@ -653,7 +653,7 @@ matches the new structure:
<div class="md-footer-meta__inner md-grid"> <div class="md-footer-meta__inner md-grid">
``` ```
=== ":octicons-file-code-16: partials/header.html" === ":octicons-file-code-16: `partials/header.html`"
``` diff ``` diff
@@ -6,21 +6,21 @@ @@ -6,21 +6,21 @@
@ -725,7 +725,7 @@ matches the new structure:
{% endif %} {% endif %}
``` ```
=== ":octicons-file-code-16: partials/source.html" === ":octicons-file-code-16: `partials/source.html`"
``` diff ``` diff
@@ -4,5 +4,5 @@ @@ -4,5 +4,5 @@
@ -737,7 +737,7 @@ matches the new structure:
{% include ".icons/" ~ icon ~ ".svg" %} {% include ".icons/" ~ icon ~ ".svg" %}
``` ```
=== ":octicons-file-code-16: partials/toc.html" === ":octicons-file-code-16: `partials/toc.html`"
``` diff ``` diff
@@ -12,7 +12,7 @@ @@ -12,7 +12,7 @@
@ -808,7 +808,7 @@ matches the new structure:
- If you've overridden a __template__, check the respective `*.html` file for - If you've overridden a __template__, check the respective `*.html` file for
potential changes potential changes
=== ":octicons-file-code-16: base.html" === ":octicons-file-code-16: `base.html`"
``` diff ``` diff
@@ -22,13 +22,6 @@ @@ -22,13 +22,6 @@
@ -978,7 +978,7 @@ matches the new structure:
{%- endfor -%} {%- endfor -%}
``` ```
=== ":octicons-file-code-16: partials/hero.html" === ":octicons-file-code-16: `partials/hero.html`"
``` diff ``` diff
@@ -1,12 +0,0 @@ @@ -1,12 +0,0 @@
@ -996,7 +996,7 @@ matches the new structure:
-</div> -</div>
``` ```
=== ":octicons-file-code-16: partials/source-link" === ":octicons-file-code-16: `partials/source-link`"
``` diff ``` diff
@@ -1,14 +0,0 @@ @@ -1,14 +0,0 @@
@ -1170,7 +1170,7 @@ matches the new structure:
- If you've overridden a __template__, check the respective `*.html` file for - If you've overridden a __template__, check the respective `*.html` file for
potential changes potential changes
=== ":octicons-file-code-16: base.html" === ":octicons-file-code-16: `base.html`"
``` diff ``` diff
@@ -4,7 +4,6 @@ @@ -4,7 +4,6 @@
@ -1419,7 +1419,7 @@ matches the new structure:
{% endfor %} {% endfor %}
``` ```
=== ":octicons-file-code-16: partials/footer.html" === ":octicons-file-code-16: `partials/footer.html`"
``` diff ``` diff
@@ -5,34 +5,34 @@ @@ -5,34 +5,34 @@
@ -1470,7 +1470,7 @@ matches the new structure:
{% endif %} {% endif %}
``` ```
=== ":octicons-file-code-16: partials/header.html" === ":octicons-file-code-16: `partials/header.html`"
``` diff ``` diff
@@ -4,51 +4,43 @@ @@ -4,51 +4,43 @@
@ -1559,7 +1559,7 @@ matches the new structure:
</header> </header>
``` ```
=== ":octicons-file-code-16: partials/hero.html" === ":octicons-file-code-16: `partials/hero.html`"
``` diff ``` diff
@@ -4,9 +4,8 @@ @@ -4,9 +4,8 @@
@ -1572,7 +1572,7 @@ matches the new structure:
<div class="{{ class }}" data-md-component="hero"> <div class="{{ class }}" data-md-component="hero">
``` ```
=== ":octicons-file-code-16: partials/language.html" === ":octicons-file-code-16: `partials/language.html`"
``` diff ``` diff
@@ -4,12 +4,4 @@ @@ -4,12 +4,4 @@
@ -1590,7 +1590,7 @@ matches the new structure:
+{% macro t(key) %}{{ lang.t(key) | default(fallback.t(key)) }}{% endmacro %} +{% macro t(key) %}{{ lang.t(key) | default(fallback.t(key)) }}{% endmacro %}
``` ```
=== ":octicons-file-code-16: partials/logo.html" === ":octicons-file-code-16: `partials/logo.html`"
``` diff ``` diff
@@ -0,0 +1,9 @@ @@ -0,0 +1,9 @@
@ -1605,7 +1605,7 @@ matches the new structure:
+{% endif %} +{% endif %}
``` ```
=== ":octicons-file-code-16: partials/nav-item.html" === ":octicons-file-code-16: `partials/nav-item.html`"
``` diff ``` diff
@@ -14,9 +14,15 @@ @@ -14,9 +14,15 @@
@ -1637,7 +1637,7 @@ matches the new structure:
<a href="{{ nav_item.url | url }}" title="{{ nav_item.title | striptags }}" class="md-nav__link md-nav__link--active"> <a href="{{ nav_item.url | url }}" title="{{ nav_item.title | striptags }}" class="md-nav__link md-nav__link--active">
``` ```
=== ":octicons-file-code-16: partials/nav.html" === ":octicons-file-code-16: `partials/nav.html`"
``` diff ``` diff
@@ -4,14 +4,10 @@ @@ -4,14 +4,10 @@
@ -1658,7 +1658,7 @@ matches the new structure:
</label> </label>
``` ```
=== ":octicons-file-code-16: partials/search.html" === ":octicons-file-code-16: `partials/search.html`"
``` diff ``` diff
@@ -6,15 +6,18 @@ @@ -6,15 +6,18 @@
@ -1686,7 +1686,7 @@ matches the new structure:
</div> </div>
``` ```
=== ":octicons-file-code-16: partials/social.html" === ":octicons-file-code-16: `partials/social.html`"
``` diff ``` diff
@@ -4,9 +4,12 @@ @@ -4,9 +4,12 @@
@ -1705,7 +1705,7 @@ matches the new structure:
{% endif %} {% endif %}
``` ```
=== ":octicons-file-code-16: partials/source-date.html" === ":octicons-file-code-16: `partials/source-date.html`"
``` diff ``` diff
@@ -0,0 +1,15 @@ @@ -0,0 +1,15 @@
@ -1726,7 +1726,7 @@ matches the new structure:
+</div> +</div>
``` ```
=== ":octicons-file-code-16: partials/source-link.html" === ":octicons-file-code-16: `partials/source-link.html`"
``` diff ``` diff
@@ -0,0 +1,13 @@ @@ -0,0 +1,13 @@
@ -1745,7 +1745,7 @@ matches the new structure:
+</a> +</a>
``` ```
=== ":octicons-file-code-16: partials/source.html" === ":octicons-file-code-16: `partials/source.html`"
``` diff ``` diff
@@ -4,24 +4,11 @@ @@ -4,24 +4,11 @@
@ -1778,7 +1778,7 @@ matches the new structure:
</div> </div>
``` ```
=== ":octicons-file-code-16: partials/tabs-item.html" === ":octicons-file-code-16: `partials/tabs-item.html`"
``` diff ``` diff
@@ -4,7 +4,7 @@ @@ -4,7 +4,7 @@
@ -1789,7 +1789,7 @@ matches the new structure:
<a href="{{ nav_item.url | url }}" class="md-tabs__link md-tabs__link--active"> <a href="{{ nav_item.url | url }}" class="md-tabs__link md-tabs__link--active">
``` ```
=== ":octicons-file-code-16: partials/tabs.html" === ":octicons-file-code-16: `partials/tabs.html`"
``` diff ``` diff
@@ -5,7 +5,7 @@ @@ -5,7 +5,7 @@
@ -1803,7 +1803,7 @@ matches the new structure:
{% for nav_item in nav %} {% for nav_item in nav %}
``` ```
=== ":octicons-file-code-16: partials/toc-item.html" === ":octicons-file-code-16: `partials/toc-item.html`"
``` diff ``` diff
@@ -6,7 +6,7 @@ @@ -6,7 +6,7 @@
@ -1817,7 +1817,7 @@ matches the new structure:
{% include "partials/toc-item.html" %} {% include "partials/toc-item.html" %}
``` ```
=== ":octicons-file-code-16: partials/toc.html" === ":octicons-file-code-16: `partials/toc.html`"
``` diff ``` diff
@@ -4,35 +4,22 @@ @@ -4,35 +4,22 @@

3
material/partials/comments.html Normal file
View File

@ -0,0 +1,3 @@
{#-
This file was automatically generated - do not edit
-#}

1
material/partials/content.html
View File

@ -16,3 +16,4 @@
{% include "partials/source-file.html" %} {% include "partials/source-file.html" %}
{% endif %} {% endif %}
{% include "partials/feedback.html" %} {% include "partials/feedback.html" %}
{% include "partials/comments.html" %}

10
mkdocs.yml
View File

@ -185,6 +185,7 @@ nav:
- Setting up site search: setup/setting-up-site-search.md - Setting up site search: setup/setting-up-site-search.md
- Setting up site analytics: setup/setting-up-site-analytics.md - Setting up site analytics: setup/setting-up-site-analytics.md
- Setting up social cards: setup/setting-up-social-cards.md - Setting up social cards: setup/setting-up-social-cards.md
- Setting up a blog: setup/setting-up-a-blog.md
- Setting up tags: setup/setting-up-tags.md - Setting up tags: setup/setting-up-tags.md
- Setting up versioning: setup/setting-up-versioning.md - Setting up versioning: setup/setting-up-versioning.md
- Setting up the header: setup/setting-up-the-header.md - Setting up the header: setup/setting-up-the-header.md
@ -221,8 +222,9 @@ nav:
- Blog: - Blog:
- blog/index.md - blog/index.md
- 2022: - 2022:
- blog/2022/chinese-search-support.md - blog/posts/blog-support-just-landed.md
- blog/posts/chinese-search-support.md
- 2021: - 2021:
- blog/2021/the-past-present-and-future.md - blog/posts/the-past-present-and-future.md
- blog/2021/excluding-content-from-search.md - blog/posts/excluding-content-from-search.md
- blog/2021/search-better-faster-smaller.md - blog/posts/search-better-faster-smaller.md

23
src/partials/comments.html Normal file
View File

@ -0,0 +1,23 @@
<!--
Copyright (c) 2016-2022 Martin Donath <martin.donath@squidfunk.com>
Permission is hereby granted, free of charge, to any person obtaining a copy
of this software and associated documentation files (the "Software"), to
deal in the Software without restriction, including without limitation the
rights to use, copy, modify, merge, publish, distribute, sublicense, and/or
sell copies of the Software, and to permit persons to whom the Software is
furnished to do so, subject to the following conditions:
The above copyright notice and this permission notice shall be included in
all copies or substantial portions of the Software.
THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
FITNESS FOR A PARTICULAR PURPOSE AND NON-INFRINGEMENT. IN NO EVENT SHALL THE
AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING
FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS
IN THE SOFTWARE.
-->
<!-- Comment system -->

3
src/partials/content.html
View File

@ -49,3 +49,6 @@
<!-- Was this page helpful? --> <!-- Was this page helpful? -->
{% include "partials/feedback.html" %} {% include "partials/feedback.html" %}
<!-- Comment system -->
{% include "partials/comments.html" %}