Material for MkDocs

https://github.com/squidfunk/mkdocs-material
Admin
A powerful documentation framework on top of MkDocs that allows you to create professional,...
Tokens:223,684
Snippets:2,154
Trust Score:9
License:MIT
Update:16 hours ago
Show doc for...
Tokens:
Raw
### Install additional MkDocs plugins with pip

Source: https://github.com/squidfunk/mkdocs-material/blob/master/docs/publishing-your-site.md

Use this command in the workflow to install further MkDocs plugins or Markdown extensions. The example shows installing mkdocs-material and mkdocs-awesome-pages-plugin, with ... as a placeholder for additional packages.

```sh
pip install \
  mkdocs-material \
  mkdocs-awesome-pages-plugin \
  ...
```

--------------------------------

### Example: Configure tag icons and identifiers

Source: https://github.com/squidfunk/mkdocs-material/blob/master/docs/setup/setting-up-tags.md

Complete example showing how to assign icons to tags and map tags to identifiers. This example uses HTML5, JavaScript, and CSS tags.

```yaml
theme:
  icon:
    tag:
      html: fontawesome/brands/html5
      js: fontawesome/brands/js
      css:  fontawesome/brands/css3
extra:
  tags:
    HTML5: html
    JavaScript: js
    CSS: css
```

--------------------------------

### Install from lockfile

Source: https://github.com/squidfunk/mkdocs-material/blob/master/docs/getting-started.md

Installs dependencies from the requirements.txt lockfile.

```sh
pip install -r requirements.txt
```

--------------------------------

### Install theme from cloned repository

Source: https://github.com/squidfunk/mkdocs-material/blob/master/docs/getting-started.md

Installs the theme and its dependencies from the cloned repository.

```sh
pip install -e mkdocs-material
```

--------------------------------

### Install Material for MkDocs with pip

Source: https://github.com/squidfunk/mkdocs-material/blob/master/README.md

Install the package using pip. Requires Python 3.11 or newer.

```sh
pip install mkdocs-material
```

--------------------------------

### Start the MkDocs live preview server

Source: https://github.com/squidfunk/mkdocs-material/blob/master/docs/customization.md

Start the MkDocs live preview server with the --watch-theme flag. Run this in a second terminal window.

```bash
mkdocs serve --watch-theme
```

--------------------------------

### Start the watcher

Source: https://github.com/squidfunk/mkdocs-material/blob/master/docs/customization.md

Start the watcher for development mode.

```bash
npm start
```

--------------------------------

### Example: Map Compatibility tag to compat identifier

Source: https://github.com/squidfunk/mkdocs-material/blob/master/docs/setup/setting-up-tags.md

Example showing how to set an identifier for a tag. Here, the tag 'Compatibility' is mapped to the identifier 'compat'.

```yaml
extra:
  tags:
    Compatibility: compat
```

--------------------------------

### Install Node.js LTS and npm dependencies

Source: https://github.com/squidfunk/mkdocs-material/blob/master/docs/customization.md

Install the Node.js LTS version into the virtual environment and install all Node.js dependencies.

```bash
nodeenv -p -n lts
npm install
```

--------------------------------

### Complete GitHub Actions workflow with git sparse-checkout

Source: https://github.com/squidfunk/mkdocs-material/blob/master/docs/blog/posts/git-sparse-checkout.md

A complete example workflow for GitHub Actions that uses git sparse-checkout to speed up documentation builds. It checks out only the docs and includes directories, sets up Python, installs mkdocs-material, and deploys with mkdocs gh-deploy.

```yaml
name: documentation
on:
  push:
    branches:
      - master
      - main
permissions:
  contents: write
jobs:
  deploy:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
        with:
          fetch-depth: 0
          sparse-checkout: |
            docs
            includes
      - uses: actions/setup-python@v4
        with:
          python-version: 3.x
      - run: pip install mkdocs-material
      - run: mkdocs gh-deploy --force
```

--------------------------------

### Start live preview server with mkdocs serve --livereload

Source: https://github.com/squidfunk/mkdocs-material/blob/master/docs/creating-your-site.md

Starts the MkDocs live preview server, which rebuilds the site automatically on save. For large projects, rebuilds may take minutes; use the --dirtyreload flag for faster rebuilds of the current page.

```sh
mkdocs serve --livereload # (1)!
```

--------------------------------

### Install pngquant on Ubuntu with apt-get

Source: https://github.com/squidfunk/mkdocs-material/blob/master/docs/plugins/requirements/image-processing.md

Install pngquant on Ubuntu using apt-get.

```bash
apt-get install pngquant
```

--------------------------------

### Enable instant prefetching in mkdocs.yml

Source: https://github.com/squidfunk/mkdocs-material/blob/master/docs/setup/setting-up-navigation.md

Adds navigation.instant.prefetch to start fetching a page on hover, reducing perceived loading time. Experimental feature.

```yaml
theme:
  features:
    - navigation.instant
    - navigation.instant.prefetch
```

--------------------------------

### Configure blog_dir for blog-only setup

Source: https://github.com/squidfunk/mkdocs-material/blob/master/docs/setup/setting-up-a-blog.md

Sets blog_dir to '.' so blog posts are served from the root URL instead of /blog/.

```yaml
plugins:
  - blog:
      blog_dir: . # (1)!
```

--------------------------------

### Install with pip (9.x)

Source: https://github.com/squidfunk/mkdocs-material/blob/master/docs/getting-started.md

Installs the 9.x version of Material for MkDocs using pip. Limits upgrades to the current major version to avoid breaking changes.

```sh
pip install mkdocs-material=="9.*" # (1)!
```

--------------------------------

### Show installed version with pip

Source: https://github.com/squidfunk/mkdocs-material/blob/master/docs/upgrade.md

Display the currently installed version of mkdocs-material.

```bash
pip show mkdocs-material
```

--------------------------------

### Install Python and Node.js dependencies

Source: https://github.com/squidfunk/mkdocs-material/blob/master/docs/customization.md

Install all Python dependencies and nodeenv. This is required for the build process.

```bash
pip install -e ".[git, recommended, imaging]"
pip install nodeenv
```

--------------------------------

### Install mkdocs-glightbox with pip

Source: https://github.com/squidfunk/mkdocs-material/blob/master/docs/reference/images.md

Install the glightbox plugin via `pip` to add image zoom functionality.

```bash
pip install mkdocs-glightbox
```

--------------------------------

### Install git-revision-date-localized plugin

Source: https://github.com/squidfunk/mkdocs-material/blob/master/docs/setup/adding-a-git-repository.md

Installs the plugin via pip.

```bash
pip install mkdocs-git-revision-date-localized-plugin
```

--------------------------------

### Install pngquant on Windows with MSYS2

Source: https://github.com/squidfunk/mkdocs-material/blob/master/docs/plugins/requirements/image-processing.md

Install pngquant on Windows using MSYS2 in the UCRT64 environment.

```bash
pacman -S mingw-w64-ucrt-x86_64-pngquant
```

--------------------------------

### Install Cairo Graphics on openSUSE with zypper

Source: https://github.com/squidfunk/mkdocs-material/blob/master/docs/plugins/requirements/image-processing.md

Install Cairo Graphics and its dependencies on openSUSE using zypper.

```bash
zypper install cairo-devel freetype-devel libffi-devel libjpeg-devel libpng-devel zlib-devel
```

--------------------------------

### Custom index pages: front matter example

Source: https://github.com/squidfunk/mkdocs-material/blob/master/docs/setup/setting-up-a-blog.md

Example front matter for a custom category page, setting the page description. Post excerpts are automatically appended below the content.

```yaml
---
description: Nullam urna elit, malesuada eget finibus ut, ac tortor.
---

# Hello
...
```

--------------------------------

### Example configuration transformation function

Source: https://github.com/squidfunk/mkdocs-material/blob/master/docs/plugins/projects.md

Example transform function that inherits the use_directory_urls setting from the top-level configuration for all projects.

```py
from mkdocs.config.defaults import MkDocsConfig

# Transform project configuration
def transform(project: MkDocsConfig, config: MkDocsConfig):
    project.use_directory_urls = config.use_directory_urls
```

--------------------------------

### Install the RSS plugin with pip

Source: https://github.com/squidfunk/mkdocs-material/blob/master/docs/setup/setting-up-a-blog.md

Installs the mkdocs-rss-plugin package, required for RSS feed integration.

```bash
pip install mkdocs-rss-plugin
```

--------------------------------

### Generated search_index.json for example page

Source: https://github.com/squidfunk/mkdocs-material/blob/master/docs/blog/posts/search-better-faster-smaller.md

Shows the JSON structure of the search index generated from the example Markdown file. Includes configuration and document entries with location, title, and text.

```json
{
  "config": {
    "indexing": "full",
    "lang": [
      "en"
    ],
    "min_search_length": 3,
    "prebuild_index": false,
    "separator": "[\\s\\-]+"
  },
  "docs": [
    {
      "location": "page/",
      "title": "Example",
      "text": "Example Text It's very easy to make some words bold and other words italic with Markdown. You can even add links , or even code : if (isAwesome) { return true } Lists Sometimes you want numbered lists: One Two Three Sometimes you want bullet points: Start a line with a star Profit!"
    },
    {
      "location": "page/#example",
      "title": "Example",
      "text": ""
    },
    {
      "location": "page/#text",
      "title": "Text",
      "text": "It's very easy to make some words bold and other words italic with Markdown. You can even add links , or even code : if (isAwesome) { return true }"
    },
    {
      "location": "page/#lists",
      "title": "Lists",
      "text": "Sometimes you want numbered lists: One Two Three Sometimes you want bullet points: Start a line with a star Profit!"
    }
  ]
}
```

--------------------------------

### Blog-only folder structure

Source: https://github.com/squidfunk/mkdocs-material/blob/master/docs/setup/setting-up-a-blog.md

Shows the folder tree for a pure blog setup without documentation pages. The posts directory is directly under docs.

```sh
.
├─ docs/
│  ├─ posts/ # (1)!
│  ├─ .authors.yml
│  └─ index.md
└─ mkdocs.yml
```

--------------------------------

### Install git-authors plugin with pip

Source: https://github.com/squidfunk/mkdocs-material/blob/master/docs/setup/adding-a-git-repository.md

Install the git-authors plugin using pip.

```bash
pip install mkdocs-git-authors-plugin
```

--------------------------------

### Highlight.js integration - JavaScript file

Source: https://github.com/squidfunk/mkdocs-material/blob/master/docs/setup/extensions/python-markdown-extensions.md

JavaScript code to trigger Highlight.js highlighting on document subscription. Part of the JavaScript syntax highlighter setup.

```js
document$.subscribe(() => {
  hljs.highlightAll()
})
```

--------------------------------

### Enable SmartSymbols in mkdocs.yml

Source: https://github.com/squidfunk/mkdocs-material/blob/master/docs/setup/extensions/python-markdown-extensions.md

Converts character sequences into corresponding symbols like copyright or fractions.

```yaml
markdown_extensions:
  - pymdownx.smartsymbols
```

--------------------------------

### Enable blog plugin in mkdocs.yml

Source: https://github.com/squidfunk/mkdocs-material/blob/master/docs/plugins/blog.md

Adds the built-in blog plugin to your MkDocs configuration. No installation required.

```yaml
plugins:
  - blog
```

--------------------------------

### Upgrade mkdocs-material with pip

Source: https://github.com/squidfunk/mkdocs-material/blob/master/docs/blog/posts/insiders-now-free-for-everyone.md

Run this command to upgrade to the latest community edition of Material for MkDocs. Use --force-reinstall to ensure a clean installation.

```bash
pip install --upgrade --force-reinstall mkdocs-material
```

--------------------------------

### Output of mkdocs build with info plugin

Source: https://github.com/squidfunk/mkdocs-material/blob/master/docs/guides/creating-a-reproduction.md

Example terminal output when running `mkdocs build` with the info plugin enabled, showing the created archive and its contents.

```text
INFO     -  Started archive creation for bug report
INFO     -  Archive successfully created:

  example/.dependencies.json 859.0 B
  example/.versions.log 83.0 B
  example/docs/index.md 282.0 B
  example/mkdocs.yml 56.0 B

  example.zip 1.8 kB
```

--------------------------------

### Enable Keys in mkdocs.yml

Source: https://github.com/squidfunk/mkdocs-material/blob/master/docs/setup/extensions/python-markdown-extensions.md

Adds rendering of keyboard keys and combinations. The class option must not be changed.

```yaml
markdown_extensions:
  - pymdownx.keys
```

--------------------------------

### Full configuration example for material.extensions.preview

Source: https://github.com/squidfunk/mkdocs-material/blob/master/docs/setup/setting-up-navigation.md

Complete configuration with `sources` and `targets` settings. `sources` controls pages where previews are enabled (default all pages), `targets` controls pages to which previews point. Exclusion overrides inclusion.

```yaml
markdown_extensions:
  - material.extensions.preview:
      configurations:
        - sources: # (1)!
            include:
              - ...
            exclude:
              - ...
          targets: # (2)!
            include:
              - ...
            exclude:
              - ...
```

--------------------------------

### Create and activate a Python virtual environment

Source: https://github.com/squidfunk/mkdocs-material/blob/master/docs/customization.md

Create a new Python virtual environment and activate it. This is required before installing dependencies.

```bash
python -m venv venv
source venv/bin/activate
```

--------------------------------

### Example headline for overflow demonstration

Source: https://github.com/squidfunk/mkdocs-material/blob/master/docs/setup/setting-up-social-cards.md

A sample headline used to illustrate text overflow behavior in the typography layer.

```markdown
# If we use a very long headline, we can see how the text will be truncated
```

--------------------------------

### Highlight with Pygments (use_pygments: true)

Source: https://github.com/squidfunk/mkdocs-material/blob/master/docs/setup/extensions/python-markdown-extensions.md

Uses Pygments for build-time syntax highlighting. This is the default behavior.

```yaml
markdown_extensions:
  - pymdownx.highlight:
      use_pygments: true
  - pymdownx.superfences
```

--------------------------------

### Example site structure for projects plugin

Source: https://github.com/squidfunk/mkdocs-material/blob/master/docs/setup/building-an-optimized-site.md

This directory structure shows a possible layout for a multi-project site with subsites. It is used in the documentation to illustrate how the projects plugin works.

```text
.
└── /
    ├── subsite-a/
    ├── subsite-b/
    └── subsite-c/
```

--------------------------------

### Enable instant previews per-page with material.extensions.preview

Source: https://github.com/squidfunk/mkdocs-material/blob/master/docs/setup/setting-up-navigation.md

Recommended way to enable instant previews on a per-page or per-section level. Configure `targets.include` with page paths or glob patterns.

```yaml
markdown_extensions:
  - material.extensions.preview:
      configurations:
        - targets:
            include:
              - changelog/index.md
              - customization.md
              - insiders/changelog/*
              - setup/extensions/*
```

--------------------------------

### Enable privacy plugin in mkdocs.yml

Source: https://github.com/squidfunk/mkdocs-material/blob/master/docs/plugins/privacy.md

Add the privacy plugin to your MkDocs configuration to start self-hosting external assets. The plugin is built into Material for MkDocs and requires no installation.

```yaml
plugins:
  - privacy
```

--------------------------------

### Example of defining a custom page status

Source: https://github.com/squidfunk/mkdocs-material/blob/master/docs/reference/index.md

Example showing how to define a status with identifier `new` and description `Recently added` in `mkdocs.yml`.

```yaml
extra:
  status:
    new: Recently added
```

--------------------------------

### Install pngquant on macOS with Homebrew

Source: https://github.com/squidfunk/mkdocs-material/blob/master/docs/plugins/requirements/image-processing.md

Install pngquant on macOS using Homebrew.

```bash
brew install pngquant
```

--------------------------------

### Publish a new version with mike deploy

Source: https://github.com/squidfunk/mkdocs-material/blob/master/docs/setup/setting-up-versioning.md

Deploys a new version of your documentation and updates the 'latest' alias to point to it. The version is published as a subdirectory of your site_url, e.g., docs.example.com/0.1/.

```bash
mike deploy --push --update-aliases 0.1 latest
```

--------------------------------

### Set default version with mike set-default

Source: https://github.com/squidfunk/mkdocs-material/blob/master/docs/setup/setting-up-versioning.md

Sets the default version alias (e.g., 'latest') to point to the latest version. Use this when starting with mike to establish a default version.

```bash
mike set-default --push latest
```

--------------------------------

### Create posts folder and hello-world.md file

Source: https://github.com/squidfunk/mkdocs-material/blob/master/docs/blog/posts/blog-support-just-landed.md

Shows the required directory structure for a blog post. Create a `posts` folder with a `hello-world.md` file inside the `docs` directory. The URLs are built from the `post_url_format` configuration and the titles and dates of posts, regardless of how they are organized.

```sh
.
├─ docs/
│  ├─ posts/
│  │  └─ hello-world.md # (1)!
│  └─ index.md
└─ mkdocs.yml
```

--------------------------------

### Enable Snippets in mkdocs.yml

Source: https://github.com/squidfunk/mkdocs-material/blob/master/docs/setup/extensions/python-markdown-extensions.md

Embeds content from arbitrary files into documents using a simple syntax.

```yaml
markdown_extensions:
  - pymdownx.snippets
```

--------------------------------

### Configure Material theme in mkdocs.yml

Source: https://github.com/squidfunk/mkdocs-material/blob/master/README.md

Add the theme configuration to your mkdocs.yml file to enable Material for MkDocs.

```yaml
theme:
  name: material
```

--------------------------------

### Bootstrap a new project with mkdocs new

Source: https://github.com/squidfunk/mkdocs-material/blob/master/docs/blog/posts/blog-support-just-landed.md

Run this command to create a new MkDocs project in the current directory. It generates the initial structure with a docs folder and mkdocs.yml.

```bash
mkdocs new .
```

--------------------------------

### Critic Markup example

Source: https://github.com/squidfunk/mkdocs-material/blob/master/docs/reference/formatting.md

Shows how to use Critic Markup to highlight suggested changes and add inline comments. The second block demonstrates block-level formatting.

```markdown
Text can be {--deleted--} and replacement text {++added++}. This can also be
combined into {~~one~>a single~~} operation. {==Highlighting==} is also
possible {>>and comments can be added inline<<}.

{==

Formatting can also be applied to blocks by putting the opening and closing
tags on separate lines and adding new lines between the tags and the content.

==}
```

--------------------------------

### Highlight.js integration - mkdocs.yml configuration

Source: https://github.com/squidfunk/mkdocs-material/blob/master/docs/setup/extensions/python-markdown-extensions.md

Adds Highlight.js JavaScript and CSS files via extra_javascript and extra_css in mkdocs.yml.

```yaml
extra_javascript:
  - https://cdnjs.cloudflare.com/ajax/libs/highlight.js/10.7.2/highlight.min.js
  - javascripts/highlight.js
extra_css:
  - https://cdnjs.cloudflare.com/ajax/libs/highlight.js/10.7.2/styles/default.min.css
```

--------------------------------

### Critic mode: accept

Source: https://github.com/squidfunk/mkdocs-material/blob/master/docs/setup/extensions/python-markdown-extensions.md

Sets the pymdownx.critic mode to 'accept' to automatically accept all suggested changes.

```yaml
markdown_extensions:
  - pymdownx.critic:
      mode: accept
```

--------------------------------

### Install Cairo Graphics on Fedora with yum

Source: https://github.com/squidfunk/mkdocs-material/blob/master/docs/plugins/requirements/image-processing.md

Install Cairo Graphics and its dependencies on Fedora using yum.

```bash
yum install cairo-devel freetype-devel libffi-devel libjpeg-devel libpng-devel zlib-devel
```

--------------------------------

### Enable instant previews globally with navigation.instant.preview

Source: https://github.com/squidfunk/mkdocs-material/blob/master/docs/setup/setting-up-navigation.md

Add `navigation.instant.preview` to `theme.features` in `mkdocs.yml` to enable instant previews for all header links without data attributes.

```yaml
theme:
  features:
    - navigation.instant.preview
```

--------------------------------

### Install Cairo Graphics on Ubuntu with apt-get

Source: https://github.com/squidfunk/mkdocs-material/blob/master/docs/plugins/requirements/image-processing.md

Install Cairo Graphics and its dependencies on Ubuntu using apt-get.

```bash
apt-get install libcairo2-dev libfreetype6-dev libffi-dev libjpeg-dev libpng-dev libz-dev
```

--------------------------------

### Enable Details extension

Source: https://github.com/squidfunk/mkdocs-material/blob/master/docs/setup/extensions/python-markdown-extensions.md

Adds the pymdownx.details extension to make Admonition call-outs collapsible. Configure via mkdocs.yml.

```yaml
markdown_extensions:
  - pymdownx.details
```

--------------------------------

### Set up upstream remote and view remotes

Source: https://github.com/squidfunk/mkdocs-material/blob/master/docs/contributing/making-a-pull-request.md

Shows how to add the original repository as an upstream remote and verify the configured remotes. The highlighted line is the command to add the upstream remote.

```bash
$ git remote -v
origin	git@github.com:<your_username>/mkdocs-material-fork.git (fetch)
origin	git@github.com:<your_username>/mkdocs-material-fork.git (push)
$ git remote add upstream https://github.com/squidfunk/mkdocs-material.git
$ git remote -v
origin	git@github.com:alexvoss/mkdocs-material-fork.git (fetch)
origin	git@github.com:alexvoss/mkdocs-material-fork.git (push)
upstream	https://github.com/squidfunk/mkdocs-material.git (fetch)
upstream	https://github.com/squidfunk/mkdocs-material.git (push)
```

--------------------------------

### Install Cairo Graphics on macOS with Homebrew

Source: https://github.com/squidfunk/mkdocs-material/blob/master/docs/plugins/requirements/image-processing.md

Install Cairo Graphics and its dependencies on macOS using Homebrew.

```bash
brew install cairo freetype libffi libjpeg libpng zlib
```

--------------------------------

### Install Cairo Graphics on Windows with MSYS2

Source: https://github.com/squidfunk/mkdocs-material/blob/master/docs/plugins/requirements/image-processing.md

Install Cairo Graphics on Windows using MSYS2 in the UCRT64 environment.

```bash
pacman -S mingw-w64-ucrt-x86_64-cairo
```

--------------------------------

### Install imaging extra with pip

Source: https://github.com/squidfunk/mkdocs-material/blob/master/docs/plugins/requirements/image-processing.md

Install the optional imaging dependencies for the social and optimize plugins using pip.

```bash
pip install "mkdocs-material[imaging]"
```

--------------------------------

### Configure meta and blog plugins in mkdocs.yml

Source: https://github.com/squidfunk/mkdocs-material/blob/master/docs/setup/setting-up-a-blog.md

Define the `meta` plugin before the `blog` plugin in `mkdocs.yml` so that defaults from `.meta.yml` files are correctly picked up by the blog plugin.

```yaml
plugins:
  - meta
  - blog
```

--------------------------------

### Social link with Mastodon icon

Source: https://github.com/squidfunk/mkdocs-material/blob/master/docs/setup/setting-up-the-footer.md

Example of a social link using the Mastodon icon. The link property is required and must include the URI scheme.

```yaml
extra:
  social:
    - icon: fontawesome/brands/mastodon
      link: https://fosstodon.org/@squidfunk
```

--------------------------------

### Build with Docker on Windows

Source: https://github.com/squidfunk/mkdocs-material/blob/master/docs/creating-your-site.md

Runs the build inside a Docker container for Windows environments. Mounts the current directory to /docs in the container.

```bash
docker run --rm -it -v "%cd%":/docs squidfunk/mkdocs-material build
```

--------------------------------

### Enable optimize plugin in mkdocs.yml

Source: https://github.com/squidfunk/mkdocs-material/blob/master/docs/plugins/optimize.md

Adds the built-in optimize plugin to your MkDocs configuration. Requires installing image processing dependencies for full functionality.

```yaml
plugins:
  - optimize
```

--------------------------------

### Generated project structure

Source: https://github.com/squidfunk/mkdocs-material/blob/master/docs/blog/posts/blog-support-just-landed.md

Shows the directory structure created by `mkdocs new .`.

```sh
.
├─ docs/
│  └─ index.md
└─ mkdocs.yml
```

--------------------------------

### Enable Critic extension

Source: https://github.com/squidfunk/mkdocs-material/blob/master/docs/setup/extensions/python-markdown-extensions.md

Adds the pymdownx.critic extension to support Critic Markup for tracking changes in documents. Configure via mkdocs.yml.

```yaml
markdown_extensions:
  - pymdownx.critic
```

--------------------------------

### Link with instant preview using data-preview attribute

Source: https://github.com/squidfunk/mkdocs-material/blob/master/docs/setup/setting-up-navigation.md

Add the `data-preview` attribute to any header link to enable instant previews for that link. This is an experimental feature limited to header links.

```markdown
[Attribute Lists](#){ data-preview }
```

--------------------------------

### Configure standalone blog in mkdocs.yml

Source: https://github.com/squidfunk/mkdocs-material/blob/master/docs/blog/posts/blog-support-just-landed.md

Replace the contents of `mkdocs.yml` with this configuration to host the blog at the root of the project. The `blog_dir: .` option is essential for a standalone blog.

```yaml
site_name: My Blog
theme:
  name: material
  features:
    - navigation.sections
plugins:
  - blog:
      blog_dir: . # (1)!
  - search
  - tags
nav:
  - index.md
```

--------------------------------

### Switch from Insiders to community edition in requirements.txt

Source: https://github.com/squidfunk/mkdocs-material/blob/master/docs/blog/posts/insiders-now-free-for-everyone.md

Replace the Insiders installation line with the community edition package. This removes the need for a personal access token and ensures you receive all future bug fixes.

```diff
- pip install git+https://${GH_TOKEN}@github.com/squidfunk/mkdocs-material-insiders. git
+ pip install mkdocs-material
```

--------------------------------

### Blog directory structure

Source: https://github.com/squidfunk/mkdocs-material/blob/master/docs/setup/setting-up-a-blog.md

Shows the expected directory layout for the blog plugin, with posts inside the `posts` directory. The `hello-world.md` file is the first post.

```sh
.
├─ docs/
│  └─ blog/
│     ├─ posts/
│     │  └─ hello-world.md # (1)!
│     └─ index.md
└─ mkdocs.yml
```

--------------------------------

### Enable versioning with mike provider in mkdocs.yml

Source: https://github.com/squidfunk/mkdocs-material/blob/master/docs/setup/setting-up-versioning.md

Add this configuration to mkdocs.yml to enable versioning with the mike utility. This renders a version selector in the header.

```yaml
extra:
  version:
    provider: mike
```

--------------------------------

### Code block with line numbers (markdown source)

Source: https://github.com/squidfunk/mkdocs-material/blob/master/docs/reference/code-blocks.md

Add line numbers using the `linenums="<start>"` option after the shortcode. The start value sets the starting line number, allowing code blocks to begin from numbers other than 1.

```markdown
``` py linenums="1"
def bubble_sort(items):
    for i in range(len(items)):
        for j in range(len(items) - 1 - i):
            if items[j] > items[j + 1]:
                items[j], items[j + 1] = items[j + 1], items[j]
```
```

--------------------------------

### Install git-committers plugin with pip

Source: https://github.com/squidfunk/mkdocs-material/blob/master/docs/setup/adding-a-git-repository.md

Install the git-committers plugin using pip. The recommended fork is mkdocs-git-committers-plugin-2.

```bash
pip install mkdocs-git-committers-plugin-2
```

--------------------------------

### Bootstrap a new MkDocs project with Docker (Windows cmd)

Source: https://github.com/squidfunk/mkdocs-material/blob/master/docs/creating-your-site.md

Use this command when running Material for MkDocs from within Docker on Windows cmd. It mounts the current directory to /docs and runs the new command.

```bash
docker run --rm -it -v "%cd%":/docs squidfunk/mkdocs-material new .
```

--------------------------------

### Enable instant loading in mkdocs.yml

Source: https://github.com/squidfunk/mkdocs-material/blob/master/docs/setup/setting-up-navigation.md

Adds the navigation.instant feature to enable instant loading, which intercepts clicks and dispatches via XHR without full page reloads. Requires setting site_url for the sitemap to work.

```yaml
theme:
  features:
    - navigation.instant
```

--------------------------------

### Add tag to multiple pages with .meta.yml

Source: https://github.com/squidfunk/mkdocs-material/blob/master/docs/plugins/meta.md

Place this file in a folder to add the tag 'Example' to all pages in that folder and its subfolders. Lists and dictionaries are recursively merged.

```yaml
tags:
  - Example
```

--------------------------------

### Annotation tooltip width: example annotation

Source: https://github.com/squidfunk/mkdocs-material/blob/master/docs/reference/code-blocks.md

Example of an annotation that will render with a larger width when the tooltip width is increased.

```yaml
# (1)!
```

--------------------------------

### Enable Abbreviations extension in mkdocs.yml

Source: https://github.com/squidfunk/mkdocs-material/blob/master/docs/setup/extensions/python-markdown.md

Adds the 'abbr' extension to enable tooltips on plain text elements. No configuration options are available.

```yaml
markdown_extensions:
  - abbr
```

--------------------------------

### macOS: Set DYLD_FALLBACK_LIBRARY_PATH for Cairo

Source: https://github.com/squidfunk/mkdocs-material/blob/master/docs/plugins/requirements/image-processing.md

Workaround for macOS when Homebrew does not set the needed variables. Add the Homebrew lib path before running MkDocs.

```bash
export DYLD_FALLBACK_LIBRARY_PATH=/opt/homebrew/lib
```

--------------------------------

### Enable Caret, Mark & Tilde extensions

Source: https://github.com/squidfunk/mkdocs-material/blob/master/docs/setup/extensions/python-markdown-extensions.md

Adds the pymdownx.caret, pymdownx.mark, and pymdownx.tilde extensions to enable text highlighting and sub/superscript syntax. Configure via mkdocs.yml.

```yaml
markdown_extensions:
  - pymdownx.caret
  - pymdownx.mark
  - pymdownx.tilde
```

--------------------------------

### Install mkdocs-exclude-search plugin

Source: https://github.com/squidfunk/mkdocs-material/blob/master/docs/blog/posts/excluding-content-from-search.md

Install the mkdocs-exclude-search plugin via pip to exclude specific pages and sections from the search index.

```bash
pip install mkdocs-exclude-search
```

--------------------------------

### Add front matter and content to hello-world.md

Source: https://github.com/squidfunk/mkdocs-material/blob/master/docs/blog/posts/blog-support-just-landed.md

YAML front matter and Markdown content for a blog post. The `draft: true` metadata marks the post as a draft, showing a red marker on index pages and excluding it from the built site unless changed via the `draft` configuration. The `date` and `categories` fields are used for post URLs and category indexes. The `<!-- more -->` comment separates the excerpt from the rest of the post.

```yaml
---
draft: true # (1)!
date: 2022-01-31
categories:
  - Hello
  - World
---

# Hello world!

Lorem ipsum dolor sit amet, consectetur adipiscing elit. Pellentesque nec
maximus ex. Sed consequat, nulla quis malesuada dapibus, elit metus vehicula
erat, ut egestas tellus eros at risus. In hac habitasse platea dictumst.
Phasellus id lacus pulvinar erat consequat pretium. Morbi malesuada arcu mauris
Nam vel justo sem. Nam placerat purus non varius luctus. Integer pretium leo in
sem rhoncus, quis gravida orci mollis. Proin id aliquam est. Vivamus in nunc ac
metus tristique pellentesque. Suspendisse viverra urna in accumsan aliquet.

<!-- more -->

Donec volutpat, elit ac volutpat laoreet, turpis dolor semper nibh, et dictum
massa ex pulvinar elit. Curabitur commodo sit amet dolor sed mattis. Etiam
tempor odio eu nisi gravida cursus. Maecenas ante enim, fermentum sit amet
molestie nec, mollis ac libero. Vivamus sagittis suscipit eros ut luctus.

Nunc vehicula sagittis condimentum. Cras facilisis bibendum lorem et feugiat.
In auctor accumsan ligula, at consectetur erat commodo quis. Morbi ac nunc
pharetra, pellentesque risus in, consectetur urna. Nulla id enim facilisis
arcu tincidunt pulvinar. Vestibulum laoreet risus scelerisque porta congue.
In velit purus, dictum quis neque nec, molestie viverra risus. Nam pellentesque
tellus id elit ultricies, vel finibus erat cursus.
```

--------------------------------

### Set site_url for instant navigation

Source: https://github.com/squidfunk/mkdocs-material/blob/master/docs/setup/setting-up-navigation.md

Required when using instant navigation, as it relies on the generated sitemap.xml which will be empty if omitted.

```yaml
site_url: https://example.com
```

--------------------------------

### Enable Highlight extension with anchor_linenums and SuperFences

Source: https://github.com/squidfunk/mkdocs-material/blob/master/docs/setup/extensions/python-markdown-extensions.md

Enables syntax highlighting for code blocks and inline code. Requires pymdownx.superfences to be enabled as well.

```yaml
markdown_extensions:
  - pymdownx.highlight:
      anchor_linenums: true
  - pymdownx.superfences # (1)!
```

--------------------------------

### Changes to *.html files: search configuration and initialization

Source: https://github.com/squidfunk/mkdocs-material/blob/master/docs/upgrade.md

Shows the diff for updating HTML files, adding search configuration keys and initialization script. The diff adds translation keys for search results and initializes the app with search worker URL.

```diff
    +        "search.config.separator",
    +        "search.result.placeholder",
    +        "search.result.none",
    +        "search.result.one",
    +        "search.result.other"
    +      ] -%}
    +        {%- set _ = translations.update({ key: lang.t(key) }) -%}
    +      {%- endfor -%}
    +      <script id="__lang" type="application/json">
    +        {{- translations | tojson -}}
    +      </script>
    +      {% block config %}{% endblock %}
    +      <script>
    +        app = initialize({
    +          base: "{{ base_url }}",
    +          features: {{ config.theme.features | tojson }},
    +          search: Object.assign({
    +            worker: "{{ 'assets/javascripts/worker/search.********.min.js' | url }}"
    +          }, typeof search !== "undefined" && search)
    +        })
    +      </script>
           {% for path in config["extra_javascript"] %}
             <script src="{{ path | url }}"></script>
           {% endfor %}
```

--------------------------------

### Enable Arithmatex in mkdocs.yml

Source: https://github.com/squidfunk/mkdocs-material/blob/master/docs/setup/extensions/python-markdown-extensions.md

Enables the Arithmatex extension for rendering block and inline equations with MathJax. Requires a MathJax configuration and JavaScript runtime to be included.

```yaml
markdown_extensions:
  - pymdownx.arithmatex:
      generic: true
```

--------------------------------

### Enable navigation.footer feature

Source: https://github.com/squidfunk/mkdocs-material/blob/master/docs/setup/setting-up-the-footer.md

Adds previous and next page links to the footer. Requires Material for MkDocs 9.0.0 or later.

```yaml
theme:
  features:
    - navigation.footer
```

--------------------------------

### Build with Docker on Unix and Powershell

Source: https://github.com/squidfunk/mkdocs-material/blob/master/docs/creating-your-site.md

Runs the build inside a Docker container for Unix and PowerShell environments. Mounts the current directory to /docs in the container.

```bash
docker run --rm -it -v ${PWD}:/docs squidfunk/mkdocs-material build
```

--------------------------------

### Link a page to a section with index.md

Source: https://github.com/squidfunk/mkdocs-material/blob/master/docs/setup/setting-up-navigation.md

Shows how to structure the nav configuration to attach an index.md page to a section. MkDocs also considers README.md as an index page.

```yaml
nav:
  - Section:
    - section/index.md # (1)!
    - Page 1: section/page-1.md
    ...
    - Page n: section/page-n.md
```

--------------------------------

### Bootstrap a new MkDocs project with Docker (Unix, Powershell)

Source: https://github.com/squidfunk/mkdocs-material/blob/master/docs/creating-your-site.md

Use this command when running Material for MkDocs from within Docker on Unix or Powershell. It mounts the current directory to /docs and runs the new command.

```bash
docker run --rm -it -v ${PWD}:/docs squidfunk/mkdocs-material new .
```

--------------------------------

### Linux: Run Cairo lookup debug script

Source: https://github.com/squidfunk/mkdocs-material/blob/master/docs/plugins/requirements/image-processing.md

Downloads and runs the cairo-lookup-linux.py debug script to see which function is run to find installed libraries.

```bash
curl "https://raw.githubusercontent.com/squidfunk/mkdocs-material/master/includes/debug/cairo-lookup-linux.py" | python -
```

--------------------------------

### Windows: MSYS2 UCRT64 binary path

Source: https://github.com/squidfunk/mkdocs-material/blob/master/docs/plugins/requirements/image-processing.md

Default binary and shared library path for the UCRT64 environment of MSYS2, where packages were installed using the above commands.

```powershell
C:\msys64\ucrt64\bin
```

--------------------------------

### Highlight specific lines with hl_lines argument

Source: https://github.com/squidfunk/mkdocs-material/blob/master/docs/reference/code-blocks.md

Use the hl_lines argument after the language shortcode to highlight specific lines. Line counts start at 1, regardless of the starting line number specified in linenums.

```markdown
``` py hl_lines="2 3"
def bubble_sort(items):
    for i in range(len(items)):
        for j in range(len(items) - 1 - i):
            if items[j] > items[j + 1]:
                items[j], items[j + 1] = items[j + 1], items[j]
```
```

--------------------------------

### Install jieba for Chinese search support

Source: https://github.com/squidfunk/mkdocs-material/blob/master/docs/blog/posts/chinese-search-support.md

Install the jieba library to enable Chinese text segmentation for the built-in search plugin. This is required for the plugin to automatically detect and segment Chinese characters.

```bash
pip install jieba
```

--------------------------------

### Card grid complex example

Source: https://github.com/squidfunk/mkdocs-material/blob/master/docs/reference/grids.md

A more complex card grid example that includes icons, links, and additional Markdown content within each list item. The surrounding div must have the 'markdown' attribute to render the Markdown.

```html
<div class="grid cards" markdown>

-   :material-clock-fast:{ .lg .middle } __Set up in 5 minutes__

    ---

    Install [`mkdocs-material`](#) with [`pip`](#) and get up
    and running in minutes

    [:octicons-arrow-right-24: Getting started](#)

-   :fontawesome-brands-markdown:{ .lg .middle } __It's just Markdown__

    ---

    Focus on your content and generate a responsive and searchable static site

    [:octicons-arrow-right-24: Reference](#)

-   :material-format-font:{ .lg .middle } __Made to measure__

    ---

    Change the colors, fonts, language, icons, logo and more with a few lines

    [:octicons-arrow-right-24: Customization](#)

-   :material-scale-balance:{ .lg .middle } __Open Source, MIT__

    ---

    Material for MkDocs is licensed under MIT and available on [GitHub]

    [:octicons-arrow-right-24: License](#)

</div>
```

--------------------------------

### Use scoped listing by id

Source: https://github.com/squidfunk/mkdocs-material/blob/master/docs/setup/setting-up-tags.md

References the scoped listing configuration defined in `mkdocs.yml` by its id.

```html
<!-- material/tags scoped -->
```

--------------------------------

### Cairo library not found error messages

Source: https://github.com/squidfunk/mkdocs-material/blob/master/docs/plugins/requirements/image-processing.md

Error output shown when the cairosvg package is installed but the cairocffi dependency cannot find the Cairo library. The exact messages vary by operating system and library lookup method.

```bash
no library called "cairo-2" was found
no library called "cairo" was found
no library called "libcairo-2" was found
cannot load library 'libcairo.so.2': error 0x7e.  Additionally, ctypes.util.find_library() did not manage to locate a library called 'libcairo.so.2'
cannot load library 'libcairo.2.dylib': error 0x7e.  Additionally, ctypes.util.find_library() did not manage to locate a library called 'libcairo.2.dylib'
cannot load library 'libcairo-2.dll': error 0x7e.  Additionally, ctypes.util.find_library() did not manage to locate a library called 'libcairo-2.dll'
```

--------------------------------

### Enable navigation.path feature

Source: https://github.com/squidfunk/mkdocs-material/blob/master/docs/setup/setting-up-navigation.md

Renders a breadcrumb navigation above the title of each page. Add these lines to mkdocs.yml.

```yaml
theme:
  features:
    - navigation.path
```

--------------------------------

### List only specific tags

Source: https://github.com/squidfunk/mkdocs-material/blob/master/docs/setup/setting-up-tags.md

Limits the tags index to only the specified tags, e.g., `Foo` and `Bar`, excluding all others.

```html
<!-- material/tags { include: [Foo, Bar] } -->
```

--------------------------------

### Enable tags plugin in mkdocs.yml

Source: https://github.com/squidfunk/mkdocs-material/blob/master/docs/plugins/tags.md

Adds the built-in tags plugin to your MkDocs project. No installation required.

```yaml
plugins:
  - tags

```

--------------------------------

### Enable InlineHilite with Highlight in mkdocs.yml

Source: https://github.com/squidfunk/mkdocs-material/blob/master/docs/setup/extensions/python-markdown-extensions.md

Adds syntax highlighting for inline code blocks. Requires the Highlight extension to be enabled first. The css_class option must not be changed.

```yaml
markdown_extensions:
  - pymdownx.highlight
  - pymdownx.inlinehilite
```

--------------------------------

### Enable tabs and instant loading in theme.features (5.x)

Source: https://github.com/squidfunk/mkdocs-material/blob/master/docs/upgrade.md

In 5.x, optional features like tabs and instant loading are enabled as flags under theme.features. Replace the old theme.feature.tabs: true configuration.

```yaml
theme:
  features:
    - tabs
    - instant

```

--------------------------------

### Set tags for an entire folder with .meta.yml

Source: https://github.com/squidfunk/mkdocs-material/blob/master/docs/setup/setting-up-tags.md

Creates a `.meta.yml` file to set tags for an entire section and all nested pages. Tags are merged and deduplicated with page-level tags, with `.meta.yml` tags appended.

```yaml
tags:
  - HTML5
  - JavaScript
  - CSS
```

--------------------------------

### Text with abbreviations

Source: https://github.com/squidfunk/mkdocs-material/blob/master/docs/reference/tooltips.md

Defines abbreviations using the special syntax starting with `*` and square brackets.

```markdown
The HTML specification is maintained by the W3C.

*[HTML]: Hyper Text Markup Language
*[W3C]: World Wide Web Consortium

```

--------------------------------

### Create partials/source-link.html

Source: https://github.com/squidfunk/mkdocs-material/blob/master/docs/upgrade.md

New partial that generates a link to the source file. It constructs the URL from the repository URL, page path, and source meta, and includes the repository icon.

```diff
@@ -0,0 +1,13 @@
+{#-
+  This file was automatically generated - do not edit
+-#}
+{% import "partials/language.html" as lang with context %}
+{% set repo = config.repo_url %}
+{% if repo | last == "/" %}
+  {% set repo = repo[:-1] %}
+{% endif %}
+{% set path = page.meta.path | default([""]) %}
+<a href="{{ [repo, path, page.meta.source] | join('/') }}" title="{{ file }}" class="md-content__button md-icon">
+  {{ lang.t("meta.source") }}
+  {% include ".icons/" ~ config.theme.icon.repo ~ ".svg" %}
+</a>

```

--------------------------------

### categories_sort_by: view_post_count

Source: https://github.com/squidfunk/mkdocs-material/blob/master/docs/plugins/blog.md

Specifies a custom function for sorting categories. The example sorts by the number of posts using material.plugins.blog.view_post_count.

```yaml
plugins:
  - blog:
      categories_sort_by: !!python/name:material.plugins.blog.view_post_count
```

--------------------------------

### Set blog_dir for Documentation + Blog

Source: https://github.com/squidfunk/mkdocs-material/blob/master/docs/plugins/blog.md

Sets the blog directory to 'blog' when the blog is part of a larger documentation site. The path is resolved from the docs directory.

```yaml
plugins:
  - blog:
      blog_dir: blog
```

--------------------------------

### Basic Admonition Syntax

Source: https://github.com/squidfunk/mkdocs-material/blob/master/docs/reference/admonitions.md

Starts an admonition block with `!!!` followed by a type qualifier. Content is indented by four spaces.

```markdown
!!! note

    Lorem ipsum dolor sit amet, consectetur adipiscing elit. Nulla et euismod
    nulla. Curabitur feugiat, tortor non consequat finibus, justo purus auctor
    massa, nec semper lorem quam in massa.
```

--------------------------------

### Enable progress indicator in mkdocs.yml

Source: https://github.com/squidfunk/mkdocs-material/blob/master/docs/setup/setting-up-navigation.md

Adds navigation.instant.progress to show a progress bar at the top of the page during navigation. Only shows if loading takes longer than 400ms.

```yaml
theme:
  features:
    - navigation.instant
    - navigation.instant.progress
```

--------------------------------

### Enable social plugin

Source: https://github.com/squidfunk/mkdocs-material/blob/master/docs/plugins/social.md

Adds the social plugin to your MkDocs configuration. The plugin is built-in and requires image processing dependencies to be installed.

```yaml
plugins:
  - social
```

--------------------------------

### Build static site with mkdocs build

Source: https://github.com/squidfunk/mkdocs-material/blob/master/docs/creating-your-site.md

Builds a static site from your Markdown files. The output directory is self-contained and can be hosted on GitHub Pages, GitLab Pages, a CDN, or private web space.

```bash
mkdocs build
```

--------------------------------

### Set shadow tags prefix

Source: https://github.com/squidfunk/mkdocs-material/blob/master/docs/plugins/tags.md

Define a string that marks tags as shadow tags when they start with it. A common practice is to use `_` as a prefix.

```yaml
plugins:
  - tags:
      shadow_tags_prefix: _
```

--------------------------------

### Configure mkdocs-exclude-search in mkdocs.yml

Source: https://github.com/squidfunk/mkdocs-material/blob/master/docs/blog/posts/excluding-content-from-search.md

Example configuration for the mkdocs-exclude-search plugin, defining exclusion patterns for pages and sections.

```yaml
plugins:
  - search
  - exclude-search:
      exclude:
        - page.md
        - page.md#section
        - directory/*
        - /*/page.md
```

--------------------------------

### Run Material for MkDocs in Docker (Windows)

Source: https://github.com/squidfunk/mkdocs-material/blob/master/docs/creating-your-site.md

Runs the Material for MkDocs Docker container with the current directory mounted to /docs, exposing the live preview on port 8000. Use this command on Windows (cmd).

```sh
docker run --rm -it -p 8000:8000 -v "%cd%":/docs squidfunk/mkdocs-material
```

--------------------------------

### Critic mode: reject

Source: https://github.com/squidfunk/mkdocs-material/blob/master/docs/setup/extensions/python-markdown-extensions.md

Sets the pymdownx.critic mode to 'reject' to automatically reject all suggested changes.

```yaml
markdown_extensions:
  - pymdownx.critic:
      mode: reject
```

--------------------------------

### Create a tags index page

Source: https://github.com/squidfunk/mkdocs-material/blob/master/docs/setup/setting-up-tags.md

Creates a `tags.md` page with the `<!-- material/tags -->` marker to render a tags index. The marker is replaced with the actual index when the page is rendered.

```markdown
# Tags

Following is a list of relevant tags:

<!-- material/tags -->
```

--------------------------------

### Fully qualified URL example (correct)

Source: https://github.com/squidfunk/mkdocs-material/blob/master/docs/plugins/privacy.md

Use fully qualified URLs so the plugin can detect and download them automatically.

```js
const url ="https://example.com/script.js"
```

--------------------------------

### Set toc slugify for Unicode case-sensitive

Source: https://github.com/squidfunk/mkdocs-material/blob/master/docs/setup/extensions/python-markdown.md

Customizes the slug function for Unicode, case-sensitive. Add to mkdocs.yml.

```yaml
markdown_extensions:
  - toc:
      slugify: !!python/object/apply:pymdownx.slugs.slugify {}
```

--------------------------------

### Run Material for MkDocs in Docker (Unix, Powershell)

Source: https://github.com/squidfunk/mkdocs-material/blob/master/docs/creating-your-site.md

Runs the Material for MkDocs Docker container with the current directory mounted to /docs, exposing the live preview on port 8000. Use this command on Unix-like systems or PowerShell.

```sh
docker run --rm -it -p 8000:8000 -v ${PWD}:/docs squidfunk/mkdocs-material
```

--------------------------------

### Set toc slugify for Unicode

Source: https://github.com/squidfunk/mkdocs-material/blob/master/docs/setup/extensions/python-markdown.md

Customizes the slug function for Unicode, converting to lowercase. Add to mkdocs.yml.

```yaml
markdown_extensions:
  - toc:
      slugify: !!python/object/apply:pymdownx.slugs.slugify
        kwds:
          case: lower
```

--------------------------------

### Show version alias in version selector

Source: https://github.com/squidfunk/mkdocs-material/blob/master/docs/setup/setting-up-versioning.md

Enable the 'alias' option to display the version alias alongside the version number in the version selector.

```yaml
extra:
  version:
    alias: true
```

--------------------------------

### Enable navigation.prune feature

Source: https://github.com/squidfunk/mkdocs-material/blob/master/docs/setup/setting-up-navigation.md

Includes only visible navigation items in the rendered HTML, reducing site size by 33% or more. Not compatible with navigation.expand. Add these lines to mkdocs.yml.

```yaml
theme:
  features:
    - navigation.prune # (1)!
```

--------------------------------

### Set toc title

Source: https://github.com/squidfunk/mkdocs-material/blob/master/docs/setup/extensions/python-markdown.md

Sets the title of the table of contents in the right navigation sidebar. Add to mkdocs.yml.

```yaml
markdown_extensions:
  - toc:
      title: On this page
```

--------------------------------

### Set default front matter with .meta.yml

Source: https://github.com/squidfunk/mkdocs-material/blob/master/docs/setup/setting-up-a-blog.md

Place a `.meta.yml` file in a folder to define default front matter properties for posts in that folder. Lists and dictionaries are merged and deduplicated with per-post values. The meta plugin must be defined before the blog plugin in `mkdocs.yml`.

```sh
.
├─ docs/
│  └─ blog/
│     ├─ posts/
│     ├─ .meta.yml # (1)!
│     └─ index.md
└─ mkdocs.yml
```

```yaml
authors:
  - squidfunk
categories:
  - Hello
  - World
```

--------------------------------

### GitHub Actions workflow for deploying with gh-deploy

Source: https://github.com/squidfunk/mkdocs-material/blob/master/docs/publishing-your-site.md

Create this workflow at .github/workflows/ci.yml to automatically build and deploy the site on pushes to master or main. It configures Git credentials, caches dependencies, installs mkdocs-material, and runs mkdocs gh-deploy --force. The cache_id uses the week number (%V) for weekly cache updates; change to %F for daily updates.

```yaml
name: ci # (1)!
on:
  push:
    branches:
      - master # (2)!
      - main
permissions:
  contents: write
jobs:
  deploy:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      - name: Configure Git Credentials
        run: |
          git config user.name github-actions[bot]
          git config user.email 41898282+github-actions[bot]@users.noreply.github.com
      - uses: actions/setup-python@v5
        with:
          python-version: 3.x
      - run: echo "cache_id=$(date --utc '+%V')" >> $GITHUB_ENV # (3)!
      - uses: actions/cache@v4
        with:
          key: mkdocs-material-${{ env.cache_id }}
          path: ~/.cache # (4)!
          restore-keys: |
            mkdocs-material-
      - run: pip install mkdocs-material # (5)!
      - run: mkdocs gh-deploy --force
```

--------------------------------

### Critic mode: view

Source: https://github.com/squidfunk/mkdocs-material/blob/master/docs/setup/extensions/python-markdown-extensions.md

Sets the pymdownx.critic mode to 'view' to display all suggested changes without applying them.

```yaml
markdown_extensions:
  - pymdownx.critic:
      mode: view
```

--------------------------------

### Enable search plugin in mkdocs.yml

Source: https://github.com/squidfunk/mkdocs-material/blob/master/docs/plugins/search.md

Adds the built-in search plugin to your MkDocs configuration. This is the minimal setup required to enable search functionality.

```yaml
plugins:
  - search
```

--------------------------------

### Enable navigation.expand feature

Source: https://github.com/squidfunk/mkdocs-material/blob/master/docs/setup/setting-up-navigation.md

Expands all collapsible subsections in the left sidebar by default. Add these lines to mkdocs.yml.

```yaml
theme:
  features:
    - navigation.expand
```

--------------------------------

### Social link with Email icon

Source: https://github.com/squidfunk/mkdocs-material/blob/master/docs/setup/setting-up-the-footer.md

Example of a social link using an email icon. The link property supports mailto URIs.

```yaml
extra:
  social:
    - icon: fontawesome/solid/paper-plane
      link: mailto:<email-address>
```
Tokens:
Raw