diff --git a/.github/assets/sponsors/sponsor-automation-technology.png b/.github/assets/sponsors/sponsor-automation-technology.png
new file mode 100644
index 000000000..7f9547641
Binary files /dev/null and b/.github/assets/sponsors/sponsor-automation-technology.png differ
diff --git a/.github/assets/sponsors/sponsor-sparkfun.png b/.github/assets/sponsors/sponsor-sparkfun.png
new file mode 100644
index 000000000..e155d95c0
Binary files /dev/null and b/.github/assets/sponsors/sponsor-sparkfun.png differ
diff --git a/.github/workflows/documentation.yml b/.github/workflows/documentation.yml
index 935660927..0b5c87bd9 100644
--- a/.github/workflows/documentation.yml
+++ b/.github/workflows/documentation.yml
@@ -57,10 +57,13 @@ jobs:
run: |
pip install .
pip install \
+ "cairosvg>=2.5" \
"mkdocs-git-committers-plugin-2>=1.1.1" \
"mkdocs-git-revision-date-localized-plugin>=1.0" \
"mkdocs-minify-plugin>=0.3" \
- "mkdocs-redirects>=1.0"
+ "mkdocs-rss-plugin>=1.1" \
+ "mkdocs-redirects>=1.0" \
+ "pillow<10"
- name: Install Insiders build
if: github.event.repository.fork == false
diff --git a/.github/workflows/publish.yml b/.github/workflows/publish.yml
index 4704582d2..e5471c10e 100644
--- a/.github/workflows/publish.yml
+++ b/.github/workflows/publish.yml
@@ -46,10 +46,10 @@ jobs:
python-version: ${{ env.PYTHON_VERSION }}
- name: Set up Python dependencies
- run: pip install --upgrade setuptools wheel twine
+ run: pip install --upgrade build twine
- name: Build Python package
- run: python setup.py build sdist bdist_wheel --universal
+ run: python -m build
- name: Publish Python package
env:
diff --git a/CHANGELOG b/CHANGELOG
index 37df318d7..6aa02a040 100644
--- a/CHANGELOG
+++ b/CHANGELOG
@@ -1,3 +1,68 @@
+mkdocs-material-8.5.2+insiders-4.23.5 (2022-09-18)
+
+ * Fixed #4367: Improved blog plugin date handling for MultiMarkdown syntax
+ * Fixed #4374: Fixed invalid URLs of related links to other blog posts
+
+mkdocs-material-8.5.2 (2022-09-18)
+
+ * Updated Mermaid.js to version 9.1.7
+ * Fixed overly large headlines in search results (8.5.0 regression)
+ * Fixed #4358: Navigation sections appear as clickable (8.5.0 regression)
+ * Fixed #4356: GitHub repository statistics fetched before consent
+
+mkdocs-material-8.5.1 (2022-09-15)
+
+ * Fixed #4366: Removed dependencies with native extensions
+
+mkdocs-material-8.5.0+insiders-4.23.4 (2022-09-14)
+
+ * Fixed #4365: Recursion error in blog plugin due to deepcopy
+ * Fixed path errors for blog plugin on Windows
+ * Fixed publishing workflow in forked repositories
+
+mkdocs-material-8.5.0+insiders-4.23.3 (2022-09-13)
+
+ * Fixed previous and next page links for drafts of blog posts
+
+mkdocs-material-8.5.0 (2022-09-13)
+
+ * Added support for social cards
+ * Added support for code annotation anchor links (deep linking)
+ * Added support for code annotation comment stripping (syntax modifier)
+ * Added support for sidebars scrolling automatically to active item
+ * Added support for anchor following table of contents (= auto scroll)
+ * Added support for tag icons
+
+mkdocs-material-8.4.4+insiders-4.23.2 (2022-09-13)
+
+ * Fixed #4348: Blog plugin crashes on custom nav title
+ * Fixed blog plugin crashing when category contained only drafts
+ * Fixed rendering of content from blog index file
+
+mkdocs-material-8.4.4+insiders-4.23.1 (2022-09-12)
+
+ * Fixed #4345: Blog plugin errors with default settings
+
+mkdocs-material-8.4.4+insiders-4.23.0 (2022-09-12)
+
+ * Added blogging support via built-in blog plugin
+
+mkdocs-material-8.4.4 (2022-09-12)
+
+ * Moved comments integration to separate partial (comments.html)
+
+mkdocs-material-8.4.3+insiders-4.22.1 (2022-09-07)
+
+ * Fixed #4217: Tooltips in data tables render in wrong position
+
+mkdocs-material-8.4.3 (2022-09-07)
+
+ * Added Simple Icons to bundled icons (+2,300 icons)
+ * Added support for changing edit icon
+ * Moved page actions to separate partial (actions.html)
+ * Fixed #4291: Version switching doesn't stay on page when anchors are used
+ * Fixed #4327: Links in data tables do not receive link styling
+
mkdocs-material-8.4.2 (2022-08-27)
* Updated Slovenian translations
diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md
index b57e83b7b..8bede912c 100644
--- a/CONTRIBUTING.md
+++ b/CONTRIBUTING.md
@@ -40,6 +40,36 @@ it is:
the `master`, as it's always a matter of opinion whether if benefits the
overall functionality of the project.
+### Missing translations?
+
+Material for MkDocs ships support for 50+ languages with the help of community
+contributions. When new features are added, sometimes, new translations are
+necessary as well. It's impossible for the maintainers of the project to update
+all translations (we just don't speak 50+ languages), so we have to rely on
+our contributors to incrementally update translations. This process is pretty
+simple, so if you find a translation missing in your language, follow these
+guidelines:
+
+1. Fork the repository.
+
+2. Open up the [translation file for your language] as well as the
+ [English translations], as they are always up-to-date. Compare them
+ side-by-side and add the missing translations. __Important__: only add the
+ translations that are different from the defaults, e.g. if your language
+ is left-to-right, don't add the `direction` translation, as English is
+ left-to-right as well. The following translations are for technical
+ purposes, and should not be updated, so if they're missing from your
+ language it's for good reason:
+
+ - `search.config.lang`
+ - `search.config.pipeline`
+ - `search.config.separator`
+
+1. Create a PR (see below) with your changes.
+
+ [translation file for your language]: https://github.com/squidfunk/mkdocs-material/tree/master/src/partials/languages
+ [English translations]: https://github.com/squidfunk/mkdocs-material/tree/master/src/partials/languages/en.html
+
## Submission guidelines
### Submitting an issue
diff --git a/Dockerfile b/Dockerfile
index 4a6faeb80..da87a0012 100644
--- a/Dockerfile
+++ b/Dockerfile
@@ -32,23 +32,27 @@ WORKDIR /tmp
# Copy files necessary for build
COPY material material
-COPY MANIFEST.in MANIFEST.in
COPY package.json package.json
COPY README.md README.md
COPY requirements.txt requirements.txt
-COPY setup.py setup.py
+COPY pyproject.toml pyproject.toml
# Perform build and cleanup artifacts and caches
RUN \
apk upgrade --update-cache -a \
&& \
apk add --no-cache \
+ cairo \
+ freetype-dev \
git \
git-fast-import \
+ jpeg-dev \
openssh \
+ zlib-dev \
&& \
apk add --no-cache --virtual .build \
gcc \
+ libffi-dev \
musl-dev \
&& \
pip install --no-cache-dir . \
@@ -56,7 +60,9 @@ RUN \
if [ "${WITH_PLUGINS}" = "true" ]; then \
pip install --no-cache-dir \
"mkdocs-minify-plugin>=0.3" \
- "mkdocs-redirects>=1.0"; \
+ "mkdocs-redirects>=1.0" \
+ "pillow>=9.0" \
+ "cairosvg>=2.5"; \
fi \
&& \
apk del .build \
diff --git a/MANIFEST.in b/MANIFEST.in
deleted file mode 100644
index 50ff2bbc9..000000000
--- a/MANIFEST.in
+++ /dev/null
@@ -1,11 +0,0 @@
-recursive-include material *.js *.css *.map *.html *.svg *.png *.yml
-recursive-include material *.ttf *.woff *.woff2 LICENSE*
-recursive-exclude material/overrides *
-recursive-exclude site *
-recursive-exclude src *
-recursive-exclude * __pycache__
-recursive-exclude * *.py[co]
-include LICENSE
-include package.json
-include README.md
-include requirements.txt
diff --git a/README.md b/README.md
index 3b734e207..98c579b2e 100644
--- a/README.md
+++ b/README.md
@@ -125,6 +125,12 @@
+
+
diff --git a/docs/alternatives.md b/docs/alternatives.md
index 28abad0e2..77a8dd274 100644
--- a/docs/alternatives.md
+++ b/docs/alternatives.md
@@ -29,7 +29,7 @@ __Challenges__
- More time needed to get up and running
While [Docusaurus] is one of the best choices when it comes to documentation
-sites that output a single page applications, there are many more solutions,
+sites that output a single page application, there are many more solutions,
including [Docz], [Gatsby], [Vuepress] and [Docsify] that approach
this problem similarily.
diff --git a/docs/blog/.authors.yml b/docs/blog/.authors.yml
new file mode 100644
index 000000000..1e2b34d3b
--- /dev/null
+++ b/docs/blog/.authors.yml
@@ -0,0 +1,4 @@
+squidfunk:
+ name: Martin Donath
+ description: Creator
+ avatar: https://avatars.githubusercontent.com/u/932156
diff --git a/docs/blog/.meta.yml b/docs/blog/.meta.yml
new file mode 100644
index 000000000..ea01dc9ab
--- /dev/null
+++ b/docs/blog/.meta.yml
@@ -0,0 +1,3 @@
+comments: true
+hide:
+ - feedback
diff --git a/docs/blog/index.md b/docs/blog/index.md
index 7330c027f..05761ac57 100644
--- a/docs/blog/index.md
+++ b/docs/blog/index.md
@@ -1,146 +1 @@
----
-template: overrides/main.html
-title: Blog
-search:
- exclude: true
----
-
-
-
# 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.__
-
-
-![@squidfunk][@squidfunk avatar]
-
-__Martin Donath__ · @squidfunk
-
-: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]
-
-
-
----
-
-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.__
-
-
-![@squidfunk][@squidfunk avatar]
-
-__Martin Donath__ · @squidfunk
-
-:octicons-calendar-24: December 27, 2021 ·
-:octicons-clock-24: 10 min read
-
-
-
----
-
-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.__
-
-
-![@squidfunk][@squidfunk avatar]
-
-__Martin Donath__ · @squidfunk
-
-: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]
-
-
-
----
-
-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.__
-
-
-![@squidfunk][@squidfunk avatar]
-
-__Martin Donath__ · @squidfunk
-
-: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]
-
-
-
----
-
-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
diff --git a/docs/blog/posts/blog-support-just-landed.md b/docs/blog/posts/blog-support-just-landed.md
new file mode 100644
index 000000000..641d4a4fd
--- /dev/null
+++ b/docs/blog/posts/blog-support-just-landed.md
@@ -0,0 +1,247 @@
+---
+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.
+
+
+
+_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:
+ - meta
+ - 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.
+
+
+
+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:
+
+
+
+- [Adding an excerpt]
+- [Adding authors]
+- [Adding categories]
+- [Adding tags]
+- [Adding related links]
+- [Linking from and to posts]
+- [Setting the reading time]
+- [Setting defaults]
+
+
+
+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!
diff --git a/docs/blog/posts/blog-support-just-landed/blog.png b/docs/blog/posts/blog-support-just-landed/blog.png
new file mode 100644
index 000000000..a1ea1eaa0
Binary files /dev/null and b/docs/blog/posts/blog-support-just-landed/blog.png differ
diff --git a/docs/blog/2022/chinese-search-support.md b/docs/blog/posts/chinese-search-support.md
similarity index 86%
rename from docs/blog/2022/chinese-search-support.md
rename to docs/blog/posts/chinese-search-support.md
index 243d09209..cf675cd61 100644
--- a/docs/blog/2022/chinese-search-support.md
+++ b/docs/blog/posts/chinese-search-support.md
@@ -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.__
-
-![@squidfunk][@squidfunk avatar]
-
-__Martin Donath__ · @squidfunk
-
-: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]
-
-
-
- [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.
+
+
_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
diff --git a/docs/blog/2021/excluding-content-from-search.md b/docs/blog/posts/excluding-content-from-search.md
similarity index 89%
rename from docs/blog/2021/excluding-content-from-search.md
rename to docs/blog/posts/excluding-content-from-search.md
index 064aa41ac..6c7b0d7b5 100644
--- a/docs/blog/2021/excluding-content-from-search.md
+++ b/docs/blog/posts/excluding-content-from-search.md
@@ -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.__
-
-![@squidfunk][@squidfunk avatar]
-
-__Martin Donath__ · @squidfunk
-
-: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]
-
-
-
- [@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.
+
+
_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
{
diff --git a/docs/blog/2021/search-better-faster-smaller.md b/docs/blog/posts/search-better-faster-smaller.md
similarity index 97%
rename from docs/blog/2021/search-better-faster-smaller.md
rename to docs/blog/posts/search-better-faster-smaller.md
index be2315e21..a6375d867 100644
--- a/docs/blog/2021/search-better-faster-smaller.md
+++ b/docs/blog/posts/search-better-faster-smaller.md
@@ -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.__
-
-![@squidfunk][@squidfunk avatar]
-
-__Martin Donath__ · @squidfunk
-
-: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]
-
-
-
- [@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.
+
+
_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
{
diff --git a/docs/blog/2021/search-better-faster-smaller/search-preview-before.png b/docs/blog/posts/search-better-faster-smaller/search-preview-before.png
similarity index 100%
rename from docs/blog/2021/search-better-faster-smaller/search-preview-before.png
rename to docs/blog/posts/search-better-faster-smaller/search-preview-before.png
diff --git a/docs/blog/2021/search-better-faster-smaller/search-preview-now.png b/docs/blog/posts/search-better-faster-smaller/search-preview-now.png
similarity index 100%
rename from docs/blog/2021/search-better-faster-smaller/search-preview-now.png
rename to docs/blog/posts/search-better-faster-smaller/search-preview-now.png
diff --git a/docs/blog/2021/search-better-faster-smaller/search-preview.png b/docs/blog/posts/search-better-faster-smaller/search-preview.png
similarity index 100%
rename from docs/blog/2021/search-better-faster-smaller/search-preview.png
rename to docs/blog/posts/search-better-faster-smaller/search-preview.png
diff --git a/docs/blog/2021/the-past-present-and-future.md b/docs/blog/posts/the-past-present-and-future.md
similarity index 96%
rename from docs/blog/2021/the-past-present-and-future.md
rename to docs/blog/posts/the-past-present-and-future.md
index cbe2e3d8b..2cd783f36 100644
--- a/docs/blog/2021/the-past-present-and-future.md
+++ b/docs/blog/posts/the-past-present-and-future.md
@@ -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.__
-
-![@squidfunk][@squidfunk avatar]
-
-__Martin Donath__ · @squidfunk
-
-:octicons-calendar-24: December 27, 2021 ·
-:octicons-clock-24: 10 min read
-
-
-
- [@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.
+
+
_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
diff --git a/docs/blog/2021/the-past-present-and-future/funding.png b/docs/blog/posts/the-past-present-and-future/funding.png
similarity index 100%
rename from docs/blog/2021/the-past-present-and-future/funding.png
rename to docs/blog/posts/the-past-present-and-future/funding.png
diff --git a/docs/blog/2021/the-past-present-and-future/mkdocs-material-0.1.0-search.png b/docs/blog/posts/the-past-present-and-future/mkdocs-material-0.1.0-search.png
similarity index 100%
rename from docs/blog/2021/the-past-present-and-future/mkdocs-material-0.1.0-search.png
rename to docs/blog/posts/the-past-present-and-future/mkdocs-material-0.1.0-search.png
diff --git a/docs/blog/2021/the-past-present-and-future/mkdocs-material-0.1.0.png b/docs/blog/posts/the-past-present-and-future/mkdocs-material-0.1.0.png
similarity index 100%
rename from docs/blog/2021/the-past-present-and-future/mkdocs-material-0.1.0.png
rename to docs/blog/posts/the-past-present-and-future/mkdocs-material-0.1.0.png
diff --git a/docs/browser-support.md b/docs/browser-support.md
index bc7a8e190..11879b706 100644
--- a/docs/browser-support.md
+++ b/docs/browser-support.md
@@ -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]:
diff --git a/docs/changelog/index.md b/docs/changelog/index.md
index 8d29aa3b7..aef8869a5 100644
--- a/docs/changelog/index.md
+++ b/docs/changelog/index.md
@@ -6,6 +6,38 @@ template: overrides/main.html
## Material for MkDocs
+### 8.5.2 _ September 18, 2022 { id="8.5.2" }
+
+- Updated Mermaid.js to version 9.1.7
+- Fixed overly large headlines in search results (8.5.0 regression)
+- Fixed #4358: Navigation sections appear as clickable (8.5.0 regression)
+- Fixed #4356: GitHub repository statistics fetched before consent
+
+### 8.5.1 _ September 15, 2022 { id="8.5.1" }
+
+- Fixed #4366: Removed dependencies with native extensions
+
+### 8.5.0 _ September 13, 2022 { id="8.5.0" }
+
+- Added support for social cards
+- Added support for code annotation anchor links (deep linking)
+- Added support for code annotation comment stripping (syntax modifier)
+- Added support for sidebars scrolling automatically to active item
+- Added support for anchor following table of contents (= auto scroll)
+- Added support for tag icons
+
+### 8.4.4 _ September 12, 2022 { id="8.4.4" }
+
+- Moved comments integration to separate partial (`comments.html`)
+
+### 8.4.3 _ September 7, 2022 { id="8.4.3" }
+
+- Added Simple Icons to bundled icons (+2,300 icons)
+- Added support for changing edit icon
+- Moved page actions to separate partial (`actions.html`)
+- Fixed #4291: Version switching doesn't stay on page when anchors are used
+- Fixed #4327: Links in data tables do not receive link styling
+
### 8.4.2 _ August 27, 2022 { id="8.4.2" }
- Updated Slovenian translations
diff --git a/docs/creating-your-site.md b/docs/creating-your-site.md
index 275846d02..f611c597c 100644
--- a/docs/creating-your-site.md
+++ b/docs/creating-your-site.md
@@ -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:
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
diff --git a/docs/customization.md b/docs/customization.md
index 455f3b52c..58f469d3a 100644
--- a/docs/customization.md
+++ b/docs/customization.md
@@ -103,25 +103,37 @@ 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
+├─ blog.html # Blog index page
+├─ blog-archive.html # Blog archive index page
+├─ blog-category.html # Blog category index page
+├─ blog-post.html # Blog post page
└─ main.html # Default page
```
@@ -170,6 +182,21 @@ Then, e.g. to override the site title, add the following lines to `main.html`:
{% endblock %}
```
+If you intend to __add__ something to a block rather than to replace it
+altogether with new content, use `{{ super() }}` inside the block to include the
+original block content. This is particularly useful when adding third-party
+scripts to your docs, e.g.
+
+``` html
+{% extends "base.html" %}
+
+{% block scripts %}
+
+ {{ super() }}
+
+{% endblock %}
+```
+
The following template blocks are provided by the theme:
| Block name | Purpose |
@@ -177,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 |
diff --git a/docs/getting-started.md b/docs/getting-started.md
index bd8e26bd6..a0bb59369 100644
--- a/docs/getting-started.md
+++ b/docs/getting-started.md
@@ -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 recommended { #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
diff --git a/docs/insiders/changelog.md b/docs/insiders/changelog.md
index b598f16aa..87d9cb5b1 100644
--- a/docs/insiders/changelog.md
+++ b/docs/insiders/changelog.md
@@ -6,6 +6,39 @@ template: overrides/main.html
## Material for MkDocs Insiders
+### 4.23.5 _ September 18, 2022 { id="4.23.5" }
+
+- Fixed #4367: Improved blog plugin date handling for MultiMarkdown syntax
+- Fixed #4374: Fixed invalid URLs of related links to other blog posts
+
+### 4.23.4 _ September 14, 2022 { id="4.23.4" }
+
+- Fixed #4365: Recursion error in blog plugin due to `deepcopy`
+- Fixed path errors for blog plugin on Windows
+- Fixed publishing workflow in forked repositories
+
+### 4.23.3 _ September 13, 2022 { id="4.23.3" }
+
+- Fixed previous and next page links for drafts of blog posts
+
+### 4.23.2 _ September 13, 2022 { id="4.23.2" }
+
+- Fixed #4348: Blog plugin crashes on custom `nav` title
+- Fixed blog plugin crashing when category contained only drafts
+- Fixed rendering of content from blog index file
+
+### 4.23.1 _ September 12, 2022 { id="4.23.1" }
+
+- Fixed #4345: Blog plugin errors with default settings
+
+### 4.23.0 _ September 12, 2022 { id="4.23.0" }
+
+- Added blogging support via built-in blog plugin
+
+### 4.22.1 _ September 7, 2022 { id="4.22.1" }
+
+- Fixed #4217: Tooltips in data tables render in wrong position
+
### 4.22.0 _ August 21, 2022 { id="4.22.0" }
- Added support for navigation status
diff --git a/docs/insiders/getting-started.md b/docs/insiders/getting-started.md
index b7cb4468a..916b085e8 100644
--- a/docs/insiders/getting-started.md
+++ b/docs/insiders/getting-started.md
@@ -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
diff --git a/docs/insiders/index.md b/docs/insiders/index.md
index 9998babcc..cb1f87483 100644
--- a/docs/insiders/index.md
+++ b/docs/insiders/index.md
@@ -82,36 +82,32 @@ 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 21 additional features__ that you can start using right away, and
which are currently exclusively available to sponsors:
+- [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] [Tags plugin: additional indexes]
- [x] [Document contributors]
- [x] [Automatic light / dark mode]
- [x] [Content tabs: anchor links]
- [x] [Navigation pruning]
- [x] [Tooltips]
- [x] [Chinese search support]
-- [x] [Tag icons]
- [x] [Card grids]
- [x] [Offline plugin]
- [x] [Privacy plugin]
-- [x] [Table of contents anchor following]
- [x] [Annotations]
- [x] [Navigation icons]
-- [x] Sidebars automatically scroll to active item
-- [x] [Code annotations: anchor links]
-- [x] [Code annotations: strip comments]
- [x] [Brand new search plugin]
- [x] [Rich search previews]
- [x] [Tokenizer with lookahead]
- [x] [Advanced search highlighting]
- [x] [Excluding content from search]
-- [x] [Social cards]
@@ -182,6 +178,8 @@ You can cancel your sponsorship anytime.[^5]
[![IP Fabric]](https://ipfabric.io/){ target=_blank title="IP Fabric" }
[![Apex.AI]](https://www.apex.ai/){ target=_blank title="Apex.AI" }
[![Jitterbit]](https://jitterbit.com/){ target=_blank title="Jitterbit" }
+[![Sparkfun]](https://sparkfun.com/){ target=_blank title="Sparkfun Electronics" }
+[![Automation Technology]](https://automationtechnology.de/){ target=_blank title="Automation Technology" }
@@ -206,6 +204,8 @@ You can cancel your sponsorship anytime.[^5]
[IP Fabric]: https://raw.githubusercontent.com/squidfunk/mkdocs-material/master/.github/assets/sponsors/sponsor-ip-fabric.png
[Apex.AI]: https://raw.githubusercontent.com/squidfunk/mkdocs-material/master/.github/assets/sponsors/sponsor-apex-ai.png
[Jitterbit]: https://raw.githubusercontent.com/squidfunk/mkdocs-material/master/.github/assets/sponsors/sponsor-jitterbit.png
+ [Sparkfun]: https://raw.githubusercontent.com/squidfunk/mkdocs-material/master/.github/assets/sponsors/sponsor-sparkfun.png
+ [Automation Technology]: https://raw.githubusercontent.com/squidfunk/mkdocs-material/master/.github/assets/sponsors/sponsor-automation-technology.png
@@ -232,21 +232,6 @@ features prefixed with a checkmark symbol, denoting whether a feature is
:octicons-check-circle-fill-24:{ style="color: var(--md-default-fg-color--lightest)" } planned, but not yet implemented. When the funding goal is hit, the features
are released for general availability.
-#### $ 8,000 – Scotch Bonnet
-
-- [x] [Social cards]
-- [x] [Code annotations: anchor links]
-- [x] [Code annotations: strip comments]
-- [x] [Tag icons]
-- [x] [Table of contents anchor following]
-- [x] Sidebars automatically scroll to active item
-
- [Social cards]: ../setup/setting-up-social-cards.md
- [Code annotations: anchor links]: ../reference/code-blocks.md#anchor-links
- [Code annotations: strip comments]: ../reference/code-blocks.md#stripping-comments
- [Tag icons]: ../setup/setting-up-tags.md#tag-icons
- [Table of contents anchor following]: ../setup/setting-up-navigation.md#anchor-following
-
#### $ 10,000 – Carolina Reaper
- [x] [Brand new search plugin]
@@ -256,24 +241,25 @@ 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
#### $ 12,000 – Piri Piri
-- [x] [Annotations]
+- [x] [Blog plugin]
- [x] [Chinese search support]
+- [x] [Annotations]
- [x] [Navigation icons]
- [x] [Navigation pruning]
- [x] [Navigation status]
-- [ ] Blog plugin
+ [Blog plugin]: ../setup/setting-up-a-blog.md
+ [Chinese search support]: ../blog/posts/chinese-search-support.md
[Annotations]: ../reference/annotations.md
- [Chinese search support]: ../blog/2022/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
@@ -297,13 +283,16 @@ are released for general availability.
#### $ 16,000 – Chipotle
- [x] [Meta plugin]
-- [x] [Additional tags indexes]
+- [x] [Blog plugin: related links]
+- [x] [Tags plugin: additional indexes]
- [ ] [Instant previews]
+- [ ] Navigation subtitles
- [ ] ... more to be announced
[Meta plugin]: ../reference/index.md#built-in-meta-plugin
- [Additional tags indexes]: ../setup/setting-up-tags.md#tags-extra-files
+ [Tags plugin: additional indexes]: ../setup/setting-up-tags.md#+tags.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
@@ -311,13 +300,28 @@ This section lists all funding goals that were previously completed, which means
that those features were part of Insiders, but are now generally available and
can be used by all users.
+#### $ 8,000 – Scotch Bonnet
+
+- [x] [Social cards]
+- [x] [Code annotations: anchor links]
+- [x] [Code annotations: strip comments]
+- [x] [Tag icons]
+- [x] [Table of contents anchor following]
+- [x] Sidebars automatically scroll to active item
+
+ [Social cards]: ../setup/setting-up-social-cards.md
+ [Code annotations: anchor links]: ../reference/code-blocks.md#anchor-links
+ [Code annotations: strip comments]: ../reference/code-blocks.md#stripping-comments
+ [Tag icons]: ../setup/setting-up-tags.md#tag-icons
+ [Table of contents anchor following]: ../setup/setting-up-navigation.md#anchor-following
+
#### $ 7,000 – Royal Gold
- [x] [Cookie consent]
- [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
diff --git a/docs/reference/admonitions.md b/docs/reference/admonitions.md
index 8ad307de6..60078a6e1 100644
--- a/docs/reference/admonitions.md
+++ b/docs/reference/admonitions.md
@@ -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]:
}
-=== ":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:
diff --git a/docs/reference/code-blocks.md b/docs/reference/code-blocks.md
index 3d1a5f9de..5afdfb50c 100644
--- a/docs/reference/code-blocks.md
+++ b/docs/reference/code-blocks.md
@@ -83,13 +83,12 @@ theme:
#### Anchor links
-[:octicons-heart-fill-24:{ .mdx-heart } Sponsors only][Insiders]{ .mdx-insiders } ·
-[:octicons-tag-24: insiders-4.4.0][Insiders] ·
+[:octicons-tag-24: 8.5.0][Anchor links support] ·
:octicons-beaker-24: Experimental
-In order to link to code annotations and share them more easily, [Insiders] adds
-an anchor link to each annotation automatically, which you can copy via right
-click or open in a new tab:
+In order to be able to link to code annotations and share them more easily, an
+anchor link is automatically added to each annotation, which you can copy via
+right click or open in a new tab:
``` yaml
# (1)!
@@ -99,7 +98,7 @@ click or open in a new tab:
rendered open in a new tab. You can also right-click me to __copy link
address__ to share me with others.
- [Insiders]: ../insiders/index.md
+ [Anchor links support]: https://github.com/squidfunk/mkdocs-material/releases/tag/8.5.0
## Usage
@@ -126,8 +125,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=""` option directly after the shortcode,
e.g. to display the name of a file:
@@ -154,8 +151,6 @@ def bubble_sort(items):
- [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
@@ -195,13 +190,11 @@ theme:
#### Stripping comments
-[:octicons-heart-fill-24:{ .mdx-heart } Sponsors only][Insiders]{ .mdx-insiders } ·
-[:octicons-tag-24: insiders-4.4.0][Insiders] ·
+[:octicons-tag-24: 8.5.0][Stripping comments support] ·
:octicons-beaker-24: Experimental
If you wish to strip the comment characters surrounding a code annotation,
-[Insiders] adds a new syntax that allows for just that. Simply add an `!` after
-the closing parens of the code annotation:
+simply add an `!` after the closing parenthesis of the code annotation:
```` markdown title="Code block with annotation, stripped"
``` yaml
@@ -225,6 +218,8 @@ Note that this only allows for a single code annotation to be rendered per
comment. If you want to add multiple code annotations, comments cannot be
stripped for technical reasons.
+ [Stripping comments support]: https://github.com/squidfunk/mkdocs-material/releases/tag/8.5.0
+
### Adding line numbers
Line numbers can be added to a code block by using the `linenums=""`
@@ -354,7 +349,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 +357,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 +368,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 +376,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 +395,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 +403,7 @@ of an [additional style sheet]:
}
```
-=== ":octicons-file-code-16: mkdocs.yml"
+=== ":octicons-file-code-16: `mkdocs.yml`"
``` yaml
extra_css:
@@ -439,7 +434,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 +445,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:
diff --git a/docs/reference/content-tabs.md b/docs/reference/content-tabs.md
index 8ec36c7f5..180ca6a87 100644
--- a/docs/reference/content-tabs.md
+++ b/docs/reference/content-tabs.md
@@ -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
diff --git a/docs/reference/data-tables.md b/docs/reference/data-tables.md
index 8f6d83ea2..100cecc34 100644
--- a/docs/reference/data-tables.md
+++ b/docs/reference/data-tables.md
@@ -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:
diff --git a/docs/reference/icons-emojis.md b/docs/reference/icons-emojis.md
index 2824f1aad..e2d824141 100644
--- a/docs/reference/icons-emojis.md
+++ b/docs/reference/icons-emojis.md
@@ -6,7 +6,7 @@ icon: material/emoticon-happy-outline
# Icons, Emojis
One of the best features of Material for MkDocs is the possibility to use [more
-than 8,000 icons][icon search] and thousands of emojis in your project
+than 10,000 icons][icon search] and thousands of emojis in your project
documentation with practically zero additional effort. Moreover, custom icons
can be added and used in `mkdocs.yml`, documents and templates.
@@ -50,6 +50,7 @@ The following icon sets are bundled with Material for MkDocs:
- :material-material-design: – [Material Design]
- :fontawesome-brands-font-awesome: – [FontAwesome]
- :octicons-mark-github-16: – [Octicons]
+- :simple-simpleicons: – [Simple Icons]
See additional configuration options:
@@ -60,6 +61,7 @@ See additional configuration options:
[Material Design]: https://materialdesignicons.com/
[FontAwesome]: https://fontawesome.com/search?m=free
[Octicons]: https://octicons.github.com/
+ [Simple Icons]: https://simpleicons.org/
[Attribute Lists]: ../setup/extensions/python-markdown.md#attribute-lists
[Emoji]: ../setup/extensions/python-markdown-extensions.md#emoji
[Emoji with custom icons]: ../setup/extensions/python-markdown-extensions.md#custom-icons
@@ -116,7 +118,7 @@ declarations into dedicated CSS classes:
}
-=== ":octicons-file-code-16: docs/stylesheets/extra.css"
+=== ":octicons-file-code-16: `docs/stylesheets/extra.css`"
``` css
.twitter {
@@ -124,7 +126,7 @@ declarations into dedicated CSS classes:
}
```
-=== ":octicons-file-code-16: mkdocs.yml"
+=== ":octicons-file-code-16: `mkdocs.yml`"
``` yaml
extra_css:
@@ -153,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 {
@@ -169,7 +171,7 @@ dedicated CSS class to the icon:
}
```
-=== ":octicons-file-code-16: mkdocs.yml"
+=== ":octicons-file-code-16: `mkdocs.yml`"
``` yaml
extra_css:
diff --git a/docs/reference/images.md b/docs/reference/images.md
index bc23abfd4..88192bd9c 100644
--- a/docs/reference/images.md
+++ b/docs/reference/images.md
@@ -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
diff --git a/docs/reference/index.md b/docs/reference/index.md
index 032ef47b1..e51bdc5b0 100644
--- a/docs/reference/index.md
+++ b/docs/reference/index.md
@@ -24,16 +24,20 @@ tags. Add the following lines to `mkdocs.yml`:
``` yaml
plugins:
- - meta
+ - meta # (1)!
```
+1. Note that the meta plugin should be located at the beginning of the list
+ of `plugins`, so that other plugins (including the [built-in blog plugin])
+ will pick up the set defaults.
+
> If you need to be able to build your documentation with and without
> [Insiders], please refer to the [built-in plugins] section to learn how
> shared configurations help to achieve this.
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
@@ -48,6 +52,7 @@ The following configuration options are available:
1. Note that it's strongly recommended to prefix meta files with a `.`,
since otherwise they would be included in the build output.
+ [built-in blog plugin]: ../setup/setting-up-a-blog.md#built-in-blog-plugin
[built-in plugins]: ../insiders/getting-started.md#built-in-plugins
## Usage
@@ -57,7 +62,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 +84,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 +105,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 +158,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 +178,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 +190,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
diff --git a/docs/reference/mathjax.md b/docs/reference/mathjax.md
index dd4c99738..960828465 100644
--- a/docs/reference/mathjax.md
+++ b/docs/reference/mathjax.md
@@ -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:
diff --git a/docs/reference/tooltips.md b/docs/reference/tooltips.md
index b65c7b1c0..efdebb339 100644
--- a/docs/reference/tooltips.md
+++ b/docs/reference/tooltips.md
@@ -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.
- [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:
diff --git a/docs/schema/assets/icons.json b/docs/schema/assets/icons.json
index 39fe4abf5..918854c31 100644
--- a/docs/schema/assets/icons.json
+++ b/docs/schema/assets/icons.json
@@ -601,7 +601,6 @@
"fontawesome/regular/money-bill-1",
"fontawesome/regular/moon",
"fontawesome/regular/newspaper",
- "fontawesome/regular/notdef",
"fontawesome/regular/note-sticky",
"fontawesome/regular/object-group",
"fontawesome/regular/object-ungroup",
@@ -1496,7 +1495,6 @@
"fontawesome/solid/neuter",
"fontawesome/solid/newspaper",
"fontawesome/solid/not-equal",
- "fontawesome/solid/notdef",
"fontawesome/solid/note-sticky",
"fontawesome/solid/notes-medical",
"fontawesome/solid/o",
@@ -9120,6 +9118,7 @@
"material/zodiac-taurus",
"material/zodiac-virgo",
"octicons/accessibility-16",
+ "octicons/accessibility-inset-16",
"octicons/alert-16",
"octicons/alert-24",
"octicons/alert-fill-12",
@@ -9527,6 +9526,7 @@
"octicons/shield-check-24",
"octicons/shield-lock-16",
"octicons/shield-lock-24",
+ "octicons/shield-slash-16",
"octicons/shield-x-16",
"octicons/shield-x-24",
"octicons/sidebar-collapse-16",
@@ -9632,6 +9632,2356 @@
"octicons/x-circle-fill-16",
"octicons/x-circle-fill-24",
"octicons/zap-16",
- "octicons/zap-24"
+ "octicons/zap-24",
+ "simple/1001tracklists",
+ "simple/1password",
+ "simple/3m",
+ "simple/42",
+ "simple/4chan",
+ "simple/4d",
+ "simple/500px",
+ "simple/abbott",
+ "simple/abbrobotstudio",
+ "simple/abbvie",
+ "simple/abletonlive",
+ "simple/aboutdotme",
+ "simple/abstract",
+ "simple/academia",
+ "simple/accenture",
+ "simple/acclaim",
+ "simple/accusoft",
+ "simple/acer",
+ "simple/acm",
+ "simple/actigraph",
+ "simple/activision",
+ "simple/adafruit",
+ "simple/adblock",
+ "simple/adblockplus",
+ "simple/addthis",
+ "simple/adguard",
+ "simple/adidas",
+ "simple/adobe",
+ "simple/adobeacrobatreader",
+ "simple/adobeaftereffects",
+ "simple/adobeaudition",
+ "simple/adobecreativecloud",
+ "simple/adobedreamweaver",
+ "simple/adobefonts",
+ "simple/adobeillustrator",
+ "simple/adobeindesign",
+ "simple/adobelightroom",
+ "simple/adobelightroomclassic",
+ "simple/adobephotoshop",
+ "simple/adobepremierepro",
+ "simple/adobexd",
+ "simple/adonisjs",
+ "simple/adyen",
+ "simple/aerlingus",
+ "simple/aeroflot",
+ "simple/aeromexico",
+ "simple/aerospike",
+ "simple/aew",
+ "simple/affinity",
+ "simple/affinitydesigner",
+ "simple/affinityphoto",
+ "simple/affinitypublisher",
+ "simple/aframe",
+ "simple/agora",
+ "simple/aib",
+ "simple/aidungeon",
+ "simple/aiohttp",
+ "simple/aiqfome",
+ "simple/airasia",
+ "simple/airbnb",
+ "simple/airbus",
+ "simple/airbyte",
+ "simple/aircall",
+ "simple/aircanada",
+ "simple/airchina",
+ "simple/airfrance",
+ "simple/airplayaudio",
+ "simple/airplayvideo",
+ "simple/airtable",
+ "simple/ajv",
+ "simple/alacritty",
+ "simple/albertheijn",
+ "simple/aldinord",
+ "simple/aldisud",
+ "simple/alfaromeo",
+ "simple/alfred",
+ "simple/algolia",
+ "simple/algorand",
+ "simple/alibabacloud",
+ "simple/alibabadotcom",
+ "simple/aliexpress",
+ "simple/alipay",
+ "simple/alitalia",
+ "simple/allegro",
+ "simple/alliedmodders",
+ "simple/allocine",
+ "simple/alltrails",
+ "simple/alpinedotjs",
+ "simple/alpinelinux",
+ "simple/altiumdesigner",
+ "simple/amazon",
+ "simple/amazonalexa",
+ "simple/amazonapigateway",
+ "simple/amazonaws",
+ "simple/amazoncloudwatch",
+ "simple/amazondynamodb",
+ "simple/amazonec2",
+ "simple/amazonecs",
+ "simple/amazoneks",
+ "simple/amazonfiretv",
+ "simple/amazonlumberyard",
+ "simple/amazonpay",
+ "simple/amazonprime",
+ "simple/amazonrds",
+ "simple/amazons3",
+ "simple/amazonsqs",
+ "simple/amd",
+ "simple/americanairlines",
+ "simple/americanexpress",
+ "simple/amg",
+ "simple/amp",
+ "simple/amul",
+ "simple/ana",
+ "simple/anaconda",
+ "simple/analogue",
+ "simple/anchor",
+ "simple/andela",
+ "simple/android",
+ "simple/androidauto",
+ "simple/androidstudio",
+ "simple/angellist",
+ "simple/angular",
+ "simple/angularjs",
+ "simple/angularuniversal",
+ "simple/anilist",
+ "simple/ansible",
+ "simple/ansys",
+ "simple/anta",
+ "simple/antdesign",
+ "simple/antena3",
+ "simple/anydesk",
+ "simple/aol",
+ "simple/apache",
+ "simple/apacheairflow",
+ "simple/apacheant",
+ "simple/apachecassandra",
+ "simple/apachecloudstack",
+ "simple/apachecordova",
+ "simple/apachecouchdb",
+ "simple/apachedruid",
+ "simple/apacheecharts",
+ "simple/apacheflink",
+ "simple/apachegroovy",
+ "simple/apachehadoop",
+ "simple/apachehive",
+ "simple/apachejmeter",
+ "simple/apachekafka",
+ "simple/apachekylin",
+ "simple/apachemaven",
+ "simple/apachenetbeanside",
+ "simple/apacheopenoffice",
+ "simple/apachepulsar",
+ "simple/apacherocketmq",
+ "simple/apachesolr",
+ "simple/apachespark",
+ "simple/apachetomcat",
+ "simple/aparat",
+ "simple/apollographql",
+ "simple/apostrophe",
+ "simple/appannie",
+ "simple/appian",
+ "simple/apple",
+ "simple/applearcade",
+ "simple/applemusic",
+ "simple/applenews",
+ "simple/applepay",
+ "simple/applepodcasts",
+ "simple/appletv",
+ "simple/appsignal",
+ "simple/appstore",
+ "simple/appveyor",
+ "simple/appwrite",
+ "simple/aqua",
+ "simple/aral",
+ "simple/arangodb",
+ "simple/archicad",
+ "simple/archiveofourown",
+ "simple/archlinux",
+ "simple/ardour",
+ "simple/arduino",
+ "simple/argo",
+ "simple/argos",
+ "simple/arkecosystem",
+ "simple/arlo",
+ "simple/arm",
+ "simple/artifacthub",
+ "simple/artixlinux",
+ "simple/artstation",
+ "simple/arxiv",
+ "simple/asana",
+ "simple/asciidoctor",
+ "simple/asciinema",
+ "simple/asda",
+ "simple/aseprite",
+ "simple/askfm",
+ "simple/askubuntu",
+ "simple/assemblyscript",
+ "simple/astonmartin",
+ "simple/astro",
+ "simple/asus",
+ "simple/atandt",
+ "simple/atari",
+ "simple/atlassian",
+ "simple/atom",
+ "simple/auchan",
+ "simple/audacity",
+ "simple/audi",
+ "simple/audible",
+ "simple/audioboom",
+ "simple/audiomack",
+ "simple/audiotechnica",
+ "simple/aurelia",
+ "simple/auth0",
+ "simple/authy",
+ "simple/autodesk",
+ "simple/autohotkey",
+ "simple/automattic",
+ "simple/autoprefixer",
+ "simple/avajs",
+ "simple/avast",
+ "simple/awesomelists",
+ "simple/awesomewm",
+ "simple/awsamplify",
+ "simple/awsfargate",
+ "simple/awslambda",
+ "simple/axios",
+ "simple/azureartifacts",
+ "simple/azuredataexplorer",
+ "simple/azuredevops",
+ "simple/azurefunctions",
+ "simple/azurepipelines",
+ "simple/babel",
+ "simple/backbonedotjs",
+ "simple/backendless",
+ "simple/badgr",
+ "simple/badoo",
+ "simple/baidu",
+ "simple/bamboo",
+ "simple/bandcamp",
+ "simple/bandlab",
+ "simple/bandrautomation",
+ "simple/bandsintown",
+ "simple/bankofamerica",
+ "simple/barclays",
+ "simple/baremetrics",
+ "simple/basecamp",
+ "simple/bastyon",
+ "simple/bata",
+ "simple/bathasu",
+ "simple/battledotnet",
+ "simple/bbc",
+ "simple/bbciplayer",
+ "simple/beatport",
+ "simple/beats",
+ "simple/beatsbydre",
+ "simple/behance",
+ "simple/beijingsubway",
+ "simple/bem",
+ "simple/bentley",
+ "simple/betfair",
+ "simple/bigbasket",
+ "simple/bigbluebutton",
+ "simple/bigcartel",
+ "simple/bigcommerce",
+ "simple/bilibili",
+ "simple/binance",
+ "simple/biolink",
+ "simple/bit",
+ "simple/bitbucket",
+ "simple/bitcoin",
+ "simple/bitcoincash",
+ "simple/bitcoinsv",
+ "simple/bitdefender",
+ "simple/bitly",
+ "simple/bitrise",
+ "simple/bitwarden",
+ "simple/bitwig",
+ "simple/blackberry",
+ "simple/blazemeter",
+ "simple/blazor",
+ "simple/blender",
+ "simple/blockchaindotcom",
+ "simple/blogger",
+ "simple/bloglovin",
+ "simple/blueprint",
+ "simple/bluetooth",
+ "simple/bmcsoftware",
+ "simple/bmw",
+ "simple/boehringeringelheim",
+ "simple/boeing",
+ "simple/bookalope",
+ "simple/bookbub",
+ "simple/bookmeter",
+ "simple/bookmyshow",
+ "simple/bookstack",
+ "simple/boost",
+ "simple/boots",
+ "simple/bootstrap",
+ "simple/borgbackup",
+ "simple/bosch",
+ "simple/bose",
+ "simple/boulanger",
+ "simple/bower",
+ "simple/box",
+ "simple/boxysvg",
+ "simple/brandfolder",
+ "simple/brave",
+ "simple/breaker",
+ "simple/britishairways",
+ "simple/broadcom",
+ "simple/bt",
+ "simple/buddy",
+ "simple/budibase",
+ "simple/buefy",
+ "simple/buffer",
+ "simple/bugatti",
+ "simple/bugcrowd",
+ "simple/bugsnag",
+ "simple/buildkite",
+ "simple/bukalapak",
+ "simple/bulma",
+ "simple/bun",
+ "simple/bunq",
+ "simple/burgerking",
+ "simple/burton",
+ "simple/buymeacoffee",
+ "simple/buzzfeed",
+ "simple/byjus",
+ "simple/byte",
+ "simple/bytedance",
+ "simple/c",
+ "simple/cachet",
+ "simple/caffeine",
+ "simple/cairometro",
+ "simple/cakephp",
+ "simple/campaignmonitor",
+ "simple/canonical",
+ "simple/canva",
+ "simple/capacitor",
+ "simple/carrefour",
+ "simple/carthrottle",
+ "simple/carto",
+ "simple/cashapp",
+ "simple/castbox",
+ "simple/castorama",
+ "simple/castro",
+ "simple/caterpillar",
+ "simple/cbs",
+ "simple/cdprojekt",
+ "simple/celery",
+ "simple/centos",
+ "simple/ceph",
+ "simple/cesium",
+ "simple/chai",
+ "simple/chainlink",
+ "simple/chakraui",
+ "simple/chartdotjs",
+ "simple/chartmogul",
+ "simple/chase",
+ "simple/chatbot",
+ "simple/checkio",
+ "simple/checkmarx",
+ "simple/chef",
+ "simple/chemex",
+ "simple/chevrolet",
+ "simple/chinaeasternairlines",
+ "simple/chinasouthernairlines",
+ "simple/chocolatey",
+ "simple/chromecast",
+ "simple/chrysler",
+ "simple/chupachups",
+ "simple/cilium",
+ "simple/cinema4d",
+ "simple/circle",
+ "simple/circleci",
+ "simple/cirrusci",
+ "simple/cisco",
+ "simple/citrix",
+ "simple/citroen",
+ "simple/civicrm",
+ "simple/civo",
+ "simple/ckeditor4",
+ "simple/claris",
+ "simple/clickhouse",
+ "simple/clickup",
+ "simple/clion",
+ "simple/cliqz",
+ "simple/clockify",
+ "simple/clojure",
+ "simple/cloud66",
+ "simple/cloudbees",
+ "simple/cloudcannon",
+ "simple/cloudera",
+ "simple/cloudflare",
+ "simple/cloudflarepages",
+ "simple/cloudfoundry",
+ "simple/cloudsmith",
+ "simple/cloudways",
+ "simple/clubhouse",
+ "simple/clyp",
+ "simple/cmake",
+ "simple/cncf",
+ "simple/cnn",
+ "simple/cockpit",
+ "simple/cockroachlabs",
+ "simple/cocoapods",
+ "simple/cocos",
+ "simple/coda",
+ "simple/codacy",
+ "simple/codeberg",
+ "simple/codecademy",
+ "simple/codeceptjs",
+ "simple/codechef",
+ "simple/codeclimate",
+ "simple/codecov",
+ "simple/codefactor",
+ "simple/codeforces",
+ "simple/codeigniter",
+ "simple/codemagic",
+ "simple/codemirror",
+ "simple/codenewbie",
+ "simple/codepen",
+ "simple/codeproject",
+ "simple/codereview",
+ "simple/codersrank",
+ "simple/coderwall",
+ "simple/codesandbox",
+ "simple/codeship",
+ "simple/codewars",
+ "simple/codingame",
+ "simple/codingninjas",
+ "simple/codio",
+ "simple/coffeescript",
+ "simple/cognizant",
+ "simple/coil",
+ "simple/coinbase",
+ "simple/coinmarketcap",
+ "simple/commerzbank",
+ "simple/commitlint",
+ "simple/commodore",
+ "simple/commonworkflowlanguage",
+ "simple/composer",
+ "simple/comsol",
+ "simple/conan",
+ "simple/concourse",
+ "simple/condaforge",
+ "simple/conekta",
+ "simple/confluence",
+ "simple/construct3",
+ "simple/consul",
+ "simple/contactlesspayment",
+ "simple/containerd",
+ "simple/contentful",
+ "simple/conventionalcommits",
+ "simple/convertio",
+ "simple/cookiecutter",
+ "simple/coop",
+ "simple/cora",
+ "simple/coronaengine",
+ "simple/coronarenderer",
+ "simple/corsair",
+ "simple/couchbase",
+ "simple/counterstrike",
+ "simple/countingworkspro",
+ "simple/coursera",
+ "simple/coveralls",
+ "simple/cpanel",
+ "simple/cplusplus",
+ "simple/craftcms",
+ "simple/cratedb",
+ "simple/createreactapp",
+ "simple/creativecommons",
+ "simple/credly",
+ "simple/crehana",
+ "simple/criticalrole",
+ "simple/crowdin",
+ "simple/crowdsource",
+ "simple/crunchbase",
+ "simple/crunchyroll",
+ "simple/cryengine",
+ "simple/crystal",
+ "simple/csharp",
+ "simple/css3",
+ "simple/cssmodules",
+ "simple/csswizardry",
+ "simple/cucumber",
+ "simple/curl",
+ "simple/curseforge",
+ "simple/cycling74",
+ "simple/cypress",
+ "simple/cytoscapedotjs",
+ "simple/d",
+ "simple/d3dotjs",
+ "simple/dacia",
+ "simple/daf",
+ "simple/dailymotion",
+ "simple/daimler",
+ "simple/dapr",
+ "simple/darkreader",
+ "simple/dart",
+ "simple/darty",
+ "simple/daserste",
+ "simple/dash",
+ "simple/dashlane",
+ "simple/dask",
+ "simple/dassaultsystemes",
+ "simple/databricks",
+ "simple/datacamp",
+ "simple/datadog",
+ "simple/datadotai",
+ "simple/datagrip",
+ "simple/dataiku",
+ "simple/datastax",
+ "simple/dataverse",
+ "simple/dataversioncontrol",
+ "simple/datocms",
+ "simple/datto",
+ "simple/dazn",
+ "simple/dblp",
+ "simple/dbt",
+ "simple/dcentertainment",
+ "simple/debian",
+ "simple/dedge",
+ "simple/deepin",
+ "simple/deepnote",
+ "simple/deezer",
+ "simple/delicious",
+ "simple/deliveroo",
+ "simple/dell",
+ "simple/delonghi",
+ "simple/delphi",
+ "simple/delta",
+ "simple/deno",
+ "simple/dependabot",
+ "simple/derspiegel",
+ "simple/designernews",
+ "simple/deutschebahn",
+ "simple/deutschebank",
+ "simple/devdotto",
+ "simple/devexpress",
+ "simple/deviantart",
+ "simple/devpost",
+ "simple/devrant",
+ "simple/dgraph",
+ "simple/dhl",
+ "simple/diagramsdotnet",
+ "simple/dialogflow",
+ "simple/diaspora",
+ "simple/digg",
+ "simple/digikeyelectronics",
+ "simple/digitalocean",
+ "simple/dior",
+ "simple/directus",
+ "simple/discogs",
+ "simple/discord",
+ "simple/discourse",
+ "simple/discover",
+ "simple/disqus",
+ "simple/disroot",
+ "simple/django",
+ "simple/dlib",
+ "simple/dlna",
+ "simple/dm",
+ "simple/docker",
+ "simple/docsdotrs",
+ "simple/docusign",
+ "simple/dogecoin",
+ "simple/dolby",
+ "simple/doordash",
+ "simple/dotenv",
+ "simple/dotnet",
+ "simple/douban",
+ "simple/doubanread",
+ "simple/dpd",
+ "simple/dragonframe",
+ "simple/draugiemdotlv",
+ "simple/dribbble",
+ "simple/drone",
+ "simple/drooble",
+ "simple/dropbox",
+ "simple/drupal",
+ "simple/dsautomobiles",
+ "simple/dtube",
+ "simple/ducati",
+ "simple/duckdb",
+ "simple/duckduckgo",
+ "simple/dungeonsanddragons",
+ "simple/dunked",
+ "simple/duolingo",
+ "simple/dvc",
+ "simple/dwavesystems",
+ "simple/dwm",
+ "simple/dynamics365",
+ "simple/dynatrace",
+ "simple/e",
+ "simple/ea",
+ "simple/eagle",
+ "simple/easyjet",
+ "simple/ebay",
+ "simple/eclipseche",
+ "simple/eclipseide",
+ "simple/eclipsejetty",
+ "simple/eclipsemosquitto",
+ "simple/eclipsevertdotx",
+ "simple/edeka",
+ "simple/editorconfig",
+ "simple/edotleclerc",
+ "simple/edx",
+ "simple/egghead",
+ "simple/egnyte",
+ "simple/eightsleep",
+ "simple/elastic",
+ "simple/elasticcloud",
+ "simple/elasticsearch",
+ "simple/elasticstack",
+ "simple/electron",
+ "simple/electronbuilder",
+ "simple/element",
+ "simple/elementary",
+ "simple/elementor",
+ "simple/eleventy",
+ "simple/elixir",
+ "simple/eljueves",
+ "simple/ello",
+ "simple/elm",
+ "simple/elsevier",
+ "simple/embarcadero",
+ "simple/emberdotjs",
+ "simple/emby",
+ "simple/emirates",
+ "simple/emlakjet",
+ "simple/empirekred",
+ "simple/enpass",
+ "simple/enterprisedb",
+ "simple/envato",
+ "simple/epel",
+ "simple/epicgames",
+ "simple/epson",
+ "simple/equinixmetal",
+ "simple/erlang",
+ "simple/esbuild",
+ "simple/esea",
+ "simple/eslgaming",
+ "simple/eslint",
+ "simple/esphome",
+ "simple/espressif",
+ "simple/etcd",
+ "simple/ethereum",
+ "simple/ethiopianairlines",
+ "simple/etihadairways",
+ "simple/etsy",
+ "simple/eventbrite",
+ "simple/eventstore",
+ "simple/evernote",
+ "simple/exercism",
+ "simple/exordo",
+ "simple/exoscale",
+ "simple/expensify",
+ "simple/expertsexchange",
+ "simple/expo",
+ "simple/express",
+ "simple/expressvpn",
+ "simple/eyeem",
+ "simple/f1",
+ "simple/f5",
+ "simple/facebook",
+ "simple/facebookgaming",
+ "simple/facebooklive",
+ "simple/faceit",
+ "simple/facepunch",
+ "simple/falcon",
+ "simple/fampay",
+ "simple/fandango",
+ "simple/fandom",
+ "simple/farfetch",
+ "simple/fastapi",
+ "simple/fastify",
+ "simple/fastlane",
+ "simple/fastly",
+ "simple/fathom",
+ "simple/fauna",
+ "simple/favro",
+ "simple/fdroid",
+ "simple/feathub",
+ "simple/fedex",
+ "simple/fedora",
+ "simple/feedly",
+ "simple/ferrari",
+ "simple/ferrarinv",
+ "simple/ffmpeg",
+ "simple/fiat",
+ "simple/fidoalliance",
+ "simple/fifa",
+ "simple/figma",
+ "simple/figshare",
+ "simple/fila",
+ "simple/files",
+ "simple/filezilla",
+ "simple/fing",
+ "simple/firebase",
+ "simple/firefox",
+ "simple/firefoxbrowser",
+ "simple/first",
+ "simple/fitbit",
+ "simple/fite",
+ "simple/fivem",
+ "simple/fiverr",
+ "simple/flask",
+ "simple/flat",
+ "simple/flathub",
+ "simple/flatpak",
+ "simple/flattr",
+ "simple/flickr",
+ "simple/flipboard",
+ "simple/flipkart",
+ "simple/floatplane",
+ "simple/flood",
+ "simple/fluentbit",
+ "simple/fluentd",
+ "simple/flutter",
+ "simple/flyway",
+ "simple/fmod",
+ "simple/fnac",
+ "simple/folium",
+ "simple/fonoma",
+ "simple/fontawesome",
+ "simple/fontbase",
+ "simple/foodpanda",
+ "simple/ford",
+ "simple/forestry",
+ "simple/formstack",
+ "simple/fortinet",
+ "simple/fortran",
+ "simple/fossa",
+ "simple/fossilscm",
+ "simple/foursquare",
+ "simple/foursquarecityguide",
+ "simple/foxtel",
+ "simple/fozzy",
+ "simple/framer",
+ "simple/framework7",
+ "simple/franprix",
+ "simple/fraunhofergesellschaft",
+ "simple/freebsd",
+ "simple/freecodecamp",
+ "simple/freedesktopdotorg",
+ "simple/freelancer",
+ "simple/freenas",
+ "simple/frontendmentor",
+ "simple/fsecure",
+ "simple/fugacloud",
+ "simple/fujifilm",
+ "simple/fujitsu",
+ "simple/funimation",
+ "simple/furaffinity",
+ "simple/furrynetwork",
+ "simple/futurelearn",
+ "simple/g2",
+ "simple/g2a",
+ "simple/gameandwatch",
+ "simple/gamejolt",
+ "simple/garmin",
+ "simple/gatling",
+ "simple/gatsby",
+ "simple/geant",
+ "simple/geeksforgeeks",
+ "simple/generalelectric",
+ "simple/generalmotors",
+ "simple/genius",
+ "simple/gentoo",
+ "simple/geocaching",
+ "simple/gerrit",
+ "simple/ghost",
+ "simple/ghostery",
+ "simple/gimp",
+ "simple/giphy",
+ "simple/git",
+ "simple/gitbook",
+ "simple/gitea",
+ "simple/gitee",
+ "simple/gitextensions",
+ "simple/github",
+ "simple/githubactions",
+ "simple/githubpages",
+ "simple/githubsponsors",
+ "simple/gitignoredotio",
+ "simple/gitkraken",
+ "simple/gitlab",
+ "simple/gitlfs",
+ "simple/gitpod",
+ "simple/gitter",
+ "simple/glassdoor",
+ "simple/glitch",
+ "simple/globus",
+ "simple/gmail",
+ "simple/gnome",
+ "simple/gnometerminal",
+ "simple/gnu",
+ "simple/gnubash",
+ "simple/gnuemacs",
+ "simple/gnuicecat",
+ "simple/gnuprivacyguard",
+ "simple/gnusocial",
+ "simple/go",
+ "simple/gocd",
+ "simple/godaddy",
+ "simple/godotengine",
+ "simple/gofundme",
+ "simple/gogdotcom",
+ "simple/goland",
+ "simple/goldenline",
+ "simple/goodreads",
+ "simple/google",
+ "simple/googleadmob",
+ "simple/googleads",
+ "simple/googleadsense",
+ "simple/googleanalytics",
+ "simple/googleassistant",
+ "simple/googlecalendar",
+ "simple/googlecardboard",
+ "simple/googlechat",
+ "simple/googlechrome",
+ "simple/googleclassroom",
+ "simple/googlecloud",
+ "simple/googlecolab",
+ "simple/googledomains",
+ "simple/googledrive",
+ "simple/googleearth",
+ "simple/googlefit",
+ "simple/googlefonts",
+ "simple/googlehangouts",
+ "simple/googlehome",
+ "simple/googlekeep",
+ "simple/googlelens",
+ "simple/googlemaps",
+ "simple/googlemarketingplatform",
+ "simple/googlemeet",
+ "simple/googlemessages",
+ "simple/googlemybusiness",
+ "simple/googlenearby",
+ "simple/googlenews",
+ "simple/googleoptimize",
+ "simple/googlepay",
+ "simple/googlephotos",
+ "simple/googleplay",
+ "simple/googlepodcasts",
+ "simple/googlescholar",
+ "simple/googlesearchconsole",
+ "simple/googlesheets",
+ "simple/googlestreetview",
+ "simple/googletagmanager",
+ "simple/googletranslate",
+ "simple/gotomeeting",
+ "simple/grab",
+ "simple/gradle",
+ "simple/grafana",
+ "simple/grammarly",
+ "simple/grandfrais",
+ "simple/graphql",
+ "simple/grav",
+ "simple/gravatar",
+ "simple/graylog",
+ "simple/greensock",
+ "simple/griddotai",
+ "simple/gridsome",
+ "simple/groupme",
+ "simple/groupon",
+ "simple/grubhub",
+ "simple/grunt",
+ "simple/gtk",
+ "simple/guangzhoumetro",
+ "simple/guilded",
+ "simple/gulp",
+ "simple/gumroad",
+ "simple/gumtree",
+ "simple/gunicorn",
+ "simple/gurobi",
+ "simple/gutenberg",
+ "simple/habr",
+ "simple/hackaday",
+ "simple/hackclub",
+ "simple/hackerearth",
+ "simple/hackernoon",
+ "simple/hackerone",
+ "simple/hackerrank",
+ "simple/hackster",
+ "simple/hackthebox",
+ "simple/handlebarsdotjs",
+ "simple/handshake",
+ "simple/handshake_protocol",
+ "simple/happycow",
+ "simple/harbor",
+ "simple/harmonyos",
+ "simple/hashnode",
+ "simple/haskell",
+ "simple/hasura",
+ "simple/hatenabookmark",
+ "simple/haveibeenpwned",
+ "simple/haxe",
+ "simple/hbo",
+ "simple/hcl",
+ "simple/headlessui",
+ "simple/headspace",
+ "simple/hellofresh",
+ "simple/hellyhansen",
+ "simple/helm",
+ "simple/helpdesk",
+ "simple/helpscout",
+ "simple/here",
+ "simple/heroku",
+ "simple/hetzner",
+ "simple/hexo",
+ "simple/hey",
+ "simple/hibernate",
+ "simple/hibob",
+ "simple/hilton",
+ "simple/hitachi",
+ "simple/hive",
+ "simple/hive_blockchain",
+ "simple/homeadvisor",
+ "simple/homeassistant",
+ "simple/homeassistantcommunitystore",
+ "simple/homebrew",
+ "simple/homebridge",
+ "simple/homify",
+ "simple/honda",
+ "simple/hootsuite",
+ "simple/hoppscotch",
+ "simple/hotelsdotcom",
+ "simple/hotjar",
+ "simple/houdini",
+ "simple/houzz",
+ "simple/hp",
+ "simple/html5",
+ "simple/htmlacademy",
+ "simple/httpie",
+ "simple/huawei",
+ "simple/hubspot",
+ "simple/hugo",
+ "simple/hulu",
+ "simple/humblebundle",
+ "simple/hungryjacks",
+ "simple/hurriyetemlak",
+ "simple/husqvarna",
+ "simple/hyper",
+ "simple/hyperledger",
+ "simple/hypothesis",
+ "simple/hyundai",
+ "simple/i18next",
+ "simple/iata",
+ "simple/ibeacon",
+ "simple/ibm",
+ "simple/ibmcloud",
+ "simple/ibmwatson",
+ "simple/iceland",
+ "simple/icinga",
+ "simple/icloud",
+ "simple/icomoon",
+ "simple/icon",
+ "simple/iconfinder",
+ "simple/iconify",
+ "simple/iconjar",
+ "simple/icons8",
+ "simple/icq",
+ "simple/ieee",
+ "simple/ifixit",
+ "simple/ifood",
+ "simple/ifttt",
+ "simple/iheartradio",
+ "simple/ikea",
+ "simple/imagej",
+ "simple/imdb",
+ "simple/imgur",
+ "simple/immer",
+ "simple/imou",
+ "simple/indeed",
+ "simple/infiniti",
+ "simple/influxdb",
+ "simple/informatica",
+ "simple/infosys",
+ "simple/ingress",
+ "simple/inkdrop",
+ "simple/inkscape",
+ "simple/insomnia",
+ "simple/instacart",
+ "simple/instagram",
+ "simple/instapaper",
+ "simple/instatus",
+ "simple/instructables",
+ "simple/integromat",
+ "simple/intel",
+ "simple/intellijidea",
+ "simple/interactjs",
+ "simple/intercom",
+ "simple/intermarche",
+ "simple/internetarchive",
+ "simple/internetexplorer",
+ "simple/intigriti",
+ "simple/invision",
+ "simple/invoiceninja",
+ "simple/iobroker",
+ "simple/ionic",
+ "simple/ionos",
+ "simple/ios",
+ "simple/iota",
+ "simple/ipfs",
+ "simple/issuu",
+ "simple/istio",
+ "simple/itchdotio",
+ "simple/iterm2",
+ "simple/itunes",
+ "simple/iveco",
+ "simple/jabber",
+ "simple/jaguar",
+ "simple/jamboard",
+ "simple/jameson",
+ "simple/jamstack",
+ "simple/jasmine",
+ "simple/javascript",
+ "simple/jbl",
+ "simple/jcb",
+ "simple/jeep",
+ "simple/jekyll",
+ "simple/jellyfin",
+ "simple/jenkins",
+ "simple/jenkinsx",
+ "simple/jest",
+ "simple/jet",
+ "simple/jetbrains",
+ "simple/jetpackcompose",
+ "simple/jfrog",
+ "simple/jfrogbintray",
+ "simple/jinja",
+ "simple/jira",
+ "simple/jirasoftware",
+ "simple/jitsi",
+ "simple/johndeere",
+ "simple/joomla",
+ "simple/joplin",
+ "simple/jordan",
+ "simple/jpeg",
+ "simple/jquery",
+ "simple/jrgroup",
+ "simple/jsdelivr",
+ "simple/jsfiddle",
+ "simple/json",
+ "simple/jsonwebtokens",
+ "simple/jss",
+ "simple/julia",
+ "simple/junipernetworks",
+ "simple/junit5",
+ "simple/jupyter",
+ "simple/justeat",
+ "simple/justgiving",
+ "simple/k3s",
+ "simple/k6",
+ "simple/kaggle",
+ "simple/kahoot",
+ "simple/kaios",
+ "simple/kakao",
+ "simple/kakaotalk",
+ "simple/kalilinux",
+ "simple/kaniko",
+ "simple/karlsruherverkehrsverbund",
+ "simple/kasasmart",
+ "simple/kashflow",
+ "simple/kaspersky",
+ "simple/katacoda",
+ "simple/katana",
+ "simple/kaufland",
+ "simple/kde",
+ "simple/kdenlive",
+ "simple/keepachangelog",
+ "simple/keepassxc",
+ "simple/kentico",
+ "simple/keras",
+ "simple/keybase",
+ "simple/keycdn",
+ "simple/keystone",
+ "simple/kfc",
+ "simple/khanacademy",
+ "simple/khronosgroup",
+ "simple/kia",
+ "simple/kibana",
+ "simple/kicad",
+ "simple/kickstarter",
+ "simple/kik",
+ "simple/kingstontechnology",
+ "simple/kinopoisk",
+ "simple/kirby",
+ "simple/kitsu",
+ "simple/klarna",
+ "simple/klm",
+ "simple/klook",
+ "simple/knative",
+ "simple/knowledgebase",
+ "simple/known",
+ "simple/koa",
+ "simple/koc",
+ "simple/kodi",
+ "simple/kofax",
+ "simple/kofi",
+ "simple/komoot",
+ "simple/konami",
+ "simple/kong",
+ "simple/kongregate",
+ "simple/konva",
+ "simple/kotlin",
+ "simple/koyeb",
+ "simple/krita",
+ "simple/ktm",
+ "simple/kuaishou",
+ "simple/kubernetes",
+ "simple/kubuntu",
+ "simple/kuma",
+ "simple/kyocera",
+ "simple/labview",
+ "simple/lada",
+ "simple/lamborghini",
+ "simple/landrover",
+ "simple/lapce",
+ "simple/laragon",
+ "simple/laravel",
+ "simple/laravelhorizon",
+ "simple/laravelnova",
+ "simple/lastdotfm",
+ "simple/lastpass",
+ "simple/latex",
+ "simple/launchpad",
+ "simple/lazarus",
+ "simple/lbry",
+ "simple/leaderprice",
+ "simple/leaflet",
+ "simple/leanpub",
+ "simple/leetcode",
+ "simple/legacygames",
+ "simple/lemmy",
+ "simple/lenovo",
+ "simple/lens",
+ "simple/lerna",
+ "simple/leroymerlin",
+ "simple/less",
+ "simple/letsencrypt",
+ "simple/letterboxd",
+ "simple/levelsdotfyi",
+ "simple/lg",
+ "simple/lgtm",
+ "simple/liberapay",
+ "simple/librariesdotio",
+ "simple/librarything",
+ "simple/libreoffice",
+ "simple/libuv",
+ "simple/lichess",
+ "simple/lidl",
+ "simple/lifx",
+ "simple/lighthouse",
+ "simple/line",
+ "simple/lineageos",
+ "simple/linear",
+ "simple/linkedin",
+ "simple/linkerd",
+ "simple/linkfire",
+ "simple/linktree",
+ "simple/linode",
+ "simple/linux",
+ "simple/linuxcontainers",
+ "simple/linuxfoundation",
+ "simple/linuxmint",
+ "simple/lionair",
+ "simple/liquibase",
+ "simple/lit",
+ "simple/litecoin",
+ "simple/litiengine",
+ "simple/livechat",
+ "simple/livejournal",
+ "simple/livewire",
+ "simple/llvm",
+ "simple/lmms",
+ "simple/lodash",
+ "simple/logitech",
+ "simple/logmein",
+ "simple/logstash",
+ "simple/looker",
+ "simple/loom",
+ "simple/loop",
+ "simple/loopback",
+ "simple/lospec",
+ "simple/lotpolishairlines",
+ "simple/lua",
+ "simple/lubuntu",
+ "simple/ludwig",
+ "simple/lufthansa",
+ "simple/lumen",
+ "simple/lunacy",
+ "simple/lydia",
+ "simple/lyft",
+ "simple/maas",
+ "simple/macos",
+ "simple/macys",
+ "simple/magasinsu",
+ "simple/magento",
+ "simple/magisk",
+ "simple/mailchimp",
+ "simple/maildotru",
+ "simple/mailgun",
+ "simple/majorleaguehacking",
+ "simple/makerbot",
+ "simple/mamp",
+ "simple/man",
+ "simple/manageiq",
+ "simple/manjaro",
+ "simple/mapbox",
+ "simple/mariadb",
+ "simple/mariadbfoundation",
+ "simple/markdown",
+ "simple/marketo",
+ "simple/marko",
+ "simple/marriott",
+ "simple/maserati",
+ "simple/mastercard",
+ "simple/mastercomfig",
+ "simple/mastodon",
+ "simple/materialdesign",
+ "simple/materialdesignicons",
+ "simple/matomo",
+ "simple/matrix",
+ "simple/matterdotjs",
+ "simple/mattermost",
+ "simple/matternet",
+ "simple/max",
+ "simple/maxplanckgesellschaft",
+ "simple/maytag",
+ "simple/mazda",
+ "simple/mcafee",
+ "simple/mcdonalds",
+ "simple/mclaren",
+ "simple/mdbook",
+ "simple/mdnwebdocs",
+ "simple/mdx",
+ "simple/mediafire",
+ "simple/mediamarkt",
+ "simple/mediatek",
+ "simple/mediatemple",
+ "simple/medium",
+ "simple/meetup",
+ "simple/mega",
+ "simple/mendeley",
+ "simple/mercedes",
+ "simple/merck",
+ "simple/mercurial",
+ "simple/messenger",
+ "simple/meta",
+ "simple/metabase",
+ "simple/metafilter",
+ "simple/meteor",
+ "simple/metro",
+ "simple/metrodelaciudaddemexico",
+ "simple/metrodemadrid",
+ "simple/metrodeparis",
+ "simple/mewe",
+ "simple/microbit",
+ "simple/microdotblog",
+ "simple/microgenetics",
+ "simple/micropython",
+ "simple/microsoft",
+ "simple/microsoftacademic",
+ "simple/microsoftaccess",
+ "simple/microsoftazure",
+ "simple/microsoftbing",
+ "simple/microsoftedge",
+ "simple/microsoftexcel",
+ "simple/microsoftexchange",
+ "simple/microsoftoffice",
+ "simple/microsoftonedrive",
+ "simple/microsoftonenote",
+ "simple/microsoftoutlook",
+ "simple/microsoftpowerpoint",
+ "simple/microsoftsharepoint",
+ "simple/microsoftsqlserver",
+ "simple/microsoftteams",
+ "simple/microsofttranslator",
+ "simple/microsoftvisio",
+ "simple/microsoftword",
+ "simple/microstrategy",
+ "simple/midi",
+ "simple/minds",
+ "simple/minecraft",
+ "simple/minetest",
+ "simple/mini",
+ "simple/minutemailer",
+ "simple/miro",
+ "simple/mitsubishi",
+ "simple/mix",
+ "simple/mixcloud",
+ "simple/mlb",
+ "simple/mlflow",
+ "simple/mobx",
+ "simple/mobxstatetree",
+ "simple/mocha",
+ "simple/modx",
+ "simple/mojangstudios",
+ "simple/moleculer",
+ "simple/momenteo",
+ "simple/monero",
+ "simple/moneygram",
+ "simple/mongodb",
+ "simple/monkeytie",
+ "simple/monogames",
+ "simple/monoprix",
+ "simple/monster",
+ "simple/monzo",
+ "simple/moo",
+ "simple/morrisons",
+ "simple/moscowmetro",
+ "simple/motorola",
+ "simple/mozilla",
+ "simple/msi",
+ "simple/msibusiness",
+ "simple/mta",
+ "simple/mtr",
+ "simple/mui",
+ "simple/mulesoft",
+ "simple/muller",
+ "simple/mumble",
+ "simple/musescore",
+ "simple/musicbrainz",
+ "simple/mxlinux",
+ "simple/myanimelist",
+ "simple/myob",
+ "simple/myspace",
+ "simple/mysql",
+ "simple/n26",
+ "simple/namebase",
+ "simple/namecheap",
+ "simple/nano",
+ "simple/nasa",
+ "simple/nationalgrid",
+ "simple/nativescript",
+ "simple/naver",
+ "simple/nba",
+ "simple/nbb",
+ "simple/ndr",
+ "simple/nec",
+ "simple/neo4j",
+ "simple/neovim",
+ "simple/nestjs",
+ "simple/netapp",
+ "simple/netbsd",
+ "simple/netflix",
+ "simple/netlify",
+ "simple/nette",
+ "simple/netto",
+ "simple/neutralinojs",
+ "simple/newbalance",
+ "simple/newjapanprowrestling",
+ "simple/newrelic",
+ "simple/newyorktimes",
+ "simple/nextbilliondotai",
+ "simple/nextcloud",
+ "simple/nextdoor",
+ "simple/nextdotjs",
+ "simple/nfc",
+ "simple/nginx",
+ "simple/ngrok",
+ "simple/niconico",
+ "simple/nike",
+ "simple/nim",
+ "simple/nintendo",
+ "simple/nintendo3ds",
+ "simple/nintendogamecube",
+ "simple/nintendonetwork",
+ "simple/nintendoswitch",
+ "simple/nissan",
+ "simple/nixos",
+ "simple/nodedotjs",
+ "simple/nodemon",
+ "simple/nodered",
+ "simple/nokia",
+ "simple/norco",
+ "simple/nordvpn",
+ "simple/norwegian",
+ "simple/notepadplusplus",
+ "simple/notion",
+ "simple/notist",
+ "simple/nounproject",
+ "simple/now",
+ "simple/npm",
+ "simple/nrwl",
+ "simple/nubank",
+ "simple/nucleo",
+ "simple/nuget",
+ "simple/nuke",
+ "simple/numba",
+ "simple/numpy",
+ "simple/nunjucks",
+ "simple/nutanix",
+ "simple/nuxtdotjs",
+ "simple/nvidia",
+ "simple/nx",
+ "simple/nzxt",
+ "simple/observable",
+ "simple/obsidian",
+ "simple/obsstudio",
+ "simple/ocaml",
+ "simple/octanerender",
+ "simple/octave",
+ "simple/octoprint",
+ "simple/octopusdeploy",
+ "simple/oculus",
+ "simple/odnoklassniki",
+ "simple/odysee",
+ "simple/ohdear",
+ "simple/okcupid",
+ "simple/okta",
+ "simple/oneplus",
+ "simple/onlyfans",
+ "simple/onlyoffice",
+ "simple/onnx",
+ "simple/onstar",
+ "simple/opel",
+ "simple/openaccess",
+ "simple/openai",
+ "simple/openaigym",
+ "simple/openapiinitiative",
+ "simple/openbadges",
+ "simple/openbsd",
+ "simple/openbugbounty",
+ "simple/opencollective",
+ "simple/opencontainersinitiative",
+ "simple/opencv",
+ "simple/openfaas",
+ "simple/opengl",
+ "simple/openid",
+ "simple/openjdk",
+ "simple/openlayers",
+ "simple/openmined",
+ "simple/opennebula",
+ "simple/openproject",
+ "simple/opensea",
+ "simple/opensearch",
+ "simple/opensourceinitiative",
+ "simple/openssl",
+ "simple/openstack",
+ "simple/openstreetmap",
+ "simple/opensuse",
+ "simple/opentelemetry",
+ "simple/openverse",
+ "simple/openvpn",
+ "simple/openwrt",
+ "simple/openzeppelin",
+ "simple/openzfs",
+ "simple/opera",
+ "simple/opnsense",
+ "simple/opsgenie",
+ "simple/opslevel",
+ "simple/oracle",
+ "simple/orcid",
+ "simple/oreilly",
+ "simple/org",
+ "simple/origin",
+ "simple/osano",
+ "simple/oshkosh",
+ "simple/osmc",
+ "simple/osu",
+ "simple/otto",
+ "simple/overcast",
+ "simple/overleaf",
+ "simple/ovh",
+ "simple/owasp",
+ "simple/oxygen",
+ "simple/oyo",
+ "simple/p5dotjs",
+ "simple/packagist",
+ "simple/packer",
+ "simple/paddypower",
+ "simple/pagekit",
+ "simple/pagerduty",
+ "simple/pagespeedinsights",
+ "simple/pagseguro",
+ "simple/palantir",
+ "simple/paloaltosoftware",
+ "simple/pandas",
+ "simple/pandora",
+ "simple/pantheon",
+ "simple/paperspace",
+ "simple/paritysubstrate",
+ "simple/parsedotly",
+ "simple/passport",
+ "simple/pastebin",
+ "simple/patreon",
+ "simple/payoneer",
+ "simple/paypal",
+ "simple/paytm",
+ "simple/pcgamingwiki",
+ "simple/peakdesign",
+ "simple/peertube",
+ "simple/pegasusairlines",
+ "simple/pelican",
+ "simple/peloton",
+ "simple/penny",
+ "simple/pepsi",
+ "simple/percy",
+ "simple/perforce",
+ "simple/perl",
+ "simple/personio",
+ "simple/petsathome",
+ "simple/peugeot",
+ "simple/pexels",
+ "simple/pfsense",
+ "simple/phabricator",
+ "simple/philipshue",
+ "simple/phonepe",
+ "simple/photobucket",
+ "simple/photocrowd",
+ "simple/photopea",
+ "simple/php",
+ "simple/phpmyadmin",
+ "simple/phpstorm",
+ "simple/picardsurgeles",
+ "simple/picartodottv",
+ "simple/picnic",
+ "simple/picpay",
+ "simple/pihole",
+ "simple/pimcore",
+ "simple/pinboard",
+ "simple/pingdom",
+ "simple/pinterest",
+ "simple/pioneerdj",
+ "simple/pivotaltracker",
+ "simple/piwigo",
+ "simple/pix",
+ "simple/pixabay",
+ "simple/pixiv",
+ "simple/pkgsrc",
+ "simple/planet",
+ "simple/planetscale",
+ "simple/plangrid",
+ "simple/platformdotsh",
+ "simple/platzi",
+ "simple/plausibleanalytics",
+ "simple/playcanvas",
+ "simple/playerdotme",
+ "simple/playerfm",
+ "simple/playstation",
+ "simple/playstation2",
+ "simple/playstation3",
+ "simple/playstation4",
+ "simple/playstation5",
+ "simple/playstationvita",
+ "simple/playwright",
+ "simple/pleroma",
+ "simple/plesk",
+ "simple/plex",
+ "simple/plotly",
+ "simple/pluralsight",
+ "simple/plurk",
+ "simple/pluscodes",
+ "simple/pm2",
+ "simple/pnpm",
+ "simple/pocket",
+ "simple/pocketbase",
+ "simple/pocketcasts",
+ "simple/podcastaddict",
+ "simple/podman",
+ "simple/poetry",
+ "simple/pointy",
+ "simple/pokemon",
+ "simple/polkadot",
+ "simple/poly",
+ "simple/polymerproject",
+ "simple/polywork",
+ "simple/popos",
+ "simple/porsche",
+ "simple/portainer",
+ "simple/postcss",
+ "simple/postgresql",
+ "simple/postman",
+ "simple/postmates",
+ "simple/powerapps",
+ "simple/powerautomate",
+ "simple/powerbi",
+ "simple/powerfx",
+ "simple/powerpages",
+ "simple/powers",
+ "simple/powershell",
+ "simple/powervirtualagents",
+ "simple/prdotco",
+ "simple/preact",
+ "simple/precommit",
+ "simple/premierleague",
+ "simple/prestashop",
+ "simple/presto",
+ "simple/prettier",
+ "simple/prezi",
+ "simple/prime",
+ "simple/primevideo",
+ "simple/prisma",
+ "simple/prismic",
+ "simple/privateinternetaccess",
+ "simple/probot",
+ "simple/processingfoundation",
+ "simple/processwire",
+ "simple/producthunt",
+ "simple/progate",
+ "simple/progress",
+ "simple/prometheus",
+ "simple/prosieben",
+ "simple/protocolsdotio",
+ "simple/protodotio",
+ "simple/protondb",
+ "simple/protonmail",
+ "simple/protonvpn",
+ "simple/protools",
+ "simple/protractor",
+ "simple/proxmox",
+ "simple/pubg",
+ "simple/publons",
+ "simple/pubmed",
+ "simple/pug",
+ "simple/pulumi",
+ "simple/puma",
+ "simple/puppet",
+ "simple/puppeteer",
+ "simple/purescript",
+ "simple/purgecss",
+ "simple/purism",
+ "simple/pusher",
+ "simple/pwa",
+ "simple/pycharm",
+ "simple/pyg",
+ "simple/pypi",
+ "simple/pypy",
+ "simple/pyscaffold",
+ "simple/pytest",
+ "simple/python",
+ "simple/pytorch",
+ "simple/pytorchlightning",
+ "simple/pyup",
+ "simple/qantas",
+ "simple/qatarairways",
+ "simple/qemu",
+ "simple/qgis",
+ "simple/qi",
+ "simple/qiita",
+ "simple/qiskit",
+ "simple/qiwi",
+ "simple/qmk",
+ "simple/qt",
+ "simple/qualcomm",
+ "simple/qualtrics",
+ "simple/qualys",
+ "simple/quantcast",
+ "simple/quantconnect",
+ "simple/quarkus",
+ "simple/quasar",
+ "simple/qubesos",
+ "simple/quest",
+ "simple/quickbooks",
+ "simple/quicklook",
+ "simple/quicktime",
+ "simple/quip",
+ "simple/quora",
+ "simple/qwiklabs",
+ "simple/qzone",
+ "simple/r",
+ "simple/r3",
+ "simple/rabbitmq",
+ "simple/racket",
+ "simple/radar",
+ "simple/radiopublic",
+ "simple/railway",
+ "simple/rainmeter",
+ "simple/rakuten",
+ "simple/ram",
+ "simple/rancher",
+ "simple/rarible",
+ "simple/rasa",
+ "simple/raspberrypi",
+ "simple/ray",
+ "simple/razer",
+ "simple/razorpay",
+ "simple/react",
+ "simple/reacthookform",
+ "simple/reactivex",
+ "simple/reactos",
+ "simple/reactquery",
+ "simple/reactrouter",
+ "simple/reacttable",
+ "simple/readthedocs",
+ "simple/realm",
+ "simple/reason",
+ "simple/reasonstudios",
+ "simple/redbubble",
+ "simple/reddit",
+ "simple/redhat",
+ "simple/redhatopenshift",
+ "simple/redis",
+ "simple/redmine",
+ "simple/redux",
+ "simple/reduxsaga",
+ "simple/redwoodjs",
+ "simple/reebok",
+ "simple/relianceindustrieslimited",
+ "simple/remix",
+ "simple/renault",
+ "simple/render",
+ "simple/renovatebot",
+ "simple/renpy",
+ "simple/renren",
+ "simple/replit",
+ "simple/republicofgamers",
+ "simple/rescript",
+ "simple/rescuetime",
+ "simple/researchgate",
+ "simple/resurrectionremixos",
+ "simple/retroarch",
+ "simple/retropie",
+ "simple/revealdotjs",
+ "simple/reverbnation",
+ "simple/revoltdotchat",
+ "simple/revolut",
+ "simple/revue",
+ "simple/rewe",
+ "simple/rezgo",
+ "simple/rhinoceros",
+ "simple/rider",
+ "simple/rimacautomobili",
+ "simple/ring",
+ "simple/riotgames",
+ "simple/ripple",
+ "simple/riseup",
+ "simple/roamresearch",
+ "simple/roblox",
+ "simple/robotframework",
+ "simple/rocketdotchat",
+ "simple/rocksdb",
+ "simple/rockylinux",
+ "simple/roku",
+ "simple/rollsroyce",
+ "simple/rollupdotjs",
+ "simple/rome",
+ "simple/roots",
+ "simple/rootsbedrock",
+ "simple/rootssage",
+ "simple/ros",
+ "simple/rossmann",
+ "simple/rotaryinternational",
+ "simple/rottentomatoes",
+ "simple/roundcube",
+ "simple/rss",
+ "simple/rstudio",
+ "simple/rte",
+ "simple/rtl",
+ "simple/rtlzwei",
+ "simple/rubocop",
+ "simple/ruby",
+ "simple/rubygems",
+ "simple/rubyonrails",
+ "simple/rubysinatra",
+ "simple/runkeeper",
+ "simple/runkit",
+ "simple/rust",
+ "simple/rxdb",
+ "simple/ryanair",
+ "simple/s7airlines",
+ "simple/sabanci",
+ "simple/safari",
+ "simple/sahibinden",
+ "simple/sailfishos",
+ "simple/salesforce",
+ "simple/saltproject",
+ "simple/samsung",
+ "simple/samsungpay",
+ "simple/sandisk",
+ "simple/sanfranciscomunicipalrailway",
+ "simple/saopaulometro",
+ "simple/sap",
+ "simple/sass",
+ "simple/sat1",
+ "simple/saturn",
+ "simple/saucelabs",
+ "simple/scala",
+ "simple/scaleway",
+ "simple/scania",
+ "simple/schneiderelectric",
+ "simple/scikitlearn",
+ "simple/scipy",
+ "simple/scopus",
+ "simple/scpfoundation",
+ "simple/scratch",
+ "simple/screencastify",
+ "simple/scribd",
+ "simple/scrimba",
+ "simple/scrollreveal",
+ "simple/scrumalliance",
+ "simple/scrutinizerci",
+ "simple/seagate",
+ "simple/seat",
+ "simple/securityscorecard",
+ "simple/sefaria",
+ "simple/sega",
+ "simple/selenium",
+ "simple/sellfy",
+ "simple/semanticrelease",
+ "simple/semanticscholar",
+ "simple/semanticuireact",
+ "simple/semanticweb",
+ "simple/semaphoreci",
+ "simple/semver",
+ "simple/sencha",
+ "simple/sennheiser",
+ "simple/sensu",
+ "simple/sentry",
+ "simple/sepa",
+ "simple/sequelize",
+ "simple/serverfault",
+ "simple/serverless",
+ "simple/sessionize",
+ "simple/sfml",
+ "simple/shadow",
+ "simple/shanghaimetro",
+ "simple/sharp",
+ "simple/shazam",
+ "simple/shell",
+ "simple/shelly",
+ "simple/shenzhenmetro",
+ "simple/shieldsdotio",
+ "simple/shikimori",
+ "simple/shopify",
+ "simple/shopware",
+ "simple/shotcut",
+ "simple/showpad",
+ "simple/showtime",
+ "simple/shutterstock",
+ "simple/siemens",
+ "simple/signal",
+ "simple/simkl",
+ "simple/simpleanalytics",
+ "simple/simpleicons",
+ "simple/simplenote",
+ "simple/sinaweibo",
+ "simple/singlestore",
+ "simple/sitepoint",
+ "simple/sketch",
+ "simple/sketchfab",
+ "simple/sketchup",
+ "simple/skillshare",
+ "simple/skoda",
+ "simple/sky",
+ "simple/skynet",
+ "simple/skypack",
+ "simple/skype",
+ "simple/skypeforbusiness",
+ "simple/slack",
+ "simple/slackware",
+ "simple/slashdot",
+ "simple/slickpic",
+ "simple/slides",
+ "simple/slideshare",
+ "simple/smart",
+ "simple/smartthings",
+ "simple/smashdotgg",
+ "simple/smashingmagazine",
+ "simple/smrt",
+ "simple/smugmug",
+ "simple/snapchat",
+ "simple/snapcraft",
+ "simple/snowflake",
+ "simple/snowpack",
+ "simple/snyk",
+ "simple/socialblade",
+ "simple/society6",
+ "simple/socketdotio",
+ "simple/sogou",
+ "simple/solid",
+ "simple/solidity",
+ "simple/sololearn",
+ "simple/solus",
+ "simple/sonarcloud",
+ "simple/sonarlint",
+ "simple/sonarqube",
+ "simple/sonarsource",
+ "simple/songkick",
+ "simple/songoda",
+ "simple/sonicwall",
+ "simple/sonos",
+ "simple/sony",
+ "simple/soundcharts",
+ "simple/soundcloud",
+ "simple/sourceengine",
+ "simple/sourceforge",
+ "simple/sourcegraph",
+ "simple/sourcetree",
+ "simple/southwestairlines",
+ "simple/spacemacs",
+ "simple/spacex",
+ "simple/spacy",
+ "simple/sparkar",
+ "simple/sparkasse",
+ "simple/sparkfun",
+ "simple/sparkpost",
+ "simple/spdx",
+ "simple/speakerdeck",
+ "simple/spectrum",
+ "simple/speedtest",
+ "simple/spinnaker",
+ "simple/spinrilla",
+ "simple/splunk",
+ "simple/spond",
+ "simple/spotify",
+ "simple/spotlight",
+ "simple/spreadshirt",
+ "simple/spreaker",
+ "simple/spring",
+ "simple/spring_creators",
+ "simple/springboot",
+ "simple/springsecurity",
+ "simple/spyderide",
+ "simple/sqlite",
+ "simple/square",
+ "simple/squareenix",
+ "simple/squarespace",
+ "simple/ssrn",
+ "simple/stackbit",
+ "simple/stackblitz",
+ "simple/stackedit",
+ "simple/stackexchange",
+ "simple/stackoverflow",
+ "simple/stackpath",
+ "simple/stackshare",
+ "simple/stadia",
+ "simple/staffbase",
+ "simple/starbucks",
+ "simple/stardock",
+ "simple/starlingbank",
+ "simple/starship",
+ "simple/startrek",
+ "simple/starz",
+ "simple/statamic",
+ "simple/statuspage",
+ "simple/statuspal",
+ "simple/steam",
+ "simple/steamdb",
+ "simple/steamdeck",
+ "simple/steamworks",
+ "simple/steelseries",
+ "simple/steem",
+ "simple/steemit",
+ "simple/steinberg",
+ "simple/stellar",
+ "simple/stencyl",
+ "simple/stimulus",
+ "simple/stitcher",
+ "simple/stmicroelectronics",
+ "simple/stopstalk",
+ "simple/storyblok",
+ "simple/storybook",
+ "simple/strapi",
+ "simple/strava",
+ "simple/streamlit",
+ "simple/stripe",
+ "simple/strongswan",
+ "simple/stubhub",
+ "simple/styledcomponents",
+ "simple/stylelint",
+ "simple/styleshare",
+ "simple/stylus",
+ "simple/subaru",
+ "simple/sublimetext",
+ "simple/substack",
+ "simple/subversion",
+ "simple/suckless",
+ "simple/sumologic",
+ "simple/supabase",
+ "simple/supermicro",
+ "simple/superuser",
+ "simple/surveymonkey",
+ "simple/suse",
+ "simple/suzuki",
+ "simple/svelte",
+ "simple/svg",
+ "simple/svgo",
+ "simple/swagger",
+ "simple/swarm",
+ "simple/swc",
+ "simple/swift",
+ "simple/swiggy",
+ "simple/swiper",
+ "simple/symantec",
+ "simple/symfony",
+ "simple/symphony",
+ "simple/sympy",
+ "simple/synology",
+ "simple/tableau",
+ "simple/tablecheck",
+ "simple/tacobell",
+ "simple/tado",
+ "simple/tails",
+ "simple/tailwindcss",
+ "simple/talend",
+ "simple/talenthouse",
+ "simple/tampermonkey",
+ "simple/taobao",
+ "simple/tapas",
+ "simple/target",
+ "simple/task",
+ "simple/tasmota",
+ "simple/tata",
+ "simple/tauri",
+ "simple/taxbuzz",
+ "simple/teamcity",
+ "simple/teamspeak",
+ "simple/teamviewer",
+ "simple/ted",
+ "simple/teespring",
+ "simple/tekton",
+ "simple/tele5",
+ "simple/telegram",
+ "simple/telegraph",
+ "simple/temporal",
+ "simple/tencentqq",
+ "simple/tensorflow",
+ "simple/teradata",
+ "simple/teratail",
+ "simple/terraform",
+ "simple/tesco",
+ "simple/tesla",
+ "simple/testcafe",
+ "simple/testin",
+ "simple/testinglibrary",
+ "simple/tether",
+ "simple/textpattern",
+ "simple/thealgorithms",
+ "simple/theconversation",
+ "simple/theirishtimes",
+ "simple/themighty",
+ "simple/themodelsresource",
+ "simple/themoviedatabase",
+ "simple/thenorthface",
+ "simple/theregister",
+ "simple/thesoundsresource",
+ "simple/thespritersresource",
+ "simple/thewashingtonpost",
+ "simple/thingiverse",
+ "simple/thinkpad",
+ "simple/threadless",
+ "simple/threedotjs",
+ "simple/threema",
+ "simple/thumbtack",
+ "simple/thunderbird",
+ "simple/thymeleaf",
+ "simple/ticketmaster",
+ "simple/tidal",
+ "simple/tide",
+ "simple/tietoevry",
+ "simple/tiktok",
+ "simple/tile",
+ "simple/timescale",
+ "simple/tinder",
+ "simple/tinyletter",
+ "simple/tistory",
+ "simple/tmobile",
+ "simple/tmux",
+ "simple/todoist",
+ "simple/toggl",
+ "simple/tokyometro",
+ "simple/tomorrowland",
+ "simple/topcoder",
+ "simple/toptal",
+ "simple/torbrowser",
+ "simple/torproject",
+ "simple/toshiba",
+ "simple/toyota",
+ "simple/tplink",
+ "simple/tqdm",
+ "simple/traefikmesh",
+ "simple/traefikproxy",
+ "simple/trainerroad",
+ "simple/trakt",
+ "simple/transportforireland",
+ "simple/transportforlondon",
+ "simple/travisci",
+ "simple/treehouse",
+ "simple/trello",
+ "simple/trendmicro",
+ "simple/treyarch",
+ "simple/triller",
+ "simple/trino",
+ "simple/tripadvisor",
+ "simple/tripdotcom",
+ "simple/trove",
+ "simple/trpc",
+ "simple/truenas",
+ "simple/trulia",
+ "simple/trustedshops",
+ "simple/trustpilot",
+ "simple/tryhackme",
+ "simple/tryitonline",
+ "simple/tsnode",
+ "simple/tubi",
+ "simple/tui",
+ "simple/tumblr",
+ "simple/tunein",
+ "simple/turborepo",
+ "simple/turbosquid",
+ "simple/turkishairlines",
+ "simple/tutanota",
+ "simple/tvtime",
+ "simple/twilio",
+ "simple/twitch",
+ "simple/twitter",
+ "simple/twoo",
+ "simple/typeform",
+ "simple/typescript",
+ "simple/typo3",
+ "simple/uber",
+ "simple/ubereats",
+ "simple/ubiquiti",
+ "simple/ubisoft",
+ "simple/ublockorigin",
+ "simple/ubuntu",
+ "simple/udacity",
+ "simple/udemy",
+ "simple/ufc",
+ "simple/uikit",
+ "simple/ulule",
+ "simple/umbraco",
+ "simple/unacademy",
+ "simple/underarmour",
+ "simple/underscoredotjs",
+ "simple/undertale",
+ "simple/unicode",
+ "simple/unilever",
+ "simple/unitedairlines",
+ "simple/unity",
+ "simple/unlicense",
+ "simple/unocss",
+ "simple/unraid",
+ "simple/unrealengine",
+ "simple/unsplash",
+ "simple/untangle",
+ "simple/untappd",
+ "simple/upcloud",
+ "simple/uplabs",
+ "simple/uploaded",
+ "simple/ups",
+ "simple/upstash",
+ "simple/uptimekuma",
+ "simple/uptobox",
+ "simple/upwork",
+ "simple/usps",
+ "simple/v",
+ "simple/v2ex",
+ "simple/v8",
+ "simple/vaadin",
+ "simple/vagrant",
+ "simple/valorant",
+ "simple/valve",
+ "simple/vapor",
+ "simple/vault",
+ "simple/vauxhall",
+ "simple/vbulletin",
+ "simple/vectorlogozone",
+ "simple/vectorworks",
+ "simple/veeam",
+ "simple/veepee",
+ "simple/velog",
+ "simple/venmo",
+ "simple/vercel",
+ "simple/verdaccio",
+ "simple/veritas",
+ "simple/verizon",
+ "simple/vexxhost",
+ "simple/vfairs",
+ "simple/viadeo",
+ "simple/viber",
+ "simple/vim",
+ "simple/vimeo",
+ "simple/vimeolivestream",
+ "simple/virgin",
+ "simple/virginmedia",
+ "simple/virtualbox",
+ "simple/virustotal",
+ "simple/visa",
+ "simple/visualstudio",
+ "simple/visualstudiocode",
+ "simple/vite",
+ "simple/vitess",
+ "simple/vivaldi",
+ "simple/vivino",
+ "simple/vk",
+ "simple/vlcmediaplayer",
+ "simple/vmware",
+ "simple/vodafone",
+ "simple/volkswagen",
+ "simple/volvo",
+ "simple/vonage",
+ "simple/vowpalwabbit",
+ "simple/vox",
+ "simple/vsco",
+ "simple/vtex",
+ "simple/vuedotjs",
+ "simple/vuetify",
+ "simple/vulkan",
+ "simple/vultr",
+ "simple/w3c",
+ "simple/wacom",
+ "simple/wagtail",
+ "simple/wakatime",
+ "simple/walkman",
+ "simple/wallabag",
+ "simple/walmart",
+ "simple/wappalyzer",
+ "simple/warnerbros",
+ "simple/wasmcloud",
+ "simple/wasmer",
+ "simple/wattpad",
+ "simple/waze",
+ "simple/wearos",
+ "simple/weasyl",
+ "simple/web3dotjs",
+ "simple/webassembly",
+ "simple/webauthn",
+ "simple/webcomponentsdotorg",
+ "simple/webdriverio",
+ "simple/webflow",
+ "simple/webgl",
+ "simple/webhint",
+ "simple/weblate",
+ "simple/webmin",
+ "simple/webmoney",
+ "simple/webpack",
+ "simple/webrtc",
+ "simple/webstorm",
+ "simple/webtoon",
+ "simple/wechat",
+ "simple/wegame",
+ "simple/weightsandbiases",
+ "simple/welcometothejungle",
+ "simple/wemo",
+ "simple/westerndigital",
+ "simple/wetransfer",
+ "simple/whatsapp",
+ "simple/wheniwork",
+ "simple/whitesource",
+ "simple/wii",
+ "simple/wiiu",
+ "simple/wikidata",
+ "simple/wikidotjs",
+ "simple/wikimediacommons",
+ "simple/wikipedia",
+ "simple/wikiquote",
+ "simple/wikivoyage",
+ "simple/winamp",
+ "simple/windicss",
+ "simple/windows",
+ "simple/windows11",
+ "simple/windows95",
+ "simple/windowsterminal",
+ "simple/windowsxp",
+ "simple/winmate",
+ "simple/wipro",
+ "simple/wire",
+ "simple/wireguard",
+ "simple/wireshark",
+ "simple/wise",
+ "simple/wish",
+ "simple/wistia",
+ "simple/wix",
+ "simple/wizzair",
+ "simple/wolfram",
+ "simple/wolframlanguage",
+ "simple/wolframmathematica",
+ "simple/woo",
+ "simple/woocommerce",
+ "simple/wordpress",
+ "simple/workplace",
+ "simple/worldhealthorganization",
+ "simple/wpengine",
+ "simple/wprocket",
+ "simple/writedotas",
+ "simple/wwe",
+ "simple/wwise",
+ "simple/xamarin",
+ "simple/xaml",
+ "simple/xampp",
+ "simple/xbox",
+ "simple/xcode",
+ "simple/xdadevelopers",
+ "simple/xdotorg",
+ "simple/xero",
+ "simple/xfce",
+ "simple/xiaomi",
+ "simple/xilinx",
+ "simple/xing",
+ "simple/xmpp",
+ "simple/xo",
+ "simple/xrp",
+ "simple/xsplit",
+ "simple/xstate",
+ "simple/yahoo",
+ "simple/yale",
+ "simple/yamahacorporation",
+ "simple/yamahamotorcorporation",
+ "simple/yammer",
+ "simple/yarn",
+ "simple/ycombinator",
+ "simple/yelp",
+ "simple/yoast",
+ "simple/yolo",
+ "simple/yourtraveldottv",
+ "simple/youtube",
+ "simple/youtubegaming",
+ "simple/youtubemusic",
+ "simple/youtubestudio",
+ "simple/youtubetv",
+ "simple/yubico",
+ "simple/zabka",
+ "simple/zalando",
+ "simple/zalo",
+ "simple/zapier",
+ "simple/zara",
+ "simple/zazzle",
+ "simple/zcash",
+ "simple/zdf",
+ "simple/zebratechnologies",
+ "simple/zelle",
+ "simple/zend",
+ "simple/zendesk",
+ "simple/zendframework",
+ "simple/zenn",
+ "simple/zenodo",
+ "simple/zerodha",
+ "simple/zeromq",
+ "simple/zerply",
+ "simple/zettlr",
+ "simple/zhihu",
+ "simple/zig",
+ "simple/zigbee",
+ "simple/zillow",
+ "simple/zingat",
+ "simple/zoho",
+ "simple/zoiper",
+ "simple/zomato",
+ "simple/zoom",
+ "simple/zorin",
+ "simple/zotero",
+ "simple/zulip",
+ "simple/zwave",
+ "simple/zyte"
]
}
\ No newline at end of file
diff --git a/docs/schema/extensions/markdown.json b/docs/schema/extensions/markdown.json
index 99563b0a6..bb2f9ddbd 100644
--- a/docs/schema/extensions/markdown.json
+++ b/docs/schema/extensions/markdown.json
@@ -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,
diff --git a/docs/schema/extensions/pymdownx.json b/docs/schema/extensions/pymdownx.json
index 6617b857f..917b7859f 100644
--- a/docs/schema/extensions/pymdownx.json
+++ b/docs/schema/extensions/pymdownx.json
@@ -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"
}
},
diff --git a/docs/schema/extra.json b/docs/schema/extra.json
index 118f26fd2..67a837bb7 100644
--- a/docs/schema/extra.json
+++ b/docs/schema/extra.json
@@ -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,22 +139,25 @@
"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": {
"$ref": "#/definitions/cookie"
+ },
+ "github": {
+ "$ref": "#/definitions/cookie"
}
},
"patternProperties": {
@@ -166,19 +169,29 @@
"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",
"checked": true
}
}
+ },
+ {
+ "label": "github (default)",
+ "markdownDescription": "https://squidfunk.github.io/mkdocs-material/setup/ensuring-data-privacy/#+consent.cookies",
+ "body": {
+ "analytics": {
+ "name": "GitHub",
+ "checked": true
+ }
+ }
}
]
},
"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 +221,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 +248,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 +275,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"
}
},
diff --git a/docs/schema/plugins.json b/docs/schema/plugins.json
index adcb7dce8..b46719581 100644
--- a/docs/schema/plugins.json
+++ b/docs/schema/plugins.json
@@ -22,6 +22,9 @@
"built-in": {
"description": "Built-in plugins",
"oneOf": [
+ {
+ "$ref": "plugins/blog.json"
+ },
{
"$ref": "plugins/meta.json"
},
diff --git a/docs/schema/plugins/blog.json b/docs/schema/plugins/blog.json
new file mode 100644
index 000000000..84f714f6f
--- /dev/null
+++ b/docs/schema/plugins/blog.json
@@ -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": ""
+ },
+ "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
+ }
+ ]
+}
diff --git a/docs/schema/plugins/external/git-committers.json b/docs/schema/plugins/external/git-committers.json
index 018075312..2cf6d6147 100644
--- a/docs/schema/plugins/external/git-committers.json
+++ b/docs/schema/plugins/external/git-committers.json
@@ -23,7 +23,7 @@
},
"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"
},
},
diff --git a/docs/schema/plugins/meta.json b/docs/schema/plugins/meta.json
index d1d9cb1b0..aef3495dd 100644
--- a/docs/schema/plugins/meta.json
+++ b/docs/schema/plugins/meta.json
@@ -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\""
}
diff --git a/docs/schema/plugins/offline.json b/docs/schema/plugins/offline.json
index 36281cad2..e97b620aa 100644
--- a/docs/schema/plugins/offline.json
+++ b/docs/schema/plugins/offline.json
@@ -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
}
diff --git a/docs/schema/plugins/privacy.json b/docs/schema/plugins/privacy.json
index d229704d5..5ee1675e1 100644
--- a/docs/schema/plugins/privacy.json
+++ b/docs/schema/plugins/privacy.json
@@ -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,
diff --git a/docs/schema/plugins/search.json b/docs/schema/plugins/search.json
index ce4892090..f99370e31 100644
--- a/docs/schema/plugins/search.json
+++ b/docs/schema/plugins/search.json
@@ -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",
diff --git a/docs/schema/plugins/social.json b/docs/schema/plugins/social.json
index e70c9cc8a..161d7cf8c 100644
--- a/docs/schema/plugins/social.json
+++ b/docs/schema/plugins/social.json
@@ -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"
}
diff --git a/docs/schema/plugins/tags.json b/docs/schema/plugins/tags.json
index 5a7ab1aa8..72b89b966 100644
--- a/docs/schema/plugins/tags.json
+++ b/docs/schema/plugins/tags.json
@@ -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$": {
diff --git a/docs/schema/theme.json b/docs/schema/theme.json
index f8762aab5..6ca89d158 100644
--- a/docs/schema/theme.json
+++ b/docs/schema/theme.json
@@ -436,6 +436,9 @@
"markdownDescription": "https://squidfunk.github.io/mkdocs-material/setup/changing-the-logo-and-icons/",
"type": "object",
"properties": {
+ "edit": {
+ "$ref": "#/definitions/icon"
+ },
"logo": {
"$ref": "#/definitions/icon"
},
@@ -550,6 +553,10 @@
},
"additionalProperties": false,
"defaultSnippets": [
+ {
+ "label": "edit",
+ "body": "edit: ${1:material/pencil}"
+ },
{
"label": "logo",
"body": "logo: ${1:material/library}"
diff --git a/docs/setup/adding-a-comment-system.md b/docs/setup/adding-a-comment-system.md
index 045bae784..a1a3eafed 100644
--- a/docs/setup/adding-a-comment-system.md
+++ b/docs/setup/adding-a-comment-system.md
@@ -42,24 +42,14 @@ Before you can use [Giscus], you need to complete the following steps:
```
-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() }}
-
-
+``` html hl_lines="3"
+{% if page.meta.comments %}
-
+
-{% 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
diff --git a/docs/setup/adding-a-git-repository.md b/docs/setup/adding-a-git-repository.md
index 064ce3e1e..a559de27b 100644
--- a/docs/setup/adding-a-git-repository.md
+++ b/docs/setup/adding-a-git-repository.md
@@ -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:
+
+
+
+ [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 `/`:
diff --git a/docs/setup/building-for-offline-usage.md b/docs/setup/building-for-offline-usage.md
index 3dfaab680..ddba28612 100644
--- a/docs/setup/building-for-offline-usage.md
+++ b/docs/setup/building-for-offline-usage.md
@@ -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
diff --git a/docs/setup/changing-the-colors.md b/docs/setup/changing-the-colors.md
index bf503e530..a40d45aa8 100644
--- a/docs/setup/changing-the-colors.md
+++ b/docs/setup/changing-the-colors.md
@@ -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:
})
- [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:
})
- [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:
})
- [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:
diff --git a/docs/setup/changing-the-fonts.md b/docs/setup/changing-the-fonts.md
index d431c937b..ab8a5d239 100644
--- a/docs/setup/changing-the-fonts.md
+++ b/docs/setup/changing-the-fonts.md
@@ -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:
diff --git a/docs/setup/changing-the-language.md b/docs/setup/changing-the-language.md
index b1eb0a67e..598f53dd5 100644
--- a/docs/setup/changing-the-language.md
+++ b/docs/setup/changing-the-language.md
@@ -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:
})
- [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
@@ -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:
diff --git a/docs/setup/changing-the-logo-and-icons.md b/docs/setup/changing-the-logo-and-icons.md
index 54e9da5f3..57cbcc9c6 100644
--- a/docs/setup/changing-the-logo-and-icons.md
+++ b/docs/setup/changing-the-logo-and-icons.md
@@ -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`:
- [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
diff --git a/docs/setup/ensuring-data-privacy.md b/docs/setup/ensuring-data-privacy.md
index 8d7a04271..e6a5a41da 100644
--- a/docs/setup/ensuring-data-privacy.md
+++ b/docs/setup/ensuring-data-privacy.md
@@ -6,23 +6,23 @@ template: overrides/main.html
Material for MkDocs makes compliance with data privacy regulations very easy,
as it offers a native [cookie consent] solution to seek explicit consent from
-users before setting up [tracking]. Additionally, external assets can be
+users before setting up [analytics]. Additionally, external assets can be
automatically downloaded for [self-hosting].
- [cookie consent]: #native-cookie-consent
- [tracking]: setting-up-site-analytics.md
+ [cookie consent]: #cookie-consent
+ [analytics]: setting-up-site-analytics.md
[self-hosting]: #built-in-privacy-plugin
## Configuration
-### Cookie consent { #native-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
Material for MkDocs ships a native and extensible cookie consent form which
-asks the user for consent prior to sending any data via analytics. Add the
+asks the user for consent prior to sending requests to third parties. Add the
following to `mkdocs.yml`:
``` yaml
@@ -41,25 +41,30 @@ 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`
- cookie. Each cookie must receive a unique identifier which is used as a key
- in the `cookies` map, and can be either set to a string, or to a map
- defining `name` and `checked` state:
+ cookies or change the initial `checked` state and name of built-in cookies.
+ Currently, the following cookies are built-in:
+
+ - __Google Analytics__ – `analytics` (enabled by default)
+ - __GitHub__ – `github` (enabled by default)
+
+ Each cookie must receive a unique identifier which is used as a key in the
+ `cookies` map, and can be either set to a string, or to a map defining
+ `name` and `checked` state:
=== "Custom cookie name"
@@ -95,11 +100,11 @@ The following properties are available:
the `analytics` cookie must be added back explicitly, or analytics
won't be triggered.
-
- If Google Analytics was configured via `mkdocs.yml`, the cookie consent will automatically include a setting for the user to disable it. [Custom cookies]
+ If Google Analytics was configured via `mkdocs.yml`, the cookie consent will
+ automatically include a setting for the user to disable it. [Custom cookies]
can be used from JavaScript.
-`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 +126,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 +173,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 +185,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 +209,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 +221,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 +445,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 +454,7 @@ check whether the user accepted it:
}
```
-=== ":octicons-file-code-16: mkdocs.yml"
+=== ":octicons-file-code-16: `mkdocs.yml`"
``` yaml
extra_javascript:
diff --git a/docs/setup/extensions/python-markdown-extensions.md b/docs/setup/extensions/python-markdown-extensions.md
index 5335ef90a..18644eb3c 100644
--- a/docs/setup/extensions/python-markdown-extensions.md
+++ b/docs/setup/extensions/python-markdown-extensions.md
@@ -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
diff --git a/docs/setup/extensions/python-markdown.md b/docs/setup/extensions/python-markdown.md
index bcd9c2ac7..d29bba97e 100644
--- a/docs/setup/extensions/python-markdown.md
+++ b/docs/setup/extensions/python-markdown.md
@@ -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
diff --git a/docs/setup/setting-up-a-blog.md b/docs/setup/setting-up-a-blog.md
new file mode 100644
index 000000000..5bb1e305b
--- /dev/null
+++ b/docs/setup/setting-up-a-blog.md
@@ -0,0 +1,1219 @@
+---
+template: overrides/main.html
+status: new
+---
+
+# Setting up a blog
+
+Material for MkDocs makes it very easy to build a blog, either as a sidecar to
+your documentation or standalone. Focus on your content while the engine does
+all the heavy lifting, automatically generating [archive] and [category]
+indexes, [post slugs], configurable [pagination] and more.
+
+---
+
+__Check out our [blog], which is created with the new [built-in blog plugin]!__
+
+ [archive]: #archive
+ [category]: #categories
+ [post slugs]: #+blog.post_url_format
+ [pagination]: #pagination
+ [blog]: ../blog/index.md
+
+## Configuration
+
+### Built-in blog plugin :material-alert-decagram:{ .mdx-pulse title="Added on September 12, 2022" }
+
+[:octicons-heart-fill-24:{ .mdx-heart } Sponsors only][Insiders]{ .mdx-insiders } ·
+[:octicons-tag-24: insiders-4.23.0][Insiders] ·
+:octicons-cpu-24: Plugin ·
+:octicons-beaker-24: Experimental
+
+The built-in blog plugin adds support for building a blog from a folder of
+posts, which are annotated with dates and other structured data. First, add the
+following lines to `mkdocs.yml`:
+
+``` yaml
+plugins:
+ - blog
+```
+
+> If you need to be able to build your documentation with and without
+> [Insiders], please refer to the [built-in plugins] section to learn how
+> shared configurations help to achieve this.
+
+By default, the built-in blog plugin assumes that your blog is hosted inside
+the `blog` subfolder of your documentation ([this is configurable]). Next,
+you need to create the following structure:
+
+``` sh
+.
+├─ docs/
+│ └─ blog/
+│ ├─ posts/
+│ └─ index.md
+└─ mkdocs.yml
+```
+
+Since the built-in blog plugin auto-generates [archive] and [category] indexes,
+it must know where to add those to the navigation. Thus, make sure to add a
+`blog/index.md` file in `mkdocs.yml`:
+
+``` yaml
+nav:
+ - Blog:
+ - blog/index.md # (1)!
+```
+
+1. Within this file, you can specify the title of your blog, which is then
+ picked up and used by the built-in blog plugin:
+
+ ``` markdown
+ # Blog
+ ```
+
+The following configuration options are available:
+
+[`enabled`](#+blog.enabled){ #+blog.enabled }
+
+: :octicons-milestone-24: Default: `true` – This option specifies whether
+ the plugin is enabled when building your project. If you want to switch
+ the plugin off, you can disable it with the following lines:
+
+ ``` yaml
+ plugins:
+ - blog:
+ enabled: false
+ ```
+
+[`blog_dir`](#+blog.blog_dir){ #+blog.blog_dir }
+
+: :octicons-milestone-24: Default: `blog` – This option specifies the folder
+ where your posts and metadata live. The name of the folder will also be
+ included in the generated URLs as a prefix to all blog-related pages. If
+ you want to build a standalone blog, change it to `.`:
+
+ === "Subdirectory"
+
+ ``` yaml
+ plugins:
+ - blog:
+ blog_dir: path/to/folder
+ ```
+
+ === "Standalone"
+
+ ``` yaml
+ plugins:
+ - blog:
+ blog_dir: .
+ ```
+
+ The path must be defined relative to [`docs_dir`][docs_dir].
+
+__The built-in blog plugin has dozens of options that allow for advanced
+configuration. It's a good idea to [start writing your first post], and come
+back here later for fine-tuning the output.__
+
+---
+
+ [Insiders]: ../insiders/index.md
+ [built-in plugins]: ../insiders/getting-started.md#built-in-plugins
+ [this is configurable]: #+blog.blog_dir
+ [environment variable]: https://www.mkdocs.org/user-guide/configuration/#environment-variables
+ [docs_dir]: https://www.mkdocs.org/user-guide/configuration/#docs_dir
+ [start writing your first post]: #writing-your-first-post
+
+#### Posts
+
+The following configuration options are available for posts:
+
+[`post_date_format`](#+blog.post_date_format){ #+blog.post_date_format }
+
+: :octicons-milestone-24: Default: `long` – This option specifies the date
+ format that is used when posts are rendered. Under the hood, the
+ [built-in blog plugin] leverages [Babel] to render dates locale-aware using
+ the configured [site language]. The following formats are supported:
+
+ === "Monday, January 31, 2022"
+
+ ``` yaml
+ plugins:
+ - blog:
+ post_date_format: full
+ ```
+
+ === "January 31, 2022"
+
+ ``` yaml
+ plugins:
+ - blog:
+ post_date_format: long
+ ```
+
+ === "Jan 31, 2022"
+
+ ``` yaml
+ plugins:
+ - blog:
+ post_date_format: medium
+ ```
+
+ === "1/31/22"
+
+ ``` yaml
+ plugins:
+ - blog:
+ post_date_format: short
+ ```
+
+ Note that depending on the [site language], formats might look different
+ for other languages. Additionally, [Babel] supports a [pattern syntax]
+ which allows for custom formats.
+
+[`post_url_date_format`](#+blog.post_url_date_format){ #+blog.post_url_date_format }
+
+: :octicons-milestone-24: Default: `YYYY/MM/dd` – This option specifies the
+ date format that is used in the URL of the post. The format string must
+ adhere to [Babel]'s [pattern syntax]. Some examples:
+
+ === ":material-link: blog/2022/01/31/:material-dots-horizontal:/"
+
+ ``` yaml
+ plugins:
+ - blog:
+ post_url_date_format: YYYY/MM/dd
+ ```
+
+ === ":material-link: blog/2022/01/:material-dots-horizontal:/"
+
+ ``` yaml
+ plugins:
+ - blog:
+ post_url_date_format: YYYY/MM
+ ```
+
+ === ":material-link: blog/2022/:material-dots-horizontal:/"
+
+ ``` yaml
+ plugins:
+ - blog:
+ post_url_date_format: YYYY
+ ```
+
+ If you want to exclude the date altogether, e.g. when your blog features
+ mostly evergreen content, you can remove the `date` placeholder from
+ the format string (see below).
+
+[`post_url_format`](#+blog.post_url_format){ #+blog.post_url_format }
+
+: :octicons-milestone-24: Default: `{date}/{slug}` – This option specifies the
+ format string that is used for the URL of the post. The following
+ placeholders are currently supported:
+
+ - `date`: Replaced with the post's date, as configured in
+ [`post_url_date_format`][post_url_date_format].
+
+ - `slug`: Replaced with a slug generated from the post's title.
+
+ === ":material-link: blog/2022/:material-dots-horizontal:/"
+
+ ``` yaml
+ plugins:
+ - blog:
+ post_url_format: "{date}/{slug}"
+ ```
+
+ === ":material-link: blog/:material-dots-horizontal:/"
+
+ ``` yaml
+ plugins:
+ - blog:
+ post_url_format: "{slug}"
+ ```
+
+ If you remove the `date` placeholder, make sure that post URLs don't
+ collide with other the URLs of other pages added to the blog section, as
+ this leads to undefined behavior.
+
+[`post_slugify`](#+blog.post_slugify){ #+blog.post_slugify }
+
+: :octicons-milestone-24: Default: `headerid.slugify` – This option specifies
+ which function to use for generating URL-compatible slugs from post titles.
+ [Python Markdown Extensions] comes with several Unicode-aware
+ slug functions which should be a good choice for non-ASCII languages:
+
+ === "Unicode"
+
+ ``` yaml
+ plugins:
+ - blog:
+ post_slugify: !!python/name:pymdownx.slugs.uslugify
+ ```
+
+ === "Unicode, case-sensitive"
+
+ ``` yaml
+ plugins:
+ - blog:
+ post_slugify: !!python/name:pymdownx.slugs.uslugify_cased
+ ```
+
+[`post_slugify_separator`](#+blog.post_slugify_separator){ #+blog.post_slugify_separator }
+
+: :octicons-milestone-24: Default: `-` – This option specifies the separator
+ which is used by the slug function. By default, a hyphen is used, but it can
+ be changed to any string, including the empty string:
+
+ ``` yaml
+ plugins:
+ - blog:
+ post_slugify_separator: "-"
+ ```
+
+[`post_excerpt`](#+blog.post_excerpt){ #+blog.post_excerpt }
+
+: :octicons-milestone-24: Default: `optional` – This option specifies whether
+ [post excerpts] should be considered being optional or required by the
+ [built-in blog plugin] when generating indexes. If excerpts are required,
+ the plugin terminates with an error if a post doesn't define an excerpt:
+
+ === "Optional"
+
+ ``` yaml
+ plugins:
+ - blog:
+ post_excerpt: optional
+ ```
+
+ === "Required"
+
+ ``` yaml
+ plugins:
+ - blog:
+ post_excerpt: required
+ ```
+
+[`post_excerpt_separator`](#+blog.post_excerpt_separator){ #+blog.post_excerpt_separator }
+
+: :octicons-milestone-24: Default: `` – This option specifies
+ the separator the [built-in blog plugin] will look for in a post's content
+ when generating [post excerpts]. All content after the separator is not
+ considered to be part of the excerpt.
+
+[`post_readtime`](#+blog.post_readtime){ #+blog.post_readtime }
+
+: :octicons-milestone-24: Default: `true` – This option specifies whether the
+ [built-in blog plugin] should compute the reading time of a post
+ automatically, which is then rendered in post excerpts, as well as in the
+ posts themselves. If you want to disable reading time computation, add:
+
+ ``` yaml
+ plugins:
+ - blog:
+ post_readtime: false
+ ```
+
+[`post_readtime_words_per_minute`](#+blog.post_readtime_words_per_minute){ #+blog.post_readtime_words_per_minute }
+
+: :octicons-milestone-24: Default: `265` – This option specifies the number
+ of words that a reader is expected to read per minute when computing the
+ reading time of a post. If you feel that estimation is not quite right,
+ you can fine-tune reading time computation with the following setting:
+
+ ``` yaml
+ plugins:
+ - blog:
+ post_readtime_words_per_minute: 265
+ ```
+
+ [built-in blog plugin]: #built-in-blog-plugin
+ [site language]: changing-the-language.md#site-language
+ [Babel]: https://pypi.org/project/Babel/
+ [pattern syntax]: https://babel.pocoo.org/en/latest/dates.html#pattern-syntax
+ [post_url_date_format]: #+blog.post_url_date_format
+ [post excerpts]: #adding-an-excerpt
+ [Python Markdown Extensions]: https://facelessuser.github.io/pymdown-extensions/extras/slugs/
+
+#### Archive
+
+The following configuration options are available for archive index generation:
+
+[`archive`](#+blog.archive){ #+blog.archive }
+
+: :octicons-milestone-24: Default: `true` – This option specifies whether the
+ [built-in blog plugin] should generate archive indexes. An archive indexes
+ shows all posts for a specific interval (e.g. year, month, etc.) in
+ reverse chronological order. If you want to disable archive index
+ generation, add:
+
+ ``` yaml
+ plugins:
+ - blog:
+ archive: false
+ ```
+
+[`archive_name`](#+blog.archive_name){ #+blog.archive_name }
+
+: :octicons-milestone-24: Default: _automatically set_ – This option specifies
+ the title of the archive section which the [built-in blog plugin] will
+ generate and add to the navigation. If this setting is omitted, it's
+ sourced from the translations, falling back to English. Change it with:
+
+ ``` yaml
+ plugins:
+ - blog:
+ archive_name: Archive
+ ```
+
+[`archive_date_format`](#+blog.archive_date_format){ #+blog.archive_date_format }
+
+: :octicons-milestone-24: Default: `YYYY` – This option specifies the date
+ format that is used when archive indexes are rendered. The format string
+ must adhere to [Babel]'s [pattern syntax]. Popular settings are:
+
+ === "2022"
+
+ ``` yaml
+ plugins:
+ - blog:
+ archive_date_format: YYYY
+ ```
+
+ === "January 2022"
+
+ ``` yaml
+ plugins:
+ - blog:
+ archive_date_format: MMMM YYYY
+ ```
+
+[`archive_url_date_format`](#+blog.archive_url_date_format){ #+blog.archive_url_date_format }
+
+: :octicons-milestone-24: Default: `YYYY` – This option specifies the date
+ format that is used in the archive index URL. The format string must adhere
+ to [Babel]'s [pattern syntax]. Some examples:
+
+ === ":material-link: blog/archive/2022/"
+
+ ``` yaml
+ plugins:
+ - blog:
+ archive_url_date_format: YYYY
+ ```
+
+ === ":material-link: blog/archive/2022/01/"
+
+ ``` yaml
+ plugins:
+ - blog:
+ archive_url_date_format: YYYY/MM
+ ```
+
+[`archive_url_format`](#+blog.archive_url_format){ #+blog.archive_url_format }
+
+: :octicons-milestone-24: Default: `archive/{date}` – This option specifies
+ the format string that is used for the URL of the archive index, and can
+ be used to localize the URL:
+
+ === ":material-link: blog/archive/2022/"
+
+ ``` yaml
+ plugins:
+ - blog:
+ archive_url_format: "archive/{date}"
+ ```
+
+ === ":material-link: blog/2022/"
+
+ ``` yaml
+ plugins:
+ - blog:
+ archive_url_format: "{date}"
+ ```
+
+#### Categories
+
+The following configuration options are available for category index generation:
+
+[`categories`](#+blog.categories){ #+blog.categories }
+
+: :octicons-milestone-24: Default: `true` – This option specifies whether the
+ [built-in blog plugin] should generate category indexes. A category indexes
+ shows all posts for a specific category in reverse chronological order. If
+ you want to disable category index generation, add:
+
+ ``` yaml
+ plugins:
+ - blog:
+ categories: false
+ ```
+
+[`categories_name`](#+blog.categories_name){ #+blog.categories_name }
+
+: :octicons-milestone-24: Default: _automatically set_ – This option specifies
+ the title of the category section which the [built-in blog plugin] will
+ generate and add to the navigation. If this setting is omitted, it's
+ sourced from the translations, falling back to English. Change it with:
+
+ ``` yaml
+ plugins:
+ - blog:
+ categories_name: Categories
+ ```
+
+[`categories_url_format`](#+blog.categories_url_format){ #+blog.categories_url_format }
+
+: :octicons-milestone-24: Default: `category/{slug}` – This option specifies
+ the format string that is used for the URL of the category index, and can
+ be used to localize the URL:
+
+ === ":material-link: blog/category/:material-dots-horizontal:/"
+
+ ``` yaml
+ plugins:
+ - blog:
+ categories_url_format: "category/{slug}"
+ ```
+
+ === ":material-link: blog/:material-dots-horizontal:/"
+
+ ``` yaml
+ plugins:
+ - blog:
+ categories_url_format: "{slug}"
+ ```
+
+[`categories_slugify`](#+blog.categories_slugify){ #+blog.categories_slugify }
+
+: :octicons-milestone-24: Default: `headerid.slugify` – This option specifies
+ which function to use for generating URL-compatible slugs from categories.
+ [Python Markdown Extensions] comes with several Unicode-aware
+ slug functions which should be a good choice for non-ASCII languages:
+
+ === "Unicode"
+
+ ``` yaml
+ plugins:
+ - blog:
+ categories_slugify: !!python/name:pymdownx.slugs.uslugify
+ ```
+
+ === "Unicode, case-sensitive"
+
+ ``` yaml
+ plugins:
+ - blog:
+ categories_slugify: !!python/name:pymdownx.slugs.uslugify_cased
+ ```
+
+[`categories_slugify_separator`](#+blog.categories_slugify_separator){ #+blog.categories_slugify_separator }
+
+: :octicons-milestone-24: Default: `-` – This option specifies the separator
+ which is used by the slug function. By default, a hyphen is used, but it can
+ be changed to any string, including the empty string:
+
+ ``` yaml
+ plugins:
+ - blog:
+ categories_slugify_separator: "-"
+ ```
+
+[`categories_allowed`](#+blog.categories_allowed){ #+blog.categories_allowed }
+
+: :octicons-milestone-24: Default: _none_ – This option specifies the
+ categories that are allowed to be used in posts. If this setting is omitted,
+ the [built-in blog plugin] will not check category names. Use this option to
+ define a list of categories in order to catch typos:
+
+ ``` yaml
+ plugins:
+ - blog:
+ categories_allowed:
+ - General
+ - Search
+ - Performance
+ ```
+
+#### Pagination
+
+The following configuration options are available for index pagination:
+
+[`pagination`](#+blog.pagination){ #+blog.pagination }
+
+: :octicons-milestone-24: Default: `true` – This option specifies whether the
+ [built-in blog plugin] should paginate the index. The index shows all posts
+ in reverse chronological order, which can be many. If you want to disable
+ index pagination, add:
+
+ ``` yaml
+ plugins:
+ - blog:
+ pagination: false
+ ```
+
+[`pagination_per_page`](#+blog.pagination_per_page){ #+blog.pagination_per_page }
+
+: :octicons-milestone-24: Default: `10` – This option specifies the number
+ of posts rendered on a single index page. If more posts are found, they are
+ assigned to a 2nd page, and so on. If you have large [post excerpts], it
+ might be a good idea to reduce the number of posts per page:
+
+ ``` yaml
+ plugins:
+ - blog:
+ pagination_per_page: 5
+ ```
+
+[`pagination_url_format`](#+blog.pagination_url_format){ #+blog.pagination_url_format }
+
+: :octicons-milestone-24: Default: `page/{page}` – This option specifies
+ the format string that is used for the URL of the paginated index, and can
+ be used to localize the URL:
+
+ === ":material-link: blog/page/n/"
+
+ ``` yaml
+ plugins:
+ - blog:
+ pagination_url_format: "page/{page}"
+ ```
+
+ === ":material-link: blog/n/"
+
+ ``` yaml
+ plugins:
+ - blog:
+ pagination_url_format: "{page}"
+ ```
+
+[`pagination_template`](#+blog.pagination_template){ #+blog.pagination_template }
+
+: :octicons-milestone-24: Default: `~2~` – This option specifies the format
+ string that is provided to the [paginate] module, which allows to customize
+ how pagination is constructed. Popular choices:
+
+ === "1 2 3 .. n"
+
+ ``` yaml
+ plugins:
+ - blog:
+ pagination_template: "~2~"
+ ```
+
+ === "1 2 3 .. n :material-chevron-right: :material-chevron-double-right:"
+
+ ``` yaml
+ plugins:
+ - blog:
+ pagination_template: "$link_first $link_previous ~2~ $link_next $link_last"
+ ```
+
+ === "1 :material-chevron-right:"
+
+ ``` yaml
+ plugins:
+ - blog:
+ pagination_template: "$link_previous $page $link_next"
+ ```
+
+ The [paginate] module exposes the following placeholders:
+
+ - `$first_page` – number of first reachable page
+ - `$last_page` – number of last reachable page
+ - `$page` – number of currently selected page
+ - `$page_count` – number of reachable pages
+ - `$items_per_page` – maximal number of items per page
+ - `$first_item` – index of first item on the current page
+ - `$last_item` – index of last item on the current page
+ - `$item_count` – total number of items
+ - `$link_first` – link to first page (unless this is first page)
+ - `$link_last` – link to last page (unless this is last page)
+ - `$link_previous` – link to previous page (unless this is first page)
+ - `$link_next` – link to next page (unless this is last page)
+
+ [paginate]: https://pypi.org/project/paginate/
+
+#### Authors
+
+The following configuration options are available for author info:
+
+[`authors`](#+blog.authors){ #+blog.authors }
+
+: :octicons-milestone-24: Default: `true` – This option specifies whether the
+ [built-in blog plugin] should generate author info. If it is enabled, the
+ plugin will look up authors in a file called `.authors.yml` and include
+ authors in indexes and in posts. If you want to disable this behavior, add:
+
+ ``` yaml
+ plugins:
+ - blog:
+ authors: false
+ ```
+
+[`authors_file`](#+blog.authors_file){ #+blog.authors_file }
+
+: :octicons-milestone-24: Default: `.authors.yml` – This option specifies the
+ name of the file where the authors for your posts resides. The default
+ settings assumes that the file is called `.authors.yml` (mind the `.` at
+ the beginning):
+
+ ``` yaml
+ plugins:
+ - blog:
+ authors_file: .authors.yml
+ ```
+
+ The path must be defined relative to [`blog_dir`][this is configurable].
+ Also see the section on [adding authors].
+
+[`authors_in_excerpt`](#+blog.authors_in_excerpt){ #+blog.authors_in_excerpt }
+
+: :octicons-milestone-24: Default: `1` – This option specifies the number of
+ authors rendered in post excerpts. While each post may be written by
+ multiple authors, this setting allows to limit the display to just a few or
+ even a single author, or disable authors in excerpts altogether:
+
+ === "Render up to 2 authors in excerpts"
+
+ ``` yaml
+ plugins:
+ - blog:
+ authors_in_excerpt: 2
+ ```
+
+ === "Disable authors in excerpts"
+
+ ``` yaml
+ plugins:
+ - blog:
+ authors_in_excerpt: 0
+ ```
+
+ [adding authors]: #adding-authors
+
+#### Drafts
+
+The following configuration options are available for drafts:
+
+[`draft`](#+blog.draft){ #+blog.draft }
+
+: :octicons-milestone-24: Default: `false` – This option specifies whether the
+ [built-in blog plugin] should also include posts marked as drafts when the
+ site is being built. Including draft posts might be desired in deploy
+ previews, which is why it exists in the first place:
+
+ === "Render drafts"
+
+ ``` yaml
+ plugins:
+ - blog:
+ draft: true
+ ```
+
+ === "Don't render drafts"
+
+ ``` yaml
+ plugins:
+ - blog:
+ draft: false
+ ```
+
+[`draft_on_serve`](#+blog.draft_on_serve){ #+blog.draft_on_serve }
+
+: :octicons-milestone-24: Default: `true` – This option specifies whether
+ posts marked as drafts should be included [when previewing your site] with
+ `mkdocs serve`. By default, drafts are rendered when previewing, but skipped
+ when the site is being built:
+
+ ``` yaml
+ plugins:
+ - blog:
+ draft_on_serve: true
+ ```
+
+[`draft_if_future_date`](#+blog.draft_if_future_date){ #+blog.draft_if_future_date }
+
+: :octicons-milestone-24: Default: `false` – This option specifies whether the
+ [built-in blog plugin] should mark posts with a future date as drafts. When
+ the date passed today, the post is automatically unmarked and included when
+ the site is being built:
+
+ ``` yaml
+ plugins:
+ - blog:
+ draft_if_future_date: true
+ ```
+
+ [when previewing your site]: ../creating-your-site.md#previewing-as-you-write
+
+### RSS
+
+[:octicons-heart-fill-24:{ .mdx-heart } Sponsors only][Insiders]{ .mdx-insiders } ·
+[:octicons-tag-24: insiders-4.23.0][Insiders] ·
+[:octicons-cpu-24: Plugin][rss]
+
+The [built-in blog plugin] integrates seamlessly with the [RSS plugin][rss],
+which provides a simple way to add an RSS feed to your blog (or to your whole
+documentation). Install it with `pip`:
+
+```
+pip install mkdocs-rss-plugin
+```
+
+Then, add the following lines to `mkdocs.yml`:
+
+``` yaml
+plugins:
+ - rss:
+ match_path: blog/posts/.* # (1)!
+ date_from_meta:
+ as_creation: date
+ categories:
+ - categories
+ - tags # (2)!
+```
+
+1. The RSS plugin allows to filter for URLs to be included in the feed. In
+ this example, only blog posts will be part of the feed.
+
+2. If you want to include a post's categories as well as its tags in the feed,
+ add both `categories` and `tags` here.
+
+The following configuration options are supported:
+
+[`enabled`](#+rss.enabled){ #+rss.enabled }
+
+: :octicons-milestone-24: Default: `true` – This option specifies whether
+ the plugin is enabled when building your project. If you want to switch
+ the plugin off, you can disable it with the following lines:
+
+ ``` yaml
+ plugins:
+ - rss:
+ enabled: false
+ ```
+
+[`match_path`](#+rss.match_path){ #+rss.match_path }
+
+: :octicons-milestone-24: Default: `.*` – This option specifies which
+ pages should be included in the feed. For example, to only include blog
+ posts in the feed, use the following regular expression:
+
+ ``` yaml
+ plugins:
+ - rss:
+ match_path: blog/posts/.*
+ ```
+
+[`date_from_meta`](#+rss.date_from_meta){ #+rss.date_from_meta }
+
+: :octicons-milestone-24: Default: _none_ – This option specifies which
+ front matter property should be used as a creation date of a page in the
+ feed. It's recommended to use the `date` property:
+
+ ``` yaml
+ plugins:
+ - rss:
+ date_from_meta:
+ as_creation: date
+ ```
+
+[`categories`](#+rss.categories){ #+rss.categories }
+
+: :octicons-milestone-24: Default: _none_ – This option specifies which
+ front matter properties are used as categories as part of the feed. If you
+ use [categories] and [tags], add both with the following lines:
+
+ ``` yaml
+ plugins:
+ - rss:
+ categories:
+ - categories
+ - tags
+ ```
+
+[`comments_path`](#+rss.comments_path){ #+rss.comments_path }
+
+: :octicons-milestone-24: Default: _none_ – This option specifies the anchor
+ at which comments for a post or page can be found. If you've integrated a
+ [comment system], add the following lines:
+
+ ``` yaml
+ plugins:
+ - rss:
+ comments_path: "#__comments"
+ ```
+
+Material for MkDocs will automatically add the [necessary metadata] to your site
+which will make the RSS feed discoverable by browsers and feed readers. Note
+that the [RSS plugin][rss] comes with several other configuration options.
+For further information, see the [documentation].
+
+ [rss]: https://guts.github.io/mkdocs-rss-plugin/
+ [categories]: #categories
+ [tags]: setting-up-tags.md#built-in-tags-plugin
+ [comment system]: adding-a-comment-system.md
+ [necessary metadata]: https://guts.github.io/mkdocs-rss-plugin/configuration/#integration
+ [theme extension]: ../customization.md
+ [documentation]: https://guts.github.io/mkdocs-rss-plugin/configuration/
+
+## Usage
+
+### Writing your first post
+
+After you've successfully set up the [built-in blog plugin], it's time to write
+your first post. The plugin doesn't assume any specific directory structure, so
+you're completely free in how you organize your posts, as long as they are all
+located inside the `posts` directory:
+
+``` sh
+.
+├─ docs/
+│ └─ blog/
+│ ├─ 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.
+
+Create a new file called `hello-world.md` and add the following lines:
+
+``` yaml
+---
+draft: true # (1)!
+date: 2022-01-31
+categories:
+ - Hello
+ - World
+---
+
+# Hello world!
+...
+```
+
+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.
+
+ [draft]: #drafts
+ [This behavior can be changed]: #+blog.draft
+ [live preview server]: ../creating-your-site.md#previewing-as-you-write
+
+#### Adding an excerpt
+
+The blog index, as well as [archive] and [category] indexes can either list the
+entire content of each post, or excerpts of posts. An excerpt can be created by
+adding a `` separator after the first few paragraphs of a post:
+
+``` py
+# Hello world!
+
+Lorem ipsum dolor sit amet, consectetur adipiscing elit. Nulla et euismod
+nulla. Curabitur feugiat, tortor non consequat finibus, justo purus auctor
+massa, nec semper lorem quam in massa.
+
+
+...
+```
+
+When the [built-in blog plugin] generates all indexes, the content before the
+[excerpt separator] is automatically extracted, allowing the user to start
+reading a post before deciding to jump in.
+
+ [excerpt separator]: #+blog.post_excerpt_separator
+
+#### Adding authors
+
+In order to add a little more personality to your posts, you can associate each
+post with one or multiple [authors]. First, create the
+[`.authors.yml`][authors_file] file in your blog directory, and add an author:
+
+``` yaml
+squidfunk:
+ name: Martin Donath
+ description: Creator
+ avatar: https://github.com/squidfunk.png
+```
+
+The [`.authors.yml`][authors_file] file associates each author with an
+identifier (in this example `squidfunk`), which can then be used in posts.
+The following properties are available for each author:
+
+[`name`](#+blog.authors_file.name){ #+blog.authors_file.name }
+
+: :octicons-milestone-24: Default: _none_ · :octicons-alert-24: __Required__ –
+ This property must define a name for the author. The name is displayed in
+ the left sidebar of each post as part of the author info.
+
+[`description`](#+blog.authors_file.description){ #+blog.authors_file.description }
+
+: :octicons-milestone-24: Default: _none_ · :octicons-alert-24: __Required__ –
+ This property can be used to add a short description for the author, e.g.
+ the role or profession of the author, or any other title.
+
+[`avatar`](#+blog.authors_file.avatar){ #+blog.authors_file.avatar }
+
+: :octicons-milestone-24: Default: _none_ · :octicons-alert-24: __Required__ –
+ This property must point to a valid image URL, internal or external, and is
+ used as part of posts and excerpts as the author's avatar.
+
+Now, you can assign one or more authors to a post by referencing their
+identifiers in the front matter of the Markdown file under the `authors`
+property. For each author, a small profile is rendered in the left sidebar of
+each post, as well as in post excerpts on index pages:
+
+``` yaml
+---
+date: 2022-01-31
+authors:
+ - squidfunk
+ ...
+---
+
+# Hello world!
+...
+```
+
+ [authors]: #authors
+ [authors_file]: #+blog.authors_file
+
+#### Adding categories
+
+Categories are an excellent way for grouping your posts thematically on
+dedicated index pages. This way, a user interested in a specific topic can
+explore all of your posts on this topic. Make sure [categories] are enabled and
+add them to the `categories` front matter property:
+
+``` yaml
+---
+date: 2022-01-31
+categories:
+ - Hello
+ - World
+---
+
+# Hello world!
+...
+```
+
+If you want to save yourself from typos when typing out categories, you can
+define your desired categories in `mkdocs.yml` as part of the
+[`categories_allowed`][categories_allowed] configuration option. The
+[built-in blog plugin] will stop the build if a category is not found within
+the list.
+
+ [categories_allowed]: #+blog.categories_allowed
+
+#### Adding tags
+
+Besides [categories], the [built-in blog plugin] also integrates with the
+[built-in tags plugin]. If you add tags in the `tags` front matter property as
+part of a post, the post is linked from the [tags index]:
+
+``` yaml
+---
+date: 2022-01-31
+tags:
+ - Foo
+ - Bar
+---
+
+# Hello world!
+...
+```
+
+As usual, the tags are rendered above the main headline and posts are linked
+on the tags index page, if configured. Note that posts are, as pages, only
+linked with their titles.
+
+ [built-in tags plugin]: setting-up-tags.md#built-in-tags-plugin
+ [tags index]: setting-up-tags.md#adding-a-tags-index
+
+#### Adding related links
+
+Related links offer the perfect way to prominently add a _further reading_
+section to your post that is included in the left sidebar, guiding the user to
+other destinations of your documentation. Use the `links` front matter property
+to add related links to a post:
+
+``` yaml
+---
+date: 2022-01-31
+links:
+ - setup/setting-up-site-search.md#built-in-search-plugin
+ - insiders/index.md#how-to-become-a-sponsor
+---
+
+# Hello world!
+...
+```
+
+You can use the exact same syntax as for the [`nav`][nav] section in
+`mkdocs.yml`, which means you can set explicit titles for links, add external
+links and even use nesting:
+
+``` yaml
+---
+date: 2022-01-31
+links:
+ - setup/setting-up-site-search.md#built-in-search-plugin
+ - insiders/index.md#how-to-become-a-sponsor
+ - Nested section:
+ - External link: https://example.com
+ - setup/setting-up-site-search.md
+---
+
+# Hello world!
+...
+```
+
+If you look closely, you'll realize that you can even use an anchor to link to
+a specific section of a document, extending the possiblities of the [`nav`][nav]
+syntax in `mkdocs.yml`. The [built-in blog plugin] resolves the anchor and sets
+the title of the anchor as a subtitle of the related link.
+
+Note that all links must be relative to [`docs_dir`][docs_dir], as is also the case for the [`nav`][nav] setting.
+
+ [nav]: https://www.mkdocs.org/user-guide/configuration/#nav
+
+#### Linking from and to posts
+
+While [post URLs][post slugs] are dynamically computed, the [built-in blog
+plugin] ensures that all links from and to posts and a post's assets are
+correct. If you want to link to a post, just use the path to the Markdown file
+as a link reference (links must be relative):
+
+``` markdown
+[Hello World!](blog/posts/hello-world.md)
+```
+
+Linking from a post to a page, e.g. the index, follows the same method:
+
+``` markdown
+[Blog](../index.md)
+```
+
+All assets inside the `posts` directory are copied to the `blog/assets` folder
+when the site is being built. Of course, you can also reference assets from
+posts outside of the `posts` directory. The [built-in blog plugin] ensures that
+all links are correct.
+
+#### Setting the reading time
+
+When [enabled], the [readtime] package is used to compute the expected reading
+time of each post, which is rendered as part of the post and post excerpt.
+Nowadays, many blogs show reading times, which is why the [built-in blog plugin]
+offers this capability as well.
+
+Sometimes, however, the computed reading time might not feel accurate, or
+result in odd and unpleasant numbers. For this reason, reading time can be
+overridden and explicitly set with the `readtime` front matter property for a
+post:
+
+``` yaml
+---
+date: 2022-01-31
+readtime: 15
+---
+
+# Hello world!
+...
+```
+
+This will disable automatic reading time computation.
+
+ [readtime]: https://pypi.org/project/readtime/
+ [enabled]: #+blog.post_readtime
+
+#### Setting defaults
+
+If you have a lot of posts, it might feel redundant to define all of the above
+for each post. Luckily, the [built-in meta plugin] allows to set default front
+matter properties per folder. You can group your posts by categories, or
+authors, and add a `.meta.yml` file to set common properties:
+
+``` sh
+.
+├─ docs/
+│ └─ blog/
+│ ├─ posts/
+│ ├─ .meta.yml # (1)!
+│ └─ index.md
+└─ mkdocs.yml
+```
+
+1. As already noted, you can also place a `.meta.yml` file in nested folders
+ of the `posts` directory. This file then can contain any front matter that
+ is also valid in posts, e.g.:
+
+ ``` yaml
+ authors:
+ - squidfunk
+ categories:
+ - Hello
+ - World
+ ```
+
+Note that order matters – the [built-in meta plugin] must be defined before the
+blog plugin in `mkdocs.yml`, so that all set defaults are correctly picked up
+by the [built-in blog plugin]:
+
+``` yaml
+plugins:
+ - meta
+ - blog
+```
+
+Lists and dictionaries in `.meta.yml` files are merged and deduplicated with the
+values defined for a post, which means you can define common properties in
+`.meta.yml` and then add specific properties or overrides for each post.
+
+ [built-in meta plugin]: ../reference/index.md#built-in-meta-plugin
+
+### Adding pages
+
+Besides posts, it's also possible to add static pages to your blog by listing
+the pages in the [`nav`][nav] section of `mkdocs.yml`. All generated indexes
+are included after the last specified page. For example, to add a page on the
+authors of the blog, add the following to `mkdocs.yml`:
+
+``` yaml
+nav:
+ - Blog:
+ - blog/index.md
+ - blog/authors.md
+ ...
+```
+
+## Customization
+
+### Overriding templates
+
+The [built-in blog plugin] is built on the same basis as Material for MkDocs,
+which means you can override all templates used for the blog by using
+[theme extension] as usual.
+
+The following templates are added by the [built-in blog plugin]:
+
+- [`blog.html`][blog.html] – Template for blog index
+- [`blog-post.html`][blog-post.html] – Template for blog post
+- [`blog-archive.html`][blog-archive.html] – Template for blog archive index
+- [`blog-category.html`][blog-category.html] – Template for blog category index
+
+ [theme extension]: ../customization.md#extending-the-theme
+
+ [blog.html]: https://github.com/squidfunk/mkdocs-material-insiders/blob/master/src/blog.html
+ [blog-post.html]: https://github.com/squidfunk/mkdocs-material-insiders/blob/master/src/blog-post.html
+ [blog-archive.html]: https://github.com/squidfunk/mkdocs-material-insiders/blob/master/src/blog-archive.html
+ [blog-category.html]: https://github.com/squidfunk/mkdocs-material-insiders/blob/master/src/blog-category.html
diff --git a/docs/setup/setting-up-navigation.md b/docs/setup/setting-up-navigation.md
index d7e896c89..d1863861e 100644
--- a/docs/setup/setting-up-navigation.md
+++ b/docs/setup/setting-up-navigation.md
@@ -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
@@ -205,11 +203,12 @@ This feature flag is especially useful for documentation sites with 100+ or even
Navigation pruning will replace all expandable sections with links to the first
page in that section (or the section index page).
+ [Insiders]: ../insiders/index.md
[navigation.expand]: #navigation-expansion
### 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 +224,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,17 +245,16 @@ 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
#### Anchor following
-[:octicons-heart-fill-24:{ .mdx-heart } Sponsors only][Insiders]{ .mdx-insiders } ·
-[:octicons-tag-24: insiders-4.8.0][Insiders] ·
+[:octicons-tag-24: 8.5.0][Anchor following support] ·
:octicons-beaker-24: Experimental
When anchor following for the [table of contents] is enabled, the sidebar is
@@ -269,11 +267,11 @@ theme:
- toc.follow
```
- [Insiders]: ../insiders/index.md
+ [Anchor following support]: https://github.com/squidfunk/mkdocs-material/releases/tag/8.5.0
#### 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
+ [Hide navigation 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:
diff --git a/docs/setup/setting-up-site-analytics.md b/docs/setup/setting-up-site-analytics.md
index 5f0511796..6bfb4edd9 100644
--- a/docs/setup/setting-up-site-analytics.md
+++ b/docs/setup/setting-up-site-analytics.md
@@ -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