Cool_Tools/mkdocs-material
1
0
Fork 0
mirror of https://github.com/squidfunk/mkdocs-material.git synced 2024-11-23 23:21:00 +01:00
Code Issues 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
## [Chinese search support – 中文搜索​支持]
__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
This is our blog where we write about new features, performance improvements
and the project in general.

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
description: >
Insiders adds Chinese language support for the built-in search plugin – a
feature that has been requested many times
hide:
- feedback
categories:
- 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 – 中文搜索​支持
@ -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
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
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
@ -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
for the built-in search plugin, something that has been requested by many users.
<!-- more -->
_Material for MkDocs終於​支持​中文​了！文本​被​正確​分割​並且​更​容易​找到。_
{ 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._
{ 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
## 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: >
Three new simple ways to exclude dedicated parts of a document from the search
index, allowing for more fine-grained control
search:
exclude: true
hide:
- feedback
categories:
- Search
links:
- 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
@ -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
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
plugin], yielding [massive improvements in usability], but also in [speed
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
Markdown file should be indexed by the built-in search functionality.
<!-- more -->
_The following section discusses existing solutions for excluding pages and
sections from the search index. If you immediately want to learn 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
whether it is excluded or not:
``` sh
``` yaml
---
search:
exclude: true
@ -137,11 +126,11 @@ search:
### Excluding sections
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
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
# Document title
@ -155,7 +144,7 @@ filtered by the search plugin before the page is rendered:
The content of this section is excluded
```
=== ":octicons-codescan-16: search_index.json"
=== ":octicons-codescan-16: `search_index.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
supported by the [Attribute Lists] extension:
=== ":octicons-file-code-16: docs/page.md"
=== ":octicons-file-code-16: `docs/page.md`"
``` markdown
# Document title
@ -192,7 +181,7 @@ supported by the [Attribute Lists] extension:
{ data-search-exclude }
```
=== ":octicons-codescan-16: search_index.json"
=== ":octicons-codescan-16: `search_index.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: >
How we rebuilt client-side search, delivering a better user experience while
making it faster and smaller at the same time
search:
exclude: true
hide:
- feedback
categories:
- Search
- Performance
links:
- setup/setting-up-site-search.md#built-in-search-plugin
- insiders/index.md#how-to-become-a-sponsor
---
# 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
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
assets: [multilingual], [offline-capable], and most importantly: _all
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
version, and what's about to come.
<!-- more -->
_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
[section just after that][what's new]._
@ -78,7 +68,7 @@ the original Markdown file:
??? example "Expand to inspect example"
=== ":octicons-file-code-16: docs/page.md"
=== ":octicons-file-code-16: `docs/page.md`"
```` markdown
# Example
@ -108,7 +98,7 @@ the original Markdown file:
* Profit!
````
=== ":octicons-codescan-16: search_index.json"
=== ":octicons-codescan-16: `search_index.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: >
2021 was a fantastic year for this project as we shipped many new awesome
features and made this project sustainable
search:
exclude: true
hide:
- feedback
categories:
- General
---
# 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
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
options when it comes to choosing a static site generator and theme for 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
bring some interesting new capabilities.
<!-- more -->
_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
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
[Content tabs: improved support]: ../../reference/content-tabs.md
[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
[Dark mode support for images]: ../../reference/images.md#light-and-dark-mode
[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
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,
please [open an issue]:
find that something doesn't look right in a browser which is in the supported
version range, please [open an issue]:
<figure markdown>

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

@ -153,6 +153,7 @@ and much more:
- [Setting up site search]
- [Setting up site analytics]
- [Setting up social cards]
- [Setting up a blog]
- [Setting up tags]
- [Setting up versioning]
- [Setting up the header]
@ -164,7 +165,7 @@ and much more:
</div>
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.
[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 analytics]: setup/setting-up-site-analytics.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 versioning]: setup/setting-up-versioning.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.html # Analytics setup
│ ├─ languages/ # Translation languages
│ ├─ actions.html # Actions
│ ├─ comments.html # Comment system (empty by default)
│ ├─ consent.html # Consent
│ ├─ content.html # Page content
│ ├─ copyright.html # Copyright and theme information
│ ├─ feedback.html # Was this page helpful?
│ ├─ footer.html # Footer bar
│ ├─ header.html # Header bar
│ ├─ icons.html # Custom icons
│ ├─ language.html # Translation setup
│ ├─ logo.html # Logo in header and sidebar
│ ├─ nav.html # Main navigation
│ ├─ nav-item.html # Main navigation item
│ ├─ pagination.html # Pagination (used for blog)
│ ├─ palette.html # Color palette
│ ├─ post.html # Blog post excerpt
│ ├─ search.html # Search interface
│ ├─ social.html # Social links
│ ├─ source.html # Repository information
│ ├─ source-file.html # Source file information
│ ├─ tabs.html # Tabs navigation
│ ├─ tabs-item.html # Tabs navigation item
│ ├─ tags.html # Tags
│ ├─ toc.html # Table of contents
│ └─ toc-item.html # Table of contents item
├─ 404.html # 404 error page
├─ 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
@ -192,6 +204,7 @@ The following template blocks are provided by the theme:
| `analytics` | Wraps the Google Analytics integration |
| `announce` | Wraps the announcement bar |
| `config` | Wraps the JavaScript application config |
| `container` | Wraps the main content container |
| `content` | Wraps the main content |
| `extrahead` | Empty block to add custom meta tags |
| `fonts` | Wraps the font definitions |

15
docs/getting-started.md
View File

@ -1,6 +1,5 @@
---
template: overrides/main.html
title: 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" }
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
the help box. Install with:
`pip`, ideally by using a [virtual environment]. Open up a terminal and install
Material for MkDocs with:
=== "Latest"
@ -38,7 +37,7 @@ the help box. Install with:
good idea to limit upgrades to the current major version.
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,
so builds are reproducible at all times:
@ -81,8 +80,8 @@ troubleshoot if you run into errors.
### with docker
The official [Docker image] is a great way to get up and running in a few
minutes, as it comes with all dependencies pre-installed. Pull the image for the
`latest` version with:
minutes, as it comes with all dependencies pre-installed. Open up a terminal
and pull the image with:
=== "Latest"
@ -151,8 +150,8 @@ want to use the very latest version:
git clone https://github.com/squidfunk/mkdocs-material.git
```
The theme will reside in the folder `mkdocs-material/material`. When cloning
from `git`, you must install all required dependencies yourself:
The theme will reside in the folder `mkdocs-material/material`. After cloning
from `git`, you must install all required dependencies with:
```
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.
[^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)
- `documentation.yml` – Build and deploy the documentation (disabled on forks)
- `publish.yml` – Build and publish the Docker image
### 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
be mitigated by using [configuration inheritance]:
=== ":octicons-file-code-16: mkdocs.insiders.yml"
=== ":octicons-file-code-16: `mkdocs.insiders.yml`"
``` yaml
INHERIT: mkdocs.yml
@ -172,7 +171,7 @@ be mitigated by using [configuration inheritance]:
- tags
```
=== ":octicons-file-code-16: mkdocs.yml"
=== ":octicons-file-code-16: `mkdocs.yml`"
``` yaml
# 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
then look like:
=== ":octicons-file-code-16: mkdocs.insiders.yml"
=== ":octicons-file-code-16: `mkdocs.insiders.yml`"
``` yaml
INHERIT: mkdocs.yml
@ -200,7 +199,7 @@ mkdocs build --config-file mkdocs.insiders.yml
social: {}
```
=== ":octicons-file-code-16: mkdocs.yml"
=== ":octicons-file-code-16 `mkdocs.yml`"
``` yaml
# 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?
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:
<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] [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] [Automatic light / dark mode]
- [x] [Content tabs: anchor links]
@ -258,10 +260,10 @@ are released for general availability.
- [x] [Excluding content from search]
- [x] [Offline plugin]
[Brand new search plugin]: ../blog/2021/search-better-faster-smaller.md
[Rich search previews]: ../blog/2021/search-better-faster-smaller.md#rich-search-previews
[Tokenizer with lookahead]: ../blog/2021/search-better-faster-smaller.md#tokenizer-lookahead
[Advanced search highlighting]: ../blog/2021/search-better-faster-smaller.md#accurate-highlighting
[Brand new search plugin]: ../blog/posts/search-better-faster-smaller.md
[Rich search previews]: ../blog/posts/search-better-faster-smaller.md#rich-search-previews
[Tokenizer with lookahead]: ../blog/posts/search-better-faster-smaller.md#tokenizer-lookahead
[Advanced search highlighting]: ../blog/posts/search-better-faster-smaller.md#accurate-highlighting
[Excluding content from search]: ../setup/setting-up-site-search.md#search-exclusion
[Offline plugin]: ../setup/building-for-offline-usage.md
@ -272,13 +274,14 @@ are released for general availability.
- [x] [Navigation icons]
- [x] [Navigation pruning]
- [x] [Navigation status]
- [ ] Blog plugin
- [x] [Blog plugin]
[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 pruning]: ../setup/setting-up-navigation.md#navigation-pruning
[Navigation status]: ../reference/index.md#setting-the-page-status
[Blog plugin]: ../setup/setting-up-a-blog.md
#### $ 14,000 – Goat's Horn
@ -298,14 +301,17 @@ are released for general availability.
#### $ 16,000 – Chipotle
- [x] [Blog plugin: related links]
- [x] [Meta plugin]
- [x] [Additional tags indexes]
- [ ] [Navigation subtitles]
- [ ] [Instant previews]
- [ ] ... more to be announced
[Meta plugin]: ../reference/index.md#built-in-meta-plugin
[Additional tags indexes]: ../setup/setting-up-tags.md#tags-extra-files
[Instant previews]: https://twitter.com/squidfunk/status/1466794654213492743
[Blog plugin: related links]: ../setup/setting-up-a-blog.md#adding-related-links
### Goals completed
@ -319,7 +325,7 @@ can be used by all users.
- [x] [Was this page helpful?]
- [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
[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
[:octicons-tag-24: 8.3.0][icon support] ·
[:octicons-tag-24: 8.3.0][Admonition icons support] ·
:octicons-beaker-24: Experimental
Each of the supported admonition types has a distinct icon, which can be changed
@ -103,7 +103,7 @@ theme:
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
[supported types]: #supported-types
[icon search]: icons-emojis.md#search
@ -231,7 +231,7 @@ Adding a `+` after the `???` token renders the block expanded:
### Inline blocks
[:octicons-tag-24: 7.0.0][Inline support] ·
[:octicons-tag-24: 7.0.0][Inline blocks support] ·
:octicons-beaker-24: Experimental
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
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
Following is a list of type qualifiers provided by Material for MkDocs, whereas
the default type, and thus fallback for unknown type qualifiers, is `note`:
`note`{ #type-note }
[`note`](#type:note){ #type: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
purus auctor massa, nec semper lorem quam in massa.
`abstract`{ #type-abstract }, `summary`, `tldr`
[`abstract`](#type:abstract){ #type:abstract }, `summary`, `tldr`
: !!! 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
purus auctor massa, nec semper lorem quam in massa.
`info`{ #type-info }, `todo`
[`info`](#type:info){ #type:info }, `todo`
: !!! 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
purus auctor massa, nec semper lorem quam in massa.
`tip`{ #type-tip }, `hint`, `important`
[`tip`](#type:tip){ #type:tip }, `hint`, `important`
: !!! 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
purus auctor massa, nec semper lorem quam in massa.
`success`{ #type-success }, `check`, `done`
[`success`](#type:success){ #type:success }, `check`, `done`
: !!! 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
purus auctor massa, nec semper lorem quam in massa.
`question`{ #type-question }, `help`, `faq`
[`question`](#type:question){ #type:question }, `help`, `faq`
: !!! 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
purus auctor massa, nec semper lorem quam in massa.
`warning`{ #type-warning }, `caution`, `attention`
[`warning`](#type:warning){ #type:warning }, `caution`, `attention`
: !!! 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
purus auctor massa, nec semper lorem quam in massa.
`failure`{ #type-failure }, `fail`, `missing`
[`failure`](#type:failure){ #type:failure }, `fail`, `missing`
: !!! 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
purus auctor massa, nec semper lorem quam in massa.
`danger`{ #type-danger }, `error`
[`danger`](#type:danger){ #type:danger }, `error`
: !!! 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
purus auctor massa, nec semper lorem quam in massa.
`bug`{ #type-bug }
[`bug`](#type:bug){ #type: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
purus auctor massa, nec semper lorem quam in massa.
`example`{ #type-example }
[`example`](#type:example){ #type: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
purus auctor massa, nec semper lorem quam in massa.
`quote`{ #type-quote }, `cite`
[`quote`](#type:quote){ #type:quote }, `cite`
: !!! quote
@ -414,7 +414,7 @@ and add the following CSS to an [additional style sheet]:
}
</style>
=== ":octicons-file-code-16: docs/stylesheets/extra.css"
=== ":octicons-file-code-16: `docs/stylesheets/extra.css`"
``` css
: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
extra_css:

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

@ -126,8 +126,6 @@ import tensorflow as tf
### 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
block by using the `title="<custom title>"` option directly after the shortcode,
e.g. to display the name of a file:
@ -154,8 +152,6 @@ def bubble_sort(items):
</div>
[Title support]: https://github.com/squidfunk/mkdocs-material/releases/tag/7.3.6
### Adding annotations
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
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
: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
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
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
.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
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
of an [additional style sheet]:
=== ":octicons-file-code-16: docs/stylesheets/extra.css"
=== ":octicons-file-code-16: `docs/stylesheets/extra.css`"
``` css
:root {
@ -408,7 +404,7 @@ of an [additional style sheet]:
}
```
=== ":octicons-file-code-16: mkdocs.yml"
=== ":octicons-file-code-16: `mkdocs.yml`"
``` yaml
extra_css:
@ -439,7 +435,7 @@ will close them.
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:
=== ":octicons-file-code-16: docs/stylesheets/extra.css"
=== ":octicons-file-code-16: `docs/stylesheets/extra.css`"
``` css
.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
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
[:octicons-tag-24: 8.3.0][link support] ·
[:octicons-tag-24: 8.3.0][Linked content tabs support] ·
:octicons-unlock-24: Feature flag ·
: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
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
[content.tabs.link enabled]: ../assets/screenshots/content-tabs-link.png
[content.tabs.link disabled]: ../assets/screenshots/content-tabs.png
[Linked content tabs enabled]: ../assets/screenshots/content-tabs-link.png
[Linked content tabs disabled]: ../assets/screenshots/content-tabs.png
## 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
loading] via [additional JavaScript]:
=== ":octicons-file-code-16: docs/javascripts/tablesort.js"
=== ":octicons-file-code-16: `docs/javascripts/tablesort.js`"
``` js
document$.subscribe(function() {
@ -142,7 +142,7 @@ loading] via [additional JavaScript]:
})
```
=== ":octicons-file-code-16: mkdocs.yml"
=== ":octicons-file-code-16: `mkdocs.yml`"
``` yaml
extra_javascript:

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

@ -118,7 +118,7 @@ declarations into dedicated CSS classes:
}
</style>
=== ":octicons-file-code-16: docs/stylesheets/extra.css"
=== ":octicons-file-code-16: `docs/stylesheets/extra.css`"
``` css
.twitter {
@ -126,7 +126,7 @@ declarations into dedicated CSS classes:
}
```
=== ":octicons-file-code-16: mkdocs.yml"
=== ":octicons-file-code-16: `mkdocs.yml`"
``` yaml
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
dedicated CSS class to the icon:
=== ":octicons-file-code-16: docs/stylesheets/extra.css"
=== ":octicons-file-code-16: `docs/stylesheets/extra.css`"
``` css
@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
extra_css:

4
docs/reference/images.md
View File

@ -32,7 +32,7 @@ See additional configuration options:
### Lightbox
[:octicons-tag-24: 0.1.0][glightbox support] ·
[:octicons-tag-24: 0.1.0][Lightbox support] ·
[:octicons-cpu-24: Plugin][glightbox]
If you want to add image zoom functionality to your documentation, the
@ -53,7 +53,7 @@ plugins:
We recommend checking out the available
[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 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:
`meta_file`{ #meta-file }
[`meta_file`](#+meta.meta_file){ #+meta.meta_file }
: :octicons-milestone-24: Default: `**/.meta.yml` – This option specifies the
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`
property. Add the following lines at the top of a Markdown file:
``` sh
``` yaml
---
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
`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)!
---
@ -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
navigation sidebar. Add the following lines at the top of a Markdown file:
``` sh
``` yaml
---
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
the top of a Markdown file:
``` sh
``` yaml
---
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
lines at the top of a Markdown file:
``` sh
``` yaml
---
template: custom.html
---
@ -185,7 +185,7 @@ template: custom.html
??? 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
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:
``` 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
lines to `mkdocs.yml`:
=== ":octicons-file-code-16: docs/javascripts/mathjax.js"
=== ":octicons-file-code-16: `docs/javascripts/mathjax.js`"
``` js
window.MathJax = {
@ -44,7 +44,7 @@ lines to `mkdocs.yml`:
1. This integrates MathJax with [instant loading].
=== ":octicons-file-code-16: mkdocs.yml"
=== ":octicons-file-code-16: `mkdocs.yml`"
``` yaml
markdown_extensions:

23
docs/reference/tooltips.md
View File

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

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

@ -91,17 +91,17 @@
"type": "object",
"properties": {
"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"
},
"permalink": {
"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"
},
{
"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"
}
],
@ -113,15 +113,15 @@
"default": false
},
"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"
},
"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"
},
"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",
"enum": [
0,

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

@ -127,7 +127,7 @@
"type": "object",
"properties": {
"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": [
"view",
"accept",
@ -158,24 +158,24 @@
"type": "object",
"properties": {
"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",
"default": "!!python/name:materialx.emoji.to_svg"
},
"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",
"default": "!!python/name:materialx.emoji.twemoji"
},
"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",
"properties": {
"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",
"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"
},
"uniqueItems": true,
@ -212,11 +212,11 @@
"type": "object",
"properties": {
"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"
},
"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"
},
"auto_title_map": {
@ -224,11 +224,11 @@
"type": "object"
},
"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"
},
"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": [
"inline",
"pymdownx-inline",
@ -236,7 +236,7 @@
]
},
"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"
}
},
@ -359,7 +359,8 @@
"properties": {
"smart_mark": {
"markdownDescription": "https://facelessuser.github.io/pymdown-extensions/extensions/mark/#options",
"type": "boolean"
"type": "boolean",
"default": true
}
},
"additionalProperties": false
@ -386,45 +387,50 @@
"markdownDescription": "https://squidfunk.github.io/mkdocs-material/setup/extensions/python-markdown-extensions/#smartsymbols",
"type": "object",
"properties": {
"smart_mark": {
"markdownDescription": "https://facelessuser.github.io/pymdown-extensions/extensions/mark/#options",
"type": "boolean"
},
"trademark": {
"markdownDescription": "https://facelessuser.github.io/pymdown-extensions/extensions/mark/#options",
"type": "boolean"
"markdownDescription": "https://facelessuser.github.io/pymdown-extensions/extensions/smartsymbols/#options",
"type": "boolean",
"default": true
},
"copyright": {
"markdownDescription": "https://facelessuser.github.io/pymdown-extensions/extensions/mark/#options",
"type": "boolean"
"markdownDescription": "https://facelessuser.github.io/pymdown-extensions/extensions/smartsymbols/#options",
"type": "boolean",
"default": true
},
"registered": {
"markdownDescription": "https://facelessuser.github.io/pymdown-extensions/extensions/mark/#options",
"type": "boolean"
"markdownDescription": "https://facelessuser.github.io/pymdown-extensions/extensions/smartsymbols/#options",
"type": "boolean",
"default": true
},
"care_of": {
"markdownDescription": "https://facelessuser.github.io/pymdown-extensions/extensions/mark/#options",
"type": "boolean"
"markdownDescription": "https://facelessuser.github.io/pymdown-extensions/extensions/smartsymbols/#options",
"type": "boolean",
"default": true
},
"plusminus": {
"markdownDescription": "https://facelessuser.github.io/pymdown-extensions/extensions/mark/#options",
"type": "boolean"
"markdownDescription": "https://facelessuser.github.io/pymdown-extensions/extensions/smartsymbols/#options",
"type": "boolean",
"default": true
},
"arrows": {
"markdownDescription": "https://facelessuser.github.io/pymdown-extensions/extensions/mark/#options",
"type": "boolean"
"markdownDescription": "https://facelessuser.github.io/pymdown-extensions/extensions/smartsymbols/#options",
"type": "boolean",
"default": true
},
"notequal": {
"markdownDescription": "https://facelessuser.github.io/pymdown-extensions/extensions/mark/#options",
"type": "boolean"
"markdownDescription": "https://facelessuser.github.io/pymdown-extensions/extensions/smartsymbols/#options",
"type": "boolean",
"default": true
},
"fractions": {
"markdownDescription": "https://facelessuser.github.io/pymdown-extensions/extensions/mark/#options",
"type": "boolean"
"markdownDescription": "https://facelessuser.github.io/pymdown-extensions/extensions/smartsymbols/#options",
"type": "boolean",
"default": true
},
"ordinal_numbers": {
"markdownDescription": "https://facelessuser.github.io/pymdown-extensions/extensions/mark/#options",
"type": "boolean"
"markdownDescription": "https://facelessuser.github.io/pymdown-extensions/extensions/smartsymbols/#options",
"type": "boolean",
"default": true
}
},
"additionalProperties": false
@ -496,10 +502,10 @@
"type": "object",
"properties": {
"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",
"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",
"properties": {
"name": {
@ -561,12 +567,12 @@
"type": "object",
"properties": {
"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",
"default": true
},
"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"
}
},

28
docs/schema/extra.json
View File

@ -72,17 +72,17 @@
},
"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"
},
"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"
},
"note": {
"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"
}
},
@ -139,18 +139,18 @@
"properties": {
"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",
"default": "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"
},
"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",
"properties": {
"analytics": {
@ -166,7 +166,7 @@
"defaultSnippets": [
{
"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": {
"analytics": {
"name": "Google Analytics",
@ -178,7 +178,7 @@
},
"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",
"items": {
"oneOf": [
@ -208,7 +208,7 @@
"defaultSnippets": [
{
"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": {
"actions": [
"accept",
@ -235,12 +235,12 @@
},
"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"
},
"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"
}
},
@ -262,17 +262,17 @@
"properties": {
"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"
},
"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"
},
"lang": {
"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"
}
},

3
docs/schema/plugins.json
View File

@ -22,6 +22,9 @@
"built-in": {
"description": "Built-in plugins",
"oneOf": [
{
"$ref": "plugins/blog.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": {
"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"
},
"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"
}
},

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

@ -17,7 +17,7 @@
"properties": {
"meta_file": {
"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$",
"default": "\"**/.meta.yml\""
}

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

@ -17,7 +17,7 @@
"properties": {
"enabled": {
"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",
"default": true
}

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

@ -17,13 +17,13 @@
"properties": {
"enabled": {
"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",
"default": true
},
"externals": {
"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": [
{
"title": "Bundle external assets",
@ -42,17 +42,17 @@
},
"externals_dir": {
"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",
"default": "assets/externals"
},
"externals_exclude": {
"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",
"items": {
"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": ".*"
},
"uniqueItems": true,

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

@ -33,17 +33,17 @@
},
"separator": {
"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"
},
"jieba_dict": {
"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"
},
"jieba_dict_user": {
"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"
}
},
@ -56,7 +56,7 @@
"definitions": {
"lang": {
"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": [
{
"title": "Site search language: Arabic",

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

@ -17,23 +17,23 @@
"properties": {
"cards": {
"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",
"default": true
},
"cards_color": {
"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",
"properties": {
"fill": {
"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"
},
"text": {
"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"
}
},
@ -48,7 +48,7 @@
},
"cards_dir": {
"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",
"default": "assets/images/social"
}

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

@ -17,13 +17,13 @@
"properties": {
"tags_file": {
"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$",
"default": "tags.md"
},
"tags_extra_files": {
"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",
"patternProperties": {
"\\.md$": {

50
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>
```
You can either integrate [Giscus] on every page by overriding the `main.html`
template, or create a new template (e.g. `blog.html`) to extend from `main.html`
which includes the comment system, so you can decide for each page whether you
want to allow comments or not.
The by default empty [`comments.html`][comments] partial is the best place to
add the code snippet generated by [Giscus]. Follow the guide on [theme extension]
and [override the `comments.html` partial][overriding partials] with:
In order to integrate [Giscus], follow the guide on [theme extension] and
[override the `content` block][overriding blocks], extending the default by
calling the `super()` function at the beginning of the block:
``` html hl_lines="8"
{% extends "base.html" %}
{% block content %}
{{ super() }}
<!-- Giscus -->
``` html hl_lines="3"
{% if page.meta.comments %}
<h2 id="__comments">{{ lang.t("meta.comments") }}</h2>
<!-- Replace with generated snippet -->
<!-- Insert generated code here -->
<!-- Synchronize Giscus theme with palette -->
<script>
@ -71,7 +61,7 @@ calling the `super()` function at the beginning of the block:
var theme = palette.color.scheme === "slate" ? "dark" : "light"
giscus.setAttribute("data-theme", theme) // (1)!
}
/* Register event handlers after documented loaded */
document.addEventListener("DOMContentLoaded", function() {
var ref = document.querySelector("[data-md-component=palette]")
@ -90,7 +80,7 @@ calling the `super()` function at the beginning of the block:
})
})
</script>
{% endblock %}
{% endif %}
```
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.
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
now see the [Giscus] comment system at the bottom of each page. If you created
a new, separate template, you can enable Giscus by [setting the page template]
via front matter.
configuration tool in the previous step. If you copied the snippet from above,
you can enable comments on a page by setting the `comments` front matter
property to `true`:
``` 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
[theme extension]: ../customization.md#extending-the-theme
[overriding blocks]: ../customization.md#overriding-blocks
[setting the page template]: ../reference/index.md#setting-the-page-template
[comments]: https://github.com/squidfunk/mkdocs-material/blob/master/src/partials/comments.html
[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
[:octicons-tag-24: 0.1.0][repo_url support] ·
[:octicons-tag-24: 0.1.0][Repository support] ·
:octicons-milestone-24: Default: _none_
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
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
[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
#### 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_
`Bitbucket`
@ -56,14 +56,14 @@ _repository name_ automatically. If you wish to customize the name, set
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
#### Repository icon
[:octicons-tag-24: 5.0.0][icon.repo support] ·
[:octicons-tag-24: 5.0.0][Repository icon support] ·
: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
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-solid-trash: – `fontawesome/solid/trash`
[icon.repo support]: https://github.com/squidfunk/mkdocs-material/releases/tag/5.0.0
[icon.repo default]: https://github.com/squidfunk/mkdocs-material/blob/master/material/.icons/fontawesome/brands/git-alt.svg
[Repository icon support]: https://github.com/squidfunk/mkdocs-material/releases/tag/5.0.0
[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
#### 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_
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 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
[GitHub]: https://github.com/
[GitLab]: https://about.gitlab.com/
@ -140,7 +159,7 @@ links to all [contributors] or [authors] involved.
#### 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]
The [git-revision-date-localized] plugin adds support for adding the date of
@ -161,7 +180,7 @@ plugins:
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
displayed. Valid values are `date`, `datetime`, `iso_date`, `iso_datetime`
@ -173,10 +192,9 @@ The following configuration options are supported:
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
date at the bottom of the page:
@ -186,7 +204,7 @@ The following configuration options are supported:
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
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
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
[enable_creation_date support]: https://github.com/squidfunk/mkdocs-material/releases/tag/7.1.4
#### Document contributors
@ -238,9 +255,9 @@ plugins:
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
documentation. The slug must follow the pattern `<username>/<repository>`:
@ -250,7 +267,7 @@ The following configuration options are supported:
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
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:
`enabled`{ #enabled }
[`enabled`](#+offline.enabled){ #+offline.enabled }
: :octicons-milestone-24: Default: `true` – This option specifies whether
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
[:octicons-tag-24: 5.2.0][palette.scheme support] ·
[:octicons-tag-24: 5.2.0][Color scheme support] ·
:octicons-milestone-24: Default: `default`
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>
[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
[:octicons-tag-24: 0.2.0][palette.primary support] ·
[:octicons-tag-24: 0.2.0][Primary color support] ·
:octicons-milestone-24: Default: `indigo`
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>
[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
[:octicons-tag-24: 0.2.0][palette.accent support] ·
[:octicons-tag-24: 0.2.0][Accent color support] ·
:octicons-milestone-24: Default: `indigo`
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>
[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
[:octicons-tag-24: 7.1.0][palette.toggle support] ·
[:octicons-tag-24: 7.1.0][Color palette toggle support] ·
:octicons-milestone-24: Default: _none_
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:
`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
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-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
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.primary]: #primary-color
[palette.accent]: #accent-color
@ -236,7 +236,7 @@ The following properties must be set for each toggle:
### 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_
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
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
@ -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
add:
=== ":octicons-file-code-16: docs/stylesheets/extra.css"
=== ":octicons-file-code-16: `docs/stylesheets/extra.css`"
``` css
:root > * {
@ -337,7 +337,7 @@ add:
}
```
=== ":octicons-file-code-16: mkdocs.yml"
=== ":octicons-file-code-16: `mkdocs.yml`"
``` yaml
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
in the [color schemes][palette.scheme] section:
=== ":octicons-file-code-16: docs/stylesheets/extra.css"
=== ":octicons-file-code-16: `docs/stylesheets/extra.css`"
``` css
[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
theme:

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

@ -15,7 +15,7 @@ or another destination should be used.
### Regular font
[:octicons-tag-24: 0.1.2][font support] ·
[:octicons-tag-24: 0.1.2][Font support] ·
:octicons-milestone-24: Default: [`Roboto`][Roboto]
The regular font is used for all body copy, headlines, and essentially
@ -31,11 +31,11 @@ theme:
The typeface will be loaded in 300, 400, _400i_ and __700__.
[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
[:octicons-tag-24: 0.1.2][font support] ·
[:octicons-tag-24: 0.1.2][Font support] ·
:octicons-milestone-24: Default: [`Roboto Mono`][Roboto Mono]
The _monospaced font_ is used for code blocks and can be configured separately.
@ -54,7 +54,7 @@ The typeface will be loaded in 400.
### Autoloading
[:octicons-tag-24: 1.0.0][font=false support] ·
[:octicons-tag-24: 1.0.0][Autoloading support] ·
:octicons-milestone-24: Default: _none_
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.
[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
## 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
corresponding `@font-face` definition:
=== ":octicons-file-code-16: docs/stylesheets/extra.css"
=== ":octicons-file-code-16: `docs/stylesheets/extra.css`"
``` css
@font-face {
@ -93,7 +93,7 @@ corresponding `@font-face` definition:
}
```
=== ":octicons-file-code-16: mkdocs.yml"
=== ":octicons-file-code-16: `mkdocs.yml`"
``` yaml
extra_css:

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

@ -13,7 +13,7 @@ available.
### Site language
[:octicons-tag-24: 1.12.0][language support] ·
[:octicons-tag-24: 1.12.0][Site language support] ·
:octicons-milestone-24: Default: `en`
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
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
[language selector]: #site-language-selector
[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
[:octicons-tag-24: 7.0.0][alternate support] ·
[:octicons-tag-24: 7.0.0][Site language selector support] ·
:octicons-milestone-24: Default: _none_ ·
:octicons-beaker-24: Experimental
@ -133,35 +133,35 @@ extra:
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
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
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
the `hreflang` attribute of the link, improving discoverability via search
engines.
[![Language selector preview]][Language selector preview]
[alternate support]: https://github.com/squidfunk/mkdocs-material/releases/tag/7.0.0
[Site 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
[ISO 639-1 language code]: https://en.wikipedia.org/wiki/List_of_ISO_639-1_codes
[Language selector preview]: ../assets/screenshots/language-selection.png
### Directionality
[:octicons-tag-24: 2.5.0][direction support] ·
[:octicons-tag-24: 2.5.0][Directionality support] ·
:octicons-milestone-24: Default: _automatically set_
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>
[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
@ -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
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
<!-- 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
to override for your language and add them here.
=== ":octicons-file-code-16: mkdocs.yml"
=== ":octicons-file-code-16: `mkdocs.yml`"
``` yaml
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
[:octicons-tag-24: 0.1.0][logo support] ·
:octicons-milestone-24: Default: [`material/library`][logo default]
[:octicons-tag-24: 0.1.0][Logo support] ·
:octicons-milestone-24: Default: :material-library: – `material/library`
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.
@ -48,8 +48,7 @@ Add the following lines to `mkdocs.yml`:
</div>
</div>
[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
[Logo support]: https://github.com/squidfunk/mkdocs-material/releases/tag/0.1.0
[icon search]: ../reference/icons-emojis.md#search
Normally, the logo in the header and sidebar links to the homepage of the
@ -63,8 +62,8 @@ extra:
### Favicon
[:octicons-tag-24: 0.1.0][favicon support] ·
:octicons-milestone-24: Default: [`assets/images/favicon.png`][favicon default]
[:octicons-tag-24: 0.1.0][Favicon support] ·
:octicons-milestone-24: Default: [`assets/images/favicon.png`][Favicon default]
The favicon can be changed to a path pointing to a user-provided image, which
must be located in the `docs` folder. Add the following lines to `mkdocs.yml`:
@ -74,8 +73,8 @@ theme:
favicon: images/favicon.png
```
[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 support]: https://github.com/squidfunk/mkdocs-material/releases/tag/0.1.0
[Favicon default]: https://github.com/squidfunk/mkdocs-material/blob/master/material/assets/images/favicon.png
## Customization

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
automatically downloaded for [self-hosting].
[cookie consent]: #native-cookie-consent
[cookie consent]: #cookie-consent
[tracking]: setting-up-site-analytics.md
[self-hosting]: #built-in-privacy-plugin
## 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-beaker-24: Experimental
@ -41,19 +41,19 @@ extra:
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
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
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
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]
can be used from JavaScript.
`actions`{ #consent-actions }
[`actions`](#+consent.actions){ #+consent.actions }
: :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
@ -121,11 +121,11 @@ The following properties are available:
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
[cookie consent support]: https://github.com/squidfunk/mkdocs-material/releases/tag/8.4.0
[cookie consent enabled]: ../assets/screenshots/consent.png
[Cookie consent support]: https://github.com/squidfunk/mkdocs-material/releases/tag/8.4.0
[Cookie consent enabled]: ../assets/screenshots/consent.png
#### Change cookie settings
@ -168,7 +168,7 @@ plugins:
The following configuration options are available:
`enabled`{ #enabled }
[`enabled`](#+privacy.enabled){ #+privacy.enabled }
: :octicons-milestone-24: Default: `true` – This option specifies whether
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]
```
`externals`{ #externals }
[`externals`](#+privacy.externals){ #+privacy.externals }
: :octicons-milestone-24: Default: `bundle` – This option specifies what the
plugin should do when encountering external assets. There are two options:
@ -204,7 +204,7 @@ The following configuration options are available:
[customization]: ../customization.md
[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
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_exclude`{ #externals-exclude }
[`externals_exclude`](#+privacy.externals_exclude){ #+privacy.externals_exclude }
: :octicons-milestone-24: Default: _none_ – This option allows to exclude
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
check whether the user accepted it:
=== ":octicons-file-code-16: docs/javascripts/consent.js"
=== ":octicons-file-code-16: `docs/javascripts/consent.js`"
``` js
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
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
of [additional JavaScript]:
=== ":octicons-file-code-16: docs/javascripts/mathjax.js"
=== ":octicons-file-code-16: `docs/javascripts/mathjax.js`"
``` js
window.MathJax = {
@ -58,7 +58,7 @@ of [additional JavaScript]:
})
```
=== ":octicons-file-code-16: mkdocs.yml"
=== ":octicons-file-code-16: `mkdocs.yml`"
``` yaml
extra_javascript:
@ -154,7 +154,7 @@ markdown_extensions:
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
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:
`emoji_index`{ #emoji-index }
[`emoji_index`](#+pymdownx.emoji.emoji_index){ #+pymdownx.emoji.emoji_index }
: :octicons-milestone-24: Default: `emojione` – This option defines which set
of emojis is used for rendering. Note that the use of `emojione` is not
@ -249,7 +249,7 @@ The following configuration options are supported:
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
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
```
`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
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:
`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
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
sheet] in `mkdocs.yml`:
=== ":octicons-file-code-16: docs/javascripts/highlight.js"
=== ":octicons-file-code-16: `docs/javascripts/highlight.js`"
``` js
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
extra_javascript:
@ -371,7 +371,7 @@ The following configuration options are supported:
syntax highlighting using [Pygments], so they don't apply if `use_pygments`
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
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
```
`linenums`{ #highlight-linenums }
[`linenums`](#+pymdownx.highlight.linenums){ #+pymdownx.highlight.linenums }
: :octicons-milestone-24: Default: `false` – This option will add line numbers
to _all_ code blocks. If you wish to add line numbers to _some_, but not all
@ -397,7 +397,7 @@ The following configuration options are supported:
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
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`
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:
Default: `false` – If a code blocks contains line numbers, enabling this
@ -579,7 +579,7 @@ markdown_extensions:
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
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:
`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-milestone-24: Default: `false` · :octicons-alert-24: Required –
This option enables the content tabs [alternate style], which has
:octicons-milestone-24: Default: `false` · :octicons-alert-24: __Required__
– This option enables the content tabs [alternate style], which has
[better behavior on mobile viewports], and is the only supported style:
``` yaml
@ -692,7 +692,7 @@ markdown_extensions:
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
style of checkboxes, replacing native checkbox styles with beautiful icons,
@ -704,7 +704,7 @@ The following configuration options are supported:
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
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:
`title`{ #toc-title }
[`title`](#+toc.title){ #+toc.title }
: [:octicons-tag-24: 7.3.5][title support] ·
:octicons-milestone-24: Default: _automatically set_ – This option sets the
@ -210,7 +210,7 @@ The following configuration options are supported:
title: On this page
```
`permalink`{ #toc-permalink }
[`permalink`](#+toc.permalink){ #+toc.permalink }
: :octicons-milestone-24: Default: `false` – This option adds an anchor link
containing the paragraph symbol `¶` or another custom symbol at the end of
@ -233,7 +233,7 @@ The following configuration options are supported:
permalink: ⚓︎
```
`permalink_title`{ #toc-permalink-title }
[`permalink_title`](#+toc.permalink_title){ #+toc.permalink_title }
: :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.
@ -246,7 +246,7 @@ The following configuration options are supported:
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
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
```
`toc_depth`{ #toc-depth }
[`toc_depth`](#+toc.toc_depth){ #+toc.toc_depth }
: :octicons-milestone-24: Default: `6` – Define the range of levels to be
included in the table of contents. This may be useful for project

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
documentation. Material for MkDocs provides a multitude of options to configure
the behavior of navigational elements, including [tabs][navigation.tabs] and
[sections][navigation.sections], and its flag-ship feature: [instant loading]
[navigation.instant].
the behavior of navigational elements, including [tabs] and [sections], and one
of its flag-ship feature: [instant loading].
[navigation.tabs]: #navigation-tabs
[navigation.sections]: #navigation-sections
[navigation.instant]: #instant-loading
[tabs]: #navigation-tabs
[sections]: #navigation-sections
[instant loading]: #instant-loading
## Configuration
### 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
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
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
### Anchor tracking
@ -59,7 +58,7 @@ theme:
### 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
When tabs are enabled, top-level sections are rendered in a menu layer below
@ -81,21 +80,21 @@ theme:
- 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 enabled]: ../assets/screenshots/navigation-tabs.png
[navigation.tabs disabled]: ../assets/screenshots/navigation.png
[Navigation tabs support]: https://github.com/squidfunk/mkdocs-material/releases/tag/1.1.0
[Navigation tabs enabled]: ../assets/screenshots/navigation-tabs.png
[Navigation tabs disabled]: ../assets/screenshots/navigation.png
#### Sticky navigation tabs
[:octicons-tag-24: 7.3.0][navigation.tabs.sticky support] ·
[:octicons-tag-24: 7.3.0][Sticky navigation tabs support] ·
:octicons-unlock-24: Feature flag
When sticky tabs are enabled, navigation tabs will lock below the header and
@ -109,21 +108,21 @@ theme:
- 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
[navigation.tabs.sticky enabled]: ../assets/screenshots/navigation-tabs-sticky.png
[navigation.tabs.sticky disabled]: ../assets/screenshots/navigation-tabs-collapsed.png
[Sticky navigation tabs support]: https://github.com/squidfunk/mkdocs-material/releases/tag/7.3.0
[Sticky navigation tabs enabled]: ../assets/screenshots/navigation-tabs-sticky.png
[Sticky navigation tabs disabled]: ../assets/screenshots/navigation-tabs-collapsed.png
### 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
When sections are enabled, top-level sections are rendered as groups in the
@ -136,26 +135,25 @@ theme:
- 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 enabled]: ../assets/screenshots/navigation-sections.png
[navigation.sections disabled]: ../assets/screenshots/navigation.png
[Navigation sections support]: https://github.com/squidfunk/mkdocs-material/releases/tag/6.2.0
[Navigation sections enabled]: ../assets/screenshots/navigation-sections.png
[Navigation sections disabled]: ../assets/screenshots/navigation.png
Both feature flags, [`navigation.tabs`][navigation.tabs] and
[`navigation.sections`][navigation.sections], can be combined with each other.
If both feature flags are enabled, sections are rendered for level 2 navigation
items.
Both feature flags, [`navigation.tabs`][tabs] and
[`navigation.sections`][sections], can be combined with each other. If both
feature flags are enabled, sections are rendered for level 2 navigation items.
### 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
When expansion is enabled, the left sidebar will expand all collapsible
@ -168,17 +166,17 @@ theme:
- 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.expand enabled]: ../assets/screenshots/navigation-expand.png
[navigation.expand disabled]: ../assets/screenshots/navigation.png
[Navigation expansion support]: https://github.com/squidfunk/mkdocs-material/releases/tag/6.2.0
[Navigation expansion enabled]: ../assets/screenshots/navigation-expand.png
[Navigation expansion disabled]: ../assets/screenshots/navigation.png
### Navigation pruning
@ -209,7 +207,7 @@ page in that section (or the section index page).
### 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
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],
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
`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
```
[navigation.indexes support]: https://github.com/squidfunk/mkdocs-material/releases/tag/7.3.0
[navigation.indexes enabled]: ../assets/screenshots/navigation-index-on.png
[navigation.indexes disabled]: ../assets/screenshots/navigation-index-off.png
[Section index pages support]: https://github.com/squidfunk/mkdocs-material/releases/tag/7.3.0
[Section index pages enabled]: ../assets/screenshots/navigation-index-on.png
[Section index pages disabled]: ../assets/screenshots/navigation-index-off.png
[toc.integrate]: #navigation-integration
### Table of contents
@ -273,7 +271,7 @@ theme:
#### 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
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
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
[toc.integrate support]: https://github.com/squidfunk/mkdocs-material/releases/tag/7.3.0
[toc.integrate enabled]: ../assets/screenshots/toc-integrate.png
[toc.integrate disabled]: ../assets/screenshots/navigation-tabs.png
[Navigation integration support]: https://github.com/squidfunk/mkdocs-material/releases/tag/7.3.0
[Navigation integration enabled]: ../assets/screenshots/toc-integrate.png
[Navigation integration disabled]: ../assets/screenshots/navigation-tabs.png
[navigation.indexes]: #section-index-pages
### 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
A back-to-top button can be shown when the user, after scrolling down, starts
@ -319,7 +317,7 @@ theme:
- 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
@ -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
Markdown file:
``` sh
``` yaml
---
hide:
- navigation
@ -342,19 +340,19 @@ hide:
=== "Hide navigation"
[![hide.navigation enabled]][hide.navigation enabled]
[![Hide navigation enabled]][Hide navigation enabled]
=== "Hide table of contents"
[![hide.toc enabled]][hide.toc enabled]
[![Hide table of contents enabled]][Hide table of contents enabled]
=== "Hide both"
[![hide.* enabled]][hide.* enabled]
[![Hide both enabled]][Hide both enabled]
[hide.navigation enabled]: ../assets/screenshots/hide-navigation.png
[hide.toc enabled]: ../assets/screenshots/hide-toc.png
[hide.* enabled]: ../assets/screenshots/hide-navigation-toc.png
[Navigation hiding enabled]: ../assets/screenshots/hide-navigation.png
[Hide table of contents enabled]: ../assets/screenshots/hide-toc.png
[Hide both enabled]: ../assets/screenshots/hide-navigation-toc.png
## Customization
@ -363,7 +361,7 @@ hide:
Material for MkDocs includes several keyboard shortcuts that make it possible
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
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
* ++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
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
your custom event listener:
=== ":octicons-file-code-16: docs/javascripts/shortcuts.js"
=== ":octicons-file-code-16: `docs/javascripts/shortcuts.js`"
``` js
keyboard$.subscribe(function(key) {
@ -401,7 +399,7 @@ your custom event listener:
underlying event, so the keypress will not propagate further and
touch other event listeners.
=== ":octicons-file-code-16: mkdocs.yml"
=== ":octicons-file-code-16: `mkdocs.yml`"
``` yaml
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
of CSS:
=== ":octicons-file-code-16: docs/stylesheets/extra.css"
=== ":octicons-file-code-16: `docs/stylesheets/extra.css`"
``` css
.md-grid {
@ -438,7 +436,7 @@ of CSS:
}
```
=== ":octicons-file-code-16: mkdocs.yml"
=== ":octicons-file-code-16: `mkdocs.yml`"
``` yaml
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].
[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
## Configuration
@ -70,7 +70,7 @@ following lines to `mkdocs.yml`:
### 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-beaker-24: Experimental
@ -169,9 +169,9 @@ integrated with the [cookie consent] feature[^1].
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
with the theme][custom icons], or the build will not succeed. Some popular
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-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
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
that is transmitted to Google Analytics[^2] (or any custom integration).
[^2]:
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.
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.
@ -221,7 +221,7 @@ The following properties are available for each rating:
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
[analytics]: #google-analytics
[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:
``` sh
``` yaml
---
hide:
- 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
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
<script>
@ -276,7 +276,7 @@ used to configure the custom integration via `mkdocs.yml`:
observable to listen for navigation events, which always emits the
current `URL`.
=== ":octicons-file-code-16: mkdocs.yml"
=== ":octicons-file-code-16: `mkdocs.yml`"
``` yaml
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
[additional JavaScript]:
=== ":octicons-file-code-16: docs/javascripts/feedback.js"
=== ":octicons-file-code-16: `docs/javascripts/feedback.js`"
``` js
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
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
[:octicons-tag-24: 0.1.0][search support] ·
[:octicons-tag-24: 0.1.0][Search support] ·
:octicons-cpu-24: Plugin
The built-in search plugin integrates seamlessly with Material for MkDocs,
@ -32,7 +32,7 @@ plugins:
The following configuration options are supported:
`lang`{ #search-lang }
[`lang`](#+search.lang){ #+search.lang }
: :octicons-milestone-24: Default: _automatically set_ – This option allows
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
best result.
`separator`{ #search-separator }
[`separator`](#+search.separator){ #+search.separator }
: :octicons-milestone-24: Default: _automatically set_ – The separator for
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>
`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:
Deprecated · :octicons-trash-24: 8.0.0 · :octicons-milestone-24: Default:
@ -135,7 +135,7 @@ The following configuration options are supported:
</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-languages]: https://github.com/MihaiValentin/lunr-languages
[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
[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
[50% smaller]: ../blog/2021/search-better-faster-smaller.md#benchmarks
[50% smaller]: ../blog/posts/search-better-faster-smaller.md#benchmarks
#### 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
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:
Default: _none_ – This option allows for specifying a [custom dictionary]
@ -180,7 +180,7 @@ configuration options are available:
- [dict.txt.small] – 占用内存较小的词典文件
- [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:
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
technical terms.
[chinese search]: ../blog/2022/chinese-search-support.md
[chinese search]: ../blog/posts/chinese-search-support.md
[jieba]: https://pypi.org/project/jieba/
[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
@ -223,9 +223,9 @@ occurrences inside those blocks:
![search preview before]
[Insiders]: ../insiders/index.md
[new search plugin]: ../blog/2021/search-better-faster-smaller.md
[search preview now]: ../blog/2021/search-better-faster-smaller/search-preview-now.png
[search preview before]: ../blog/2021/search-better-faster-smaller/search-preview-before.png
[new search plugin]: ../blog/posts/search-better-faster-smaller.md
[search preview now]: ../blog/posts/search-better-faster-smaller/search-preview-now.png
[search preview before]: ../blog/posts/search-better-faster-smaller/search-preview-before.png
### Tokenizer lookahead
@ -290,13 +290,13 @@ The following section explains what can be achieved with tokenizer lookahead:
[separator]: #search-separator
[words are split at case changes]: ?q=searchHighlight
[tokenize case changes]: ../blog/2021/search-better-faster-smaller.md#case-changes
[tokenize version numbers]: ../blog/2021/search-better-faster-smaller.md#version-numbers
[tokenize html-xml tags]: ../blog/2021/search-better-faster-smaller.md#htmlxml-tags
[tokenize case changes]: ../blog/posts/search-better-faster-smaller.md#case-changes
[tokenize version numbers]: ../blog/posts/search-better-faster-smaller.md#version-numbers
[tokenize html-xml tags]: ../blog/posts/search-better-faster-smaller.md#htmlxml-tags
### 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-beaker-24: Experimental
@ -310,15 +310,15 @@ theme:
- search.suggest
```
Searching for [:octicons-search-24: search su][search.suggest example] yields
^^search suggestions^^ as a suggestion.
Searching for [:octicons-search-24: search su][Search suggestions example]
yields ^^search suggestions^^ as a suggestion.
[search.suggest support]: https://github.com/squidfunk/mkdocs-material/releases/tag/7.2.0
[search.suggest example]: ?q=search+su
[Search suggestions support]: https://github.com/squidfunk/mkdocs-material/releases/tag/7.2.0
[Search suggestions example]: ?q=search+su
### 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-beaker-24: Experimental
@ -332,15 +332,15 @@ theme:
- 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.
[search.highlight support]: https://github.com/squidfunk/mkdocs-material/releases/tag/7.2.0
[search.highlight example]: ../reference/code-blocks.md?h=code+blocks
[Search highlighting support]: https://github.com/squidfunk/mkdocs-material/releases/tag/7.2.0
[Search highlighting example]: ../reference/code-blocks.md?h=code+blocks
### 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-beaker-24: Experimental
@ -357,7 +357,7 @@ theme:
When a user clicks the share button, the URL is automatically copied to the
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
@ -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
Markdown file:
``` sh
``` yaml
---
search:
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
Markdown file:
``` sh
``` yaml
---
search:
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
heading:
=== ":octicons-file-code-16: docs/page.md"
=== ":octicons-file-code-16: `docs/page.md`"
``` markdown
# Document title
@ -425,7 +425,7 @@ heading:
The content of this section is excluded
```
=== ":octicons-codescan-16: search_index.json"
=== ":octicons-codescan-16: `search_index.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
inline- or block-level element:
=== ":octicons-file-code-16: docs/page.md"
=== ":octicons-file-code-16: `docs/page.md`"
``` markdown
# Document title
@ -464,7 +464,7 @@ inline- or block-level element:
{ data-search-exclude }
```
=== ":octicons-codescan-16: search_index.json"
=== ":octicons-codescan-16: `search_index.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
a link to your project documentation is shared on social media. Material for
MkDocs can generate beautiful social cards automatically, using the [colors]
[palette.primary], [fonts][font.text] and [logo][^1] defined in `mkdocs.yml`,
MkDocs can generate beautiful social cards automatically, using the [colors],
[fonts] and [logo][^1] defined in `mkdocs.yml`,
e.g.:
<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.
[palette.primary]: changing-the-colors.md#primary-color
[font.text]: changing-the-fonts.md#regular-font
[colors]: changing-the-colors.md#primary-color
[fonts]: changing-the-fonts.md#regular-font
[logo]: changing-the-logo-and-icons.md#logo
[Social cards preview]: ../assets/screenshots/social-cards.png
[setting up site analytics]: setting-up-site-analytics.md
@ -59,7 +59,7 @@ plugins:
The following configuration options are available:
`cards`{ #cards }
[`cards`](#+social.cards){ #+social.cards }
: :octicons-milestone-24: Default: `true` – This option specifies whether
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_color`{ #cards-color }
[`cards_color`](#+social.cards_color){ #+social.cards_color }
: [:octicons-tag-24: insiders-2.13.0][Insiders] · :octicons-milestone-24:
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].
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:
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_dir`{ #cards-dir }
[`cards_dir`](#+social.cards_dir){ #+social.cards_dir }
: :octicons-milestone-24: Default: `assets/images/social` – This option
specifies where the generated social card images will be written to. It's
@ -111,13 +111,15 @@ The following configuration options are available:
``` yaml
plugins:
- social:
cards_dir: assets/images/social
cards_dir: path/to/folder
```
[Insiders]: ../insiders/index.md
[dependencies]: #dependencies
[site_url]: https://www.mkdocs.org/user-guide/configuration/#site_url
[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
[CSS color keywords]: https://developer.mozilla.org/en-US/docs/Web/CSS/color_value#color_keywords
[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
[:octicons-tag-24: 8.2.0][tags support] ·
[:octicons-tag-24: 8.2.0][Tags support] ·
:octicons-cpu-24: Plugin ·
:octicons-beaker-24: Experimental
@ -30,7 +30,7 @@ plugins:
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
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
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:
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.
[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 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
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
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
arbitrary content before and after the marker:
[![Tags index][9]][9]
[![Tags index][tags index enabled]][tags index enabled]
[tags.tags_file]: #tags-file
[9]: ../assets/screenshots/tags-index.png
[tags index enabled]: ../assets/screenshots/tags-index.png
### 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
front matter `hide` property:
``` sh
``` yaml
---
hide:
- tags

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

@ -14,7 +14,7 @@ configure via `mkdocs.yml`.
### Social links
[:octicons-tag-24: 1.0.0][social support] ·
[:octicons-tag-24: 1.0.0][Social links support] ·
:octicons-milestone-24: Default: _none_
Social links are rendered next to the copyright notice as part of the
@ -41,14 +41,12 @@ extra:
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:
Default: _none_ · :octicons-alert-24: Required – This property must contain
a valid path to any icon bundled with the theme, or the
build will not succeed. Some popular choices:
: :octicons-milestone-24: Default: _none_ · :octicons-alert-24: __Required__ –
This property must contain a valid path to any icon bundled with the theme,
or the build will not succeed. Some popular choices:
* :fontawesome-brands-behance: – `fontawesome/brands/behance`
* :fontawesome-brands-docker: – `fontawesome/brands/docker`
* :fontawesome-brands-facebook: – `fontawesome/brands/facebook`
* :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-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
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>
```
`name`{ #social-name }
[`name`](#+social.name){ #+social.name }
: [:octicons-tag-24: 5.1.5][social.name support] · :octicons-milestone-24:
Default: _domain name from_ `link`_, if available_ – This property is used
as the link's `title` attribute and can be set to a discernable name to
improve accessibility:
: :octicons-milestone-24: Default: _domain name from_ `link`_, if available_ –
This property is used as the link's `title` attribute and can be set to a
discernable name to improve accessibility:
``` yaml
extra:
@ -100,9 +97,7 @@ The following properties are available for each link:
```
[icon search]: ../reference/icons-emojis.md#search
[social 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
[Social links support]: https://github.com/squidfunk/mkdocs-material/releases/tag/1.0.0
### 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
Markdown file:
``` sh
``` yaml
---
hide:
- footer
@ -174,7 +169,7 @@ hide:
:octicons-file-symlink-file-24: Customization
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`.
[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
[:octicons-tag-24: 7.0.0][version support] ·
[:octicons-tag-24: 7.0.0][Versioning support] ·
[:octicons-package-24: Utility][mike]
[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
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 example]: https://squidfunk.github.io/mkdocs-material-example-versioning/
[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
potential changes
=== ":octicons-file-code-16: base.html"
=== ":octicons-file-code-16: `base.html`"
``` diff
@@ -13,11 +13,6 @@
@ -363,7 +363,7 @@ matches the new structure:
</div>
```
=== ":octicons-file-code-16: partials/copyright.html"
=== ":octicons-file-code-16: `partials/copyright.html`"
``` diff
@@ -0,0 +1,16 @@
@ -385,7 +385,7 @@ matches the new structure:
+</div>
```
=== ":octicons-file-code-16: partials/footer.html"
=== ":octicons-file-code-16: `partials/footer.html`"
``` diff
@@ -41,21 +40,10 @@
@ -416,7 +416,7 @@ matches the new structure:
</footer>
```
=== ":octicons-file-code-16: partials/social.html"
=== ":octicons-file-code-16: `partials/social.html`"
``` diff
@@ -4,17 +4,15 @@
@ -492,7 +492,7 @@ matches the new structure:
- If you've overridden a __template__, check the respective `*.html` file for
potential changes
=== ":octicons-file-code-16: base.html"
=== ":octicons-file-code-16: `base.html`"
``` diff
@@ -61,7 +61,7 @@
@ -581,7 +581,7 @@ matches the new structure:
{% endfor %}
```
=== ":octicons-file-code-16: partials/footer.html"
=== ":octicons-file-code-16: `partials/footer.html`"
``` diff
- <div class="md-footer-nav">
@ -653,7 +653,7 @@ matches the new structure:
<div class="md-footer-meta__inner md-grid">
```
=== ":octicons-file-code-16: partials/header.html"
=== ":octicons-file-code-16: `partials/header.html`"
``` diff
@@ -6,21 +6,21 @@
@ -725,7 +725,7 @@ matches the new structure:
{% endif %}
```
=== ":octicons-file-code-16: partials/source.html"
=== ":octicons-file-code-16: `partials/source.html`"
``` diff
@@ -4,5 +4,5 @@
@ -737,7 +737,7 @@ matches the new structure:
{% include ".icons/" ~ icon ~ ".svg" %}
```
=== ":octicons-file-code-16: partials/toc.html"
=== ":octicons-file-code-16: `partials/toc.html`"
``` diff
@@ -12,7 +12,7 @@
@ -808,7 +808,7 @@ matches the new structure:
- If you've overridden a __template__, check the respective `*.html` file for
potential changes
=== ":octicons-file-code-16: base.html"
=== ":octicons-file-code-16: `base.html`"
``` diff
@@ -22,13 +22,6 @@
@ -978,7 +978,7 @@ matches the new structure:
{%- endfor -%}
```
=== ":octicons-file-code-16: partials/hero.html"
=== ":octicons-file-code-16: `partials/hero.html`"
``` diff
@@ -1,12 +0,0 @@
@ -996,7 +996,7 @@ matches the new structure:
-</div>
```
=== ":octicons-file-code-16: partials/source-link"
=== ":octicons-file-code-16: `partials/source-link`"
``` diff
@@ -1,14 +0,0 @@
@ -1170,7 +1170,7 @@ matches the new structure:
- If you've overridden a __template__, check the respective `*.html` file for
potential changes
=== ":octicons-file-code-16: base.html"
=== ":octicons-file-code-16: `base.html`"
``` diff
@@ -4,7 +4,6 @@
@ -1419,7 +1419,7 @@ matches the new structure:
{% endfor %}
```
=== ":octicons-file-code-16: partials/footer.html"
=== ":octicons-file-code-16: `partials/footer.html`"
``` diff
@@ -5,34 +5,34 @@
@ -1470,7 +1470,7 @@ matches the new structure:
{% endif %}
```
=== ":octicons-file-code-16: partials/header.html"
=== ":octicons-file-code-16: `partials/header.html`"
``` diff
@@ -4,51 +4,43 @@
@ -1559,7 +1559,7 @@ matches the new structure:
</header>
```
=== ":octicons-file-code-16: partials/hero.html"
=== ":octicons-file-code-16: `partials/hero.html`"
``` diff
@@ -4,9 +4,8 @@
@ -1572,7 +1572,7 @@ matches the new structure:
<div class="{{ class }}" data-md-component="hero">
```
=== ":octicons-file-code-16: partials/language.html"
=== ":octicons-file-code-16: `partials/language.html`"
``` diff
@@ -4,12 +4,4 @@
@ -1590,7 +1590,7 @@ matches the new structure:
+{% 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
@@ -0,0 +1,9 @@
@ -1605,7 +1605,7 @@ matches the new structure:
+{% endif %}
```
=== ":octicons-file-code-16: partials/nav-item.html"
=== ":octicons-file-code-16: `partials/nav-item.html`"
``` diff
@@ -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">
```
=== ":octicons-file-code-16: partials/nav.html"
=== ":octicons-file-code-16: `partials/nav.html`"
``` diff
@@ -4,14 +4,10 @@
@ -1658,7 +1658,7 @@ matches the new structure:
</label>
```
=== ":octicons-file-code-16: partials/search.html"
=== ":octicons-file-code-16: `partials/search.html`"
``` diff
@@ -6,15 +6,18 @@
@ -1686,7 +1686,7 @@ matches the new structure:
</div>
```
=== ":octicons-file-code-16: partials/social.html"
=== ":octicons-file-code-16: `partials/social.html`"
``` diff
@@ -4,9 +4,12 @@
@ -1705,7 +1705,7 @@ matches the new structure:
{% endif %}
```
=== ":octicons-file-code-16: partials/source-date.html"
=== ":octicons-file-code-16: `partials/source-date.html`"
``` diff
@@ -0,0 +1,15 @@
@ -1726,7 +1726,7 @@ matches the new structure:
+</div>
```
=== ":octicons-file-code-16: partials/source-link.html"
=== ":octicons-file-code-16: `partials/source-link.html`"
``` diff
@@ -0,0 +1,13 @@
@ -1745,7 +1745,7 @@ matches the new structure:
+</a>
```
=== ":octicons-file-code-16: partials/source.html"
=== ":octicons-file-code-16: `partials/source.html`"
``` diff
@@ -4,24 +4,11 @@
@ -1778,7 +1778,7 @@ matches the new structure:
</div>
```
=== ":octicons-file-code-16: partials/tabs-item.html"
=== ":octicons-file-code-16: `partials/tabs-item.html`"
``` diff
@@ -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">
```
=== ":octicons-file-code-16: partials/tabs.html"
=== ":octicons-file-code-16: `partials/tabs.html`"
``` diff
@@ -5,7 +5,7 @@
@ -1803,7 +1803,7 @@ matches the new structure:
{% for nav_item in nav %}
```
=== ":octicons-file-code-16: partials/toc-item.html"
=== ":octicons-file-code-16: `partials/toc-item.html`"
``` diff
@@ -6,7 +6,7 @@
@ -1817,7 +1817,7 @@ matches the new structure:
{% include "partials/toc-item.html" %}
```
=== ":octicons-file-code-16: partials/toc.html"
=== ":octicons-file-code-16: `partials/toc.html`"
``` diff
@@ -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" %}
{% endif %}
{% 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 analytics: setup/setting-up-site-analytics.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 versioning: setup/setting-up-versioning.md
- Setting up the header: setup/setting-up-the-header.md
@ -221,8 +222,9 @@ nav:
- Blog:
- blog/index.md
- 2022:
- blog/2022/chinese-search-support.md
- blog/posts/blog-support-just-landed.md
- blog/posts/chinese-search-support.md
- 2021:
- blog/2021/the-past-present-and-future.md
- blog/2021/excluding-content-from-search.md
- blog/2021/search-better-faster-smaller.md
- blog/posts/the-past-present-and-future.md
- blog/posts/excluding-content-from-search.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? -->
{% include "partials/feedback.html" %}
<!-- Comment system -->
{% include "partials/comments.html" %}