Material for MkDocs

https://squidfunk.github.io/mkdocs-material
Admin
Material for MkDocs is an open-source theme that transforms Markdown documentation into...
Tokens:141,704
Snippets:1,995
Trust Score:8.3
Update:1 month ago
Show doc for...
Tokens:
Raw
### Start Development Watcher

Source: https://squidfunk.github.io/mkdocs-material/customization

Start the build watcher and the MkDocs live preview server.

```bash
npm start

```

```bash
mkdocs serve --watch-theme

```

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

### Define site structure

Source: https://squidfunk.github.io/mkdocs-material/setup/building-an-optimized-site

Example directory structure for a multi-project site setup.

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

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

### Install Dependencies from Requirements File

Source: https://squidfunk.github.io/mkdocs-material/getting-started

Install all project dependencies, including MkDocs and Material for MkDocs, from a requirements.txt lockfile.

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

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

### Start the live preview server

Source: https://squidfunk.github.io/mkdocs-material/creating-your-site

Launch the local development server with live reloading enabled.

```bash
mkdocs serve --livereload 
```

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

### Setup Virtual Environment

Source: https://squidfunk.github.io/mkdocs-material/customization

Create and activate a Python virtual environment.

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

```

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

### Install Node.js Dependencies

Source: https://squidfunk.github.io/mkdocs-material/customization

Install Node.js and project dependencies.

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

```

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

### Install glightbox Plugin

Source: https://squidfunk.github.io/mkdocs-material/reference/images

Install the glightbox plugin using pip to add image zoom functionality to your documentation.

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

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

### Start the preview server with Docker

Source: https://squidfunk.github.io/mkdocs-material/creating-your-site

Run the development server inside a Docker container, mapping port 8000.

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

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

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

### Install Material for MkDocs from Local Clone

Source: https://squidfunk.github.io/mkdocs-material/getting-started

Install Material for MkDocs in editable mode from a local clone of the repository, along with its dependencies.

```bash
pip install -e mkdocs-material
```

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

### Create a blog post with front matter

Source: https://squidfunk.github.io/mkdocs-material/setup/setting-up-a-blog

Example of a blog post file with draft status, date, and categories.

```markdown
---
draft: true 
date: 2024-01-31 
categories:
  - Hello
  - World
---

# Hello world!
...
```

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

### Show installed version with pip show

Source: https://squidfunk.github.io/mkdocs-material/upgrade

Display the currently installed version of Material for MkDocs.

```bash
pip show mkdocs-material

```

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

### Install the RSS plugin

Source: https://squidfunk.github.io/mkdocs-material/setup/setting-up-a-blog

Install the required RSS plugin via pip.

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

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

### Install Latest Material for MkDocs with pip

Source: https://squidfunk.github.io/mkdocs-material/getting-started

Install the latest stable version of Material for MkDocs using pip. It's recommended to use a virtual environment.

```bash
pip install mkdocs-material
```

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

### Install latest release with pip

Source: https://squidfunk.github.io/mkdocs-material/insiders

Installs the latest release of Material for MkDocs Insiders using pip. Ensure the GH_TOKEN environment variable is set.

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

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

### Define meta file structure

Source: https://squidfunk.github.io/mkdocs-material/setup/setting-up-a-blog

Example directory structure for using .meta.yml to set default front matter.

```text
.
├─ docs/
│  └─ blog/
│     ├─ posts/
│     ├─ .meta.yml 
│     └─ index.md
└─ mkdocs.yml

```

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

### Install Python Dependencies

Source: https://squidfunk.github.io/mkdocs-material/customization

Install required Python packages for development.

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

```

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

### Card Grid - List Syntax (Complex Example)

Source: https://squidfunk.github.io/mkdocs-material/reference/grids

A more advanced list syntax example for card grids, including icons, titles, descriptions, and links. Note the use of '.lg .middle' for icon sizing and alignment, and '---' for a visual separator.

```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>

```

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

### Bootstrap a new MkDocs project with mkdocs new

Source: https://squidfunk.github.io/mkdocs-material/guides/creating-a-reproduction

Bootstraps a new, empty MkDocs project in the current directory. This is the required starting point for a minimal reproduction.

```bash
mkdocs new .

```

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

### Install MkDocs RSS Plugin

Source: https://squidfunk.github.io/mkdocs-material/tutorials/blogs/engage

Install the MkDocs RSS Plugin using pip. This is a prerequisite for enabling RSS feed functionality.

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

```

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

### Install Insiders from local git repository

Source: https://squidfunk.github.io/mkdocs-material/insiders/upgrade

After checking out the desired version, change back to the parent directory and use pip to install the Insiders version in editable mode.

```bash
cd .. 
pip install -e mkdocs-material
```

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

### Install specific release with pip

Source: https://squidfunk.github.io/mkdocs-material/insiders

Installs a specific older release of Material for MkDocs Insiders using pip. Ensure the GH_TOKEN environment variable is set.

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

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

### Example JSON with Annotations

Source: https://squidfunk.github.io/mkdocs-material/reference/code-blocks

Demonstrates usage of annotations within a JSON string.

```json
{
  "key": "value 
}
```

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

### Blog Post Structure and Content

Source: https://squidfunk.github.io/mkdocs-material/setup/setting-up-a-blog

Example of how to structure a blog post file and its front matter for use with the blog plugin.

```APIDOC
## Usage: Writing Your First Post

### Description
Demonstrates the structure of a blog post file, including front matter and content, and how to create excerpts.

### Method
File Creation

### Endpoint
n/a

### Parameters
N/A

### Request Example
#### File: `docs/blog/posts/hello-world.md`
```markdown
---
draft: true 
date: 2024-01-31 
categories:
  - Hello
  - World
---

# Hello world!

This is the introduction to my first blog post. It will be displayed in lists and indexes.

<!-- more -->

This is the content that will only appear after the "more" separator or on the post's dedicated page.

```

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

### Enable the optimize plugin in mkdocs.yml

Source: https://squidfunk.github.io/mkdocs-material/plugins/optimize

Add these lines to mkdocs.yml to enable the optimize plugin. The plugin is built-in and doesn't need to be installed, but dependencies for image processing must be installed separately.

```yaml
plugins:
  - optimize

```

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

### Output of mkdocs build with info plugin

Source: https://squidfunk.github.io/mkdocs-material/guides/creating-a-reproduction

Example terminal output when running mkdocs build with the info plugin enabled. It shows the created archive and its contents, including example.zip.

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

  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

```

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

### View downloaded assets structure

Source: https://squidfunk.github.io/mkdocs-material/setup/ensuring-data-privacy

Example directory structure showing how the privacy plugin organizes downloaded external resources.

```text
.
└─ assets/external/
   ├─ unpkg.com/tablesort@5.3.0/dist/tablesort.min.js
   ├─ fonts.googleapis.com/css
   └─ fonts.gstatic.com/s/
      ├─ roboto/v29/
      │  ├─ KFOjCnqEu92Fr1Mu51TjASc-CsTKlA.woff2
      │  ├─ KFOjCnqEu92Fr1Mu51TjASc0CsTKlA.woff2
      │  ├─ KFOjCnqEu92Fr1Mu51TjASc1CsTKlA.woff2
      │  ├─ KFOjCnqEu92Fr1Mu51TjASc2CsTKlA.woff2
      │  ├─ KFOjCnqEu92Fr1Mu51TjASc3CsTKlA.woff2
      │  ├─ KFOjCnqEu92Fr1Mu51TjASc5CsTKlA.woff2
      │  ├─ KFOjCnqEu92Fr1Mu51TjASc6CsQ.woff2
      │  ├─ KFOjCnqEu92Fr1Mu51TzBic-CsTKlA.woff2
      │  ├─ KFOjCnqEu92Fr1Mu51TzBic0CsTKlA.woff2
      │  ├─ KFOjCnqEu92Fr1Mu51TzBic1CsTKlA.woff2
      │  ├─ KFOjCnqEu92Fr1Mu51TzBic2CsTKlA.woff2
      │  ├─ KFOjCnqEu92Fr1Mu51TzBic3CsTKlA.woff2
      │  ├─ KFOjCnqEu92Fr1Mu51TzBic5CsTKlA.woff2
      │  ├─ KFOjCnqEu92Fr1Mu51TzBic6CsQ.woff2
      │  ├─ KFOkCnqEu92Fr1Mu51xEIzIFKw.woff2
      │  ├─ KFOkCnqEu92Fr1Mu51xFIzIFKw.woff2
      │  ├─ KFOkCnqEu92Fr1Mu51xGIzIFKw.woff2
      │  ├─ KFOkCnqEu92Fr1Mu51xHIzIFKw.woff2
      │  ├─ KFOkCnqEu92Fr1Mu51xIIzI.woff2
      │  ├─ KFOkCnqEu92Fr1Mu51xLIzIFKw.woff2
      │  ├─ KFOkCnqEu92Fr1Mu51xMIzIFKw.woff2
      │  ├─ KFOlCnqEu92Fr1MmSU5fABc4EsA.woff2
      │  ├─ KFOlCnqEu92Fr1MmSU5fBBc4.woff2
      │  ├─ KFOlCnqEu92Fr1MmSU5fBxc4EsA.woff2
      │  ├─ KFOlCnqEu92Fr1MmSU5fCBc4EsA.woff2
      │  ├─ KFOlCnqEu92Fr1MmSU5fCRc4EsA.woff2
      │  ├─ KFOlCnqEu92Fr1MmSU5fChc4EsA.woff2
      │  ├─ KFOlCnqEu92Fr1MmSU5fCxc4EsA.woff2
      │  ├─ KFOlCnqEu92Fr1MmWUlfABc4EsA.woff2
      │  ├─ KFOlCnqEu92Fr1MmWUlfBBc4.woff2
      │  ├─ KFOlCnqEu92Fr1MmWUlfBxc4EsA.woff2
      │  ├─ KFOlCnqEu92Fr1MmWUlfCBc4EsA.woff2
      │  ├─ KFOlCnqEu92Fr1MmWUlfCRc4EsA.woff2
      │  ├─ KFOlCnqEu92Fr1MmWUlfChc4EsA.woff2
      │  ├─ KFOlCnqEu92Fr1MmWUlfCxc4EsA.woff2
      │  ├─ KFOmCnqEu92Fr1Mu4WxKOzY.woff2
      │  ├─ KFOmCnqEu92Fr1Mu4mxK.woff2
      │  ├─ KFOmCnqEu92Fr1Mu5mxKOzY.woff2
      │  ├─ KFOmCnqEu92Fr1Mu72xKOzY.woff2
      │  ├─ KFOmCnqEu92Fr1Mu7GxKOzY.woff2
      │  ├─ KFOmCnqEu92Fr1Mu7WxKOzY.woff2
      │  └─ KFOmCnqEu92Fr1Mu7mxKOzY.woff2
      └─ robotomono/v13/
         ├─ L0xTDF4xlVMF-BfR8bXMIhJHg45mwgGEFl0_3vrtSM1J-gEPT5Ese6hmHSV0mf0h.woff2
         ├─ L0xTDF4xlVMF-BfR8bXMIhJHg45mwgGEFl0_3vrtSM1J-gEPT5Ese6hmHSZ0mf0h.woff2
         ├─ L0xTDF4xlVMF-BfR8bXMIhJHg45mwgGEFl0_3vrtSM1J-gEPT5Ese6hmHSd0mf0h.woff2
         ├─ L0xTDF4xlVMF-BfR8bXMIhJHg45mwgGEFl0_3vrtSM1J-gEPT5Ese6hmHSh0mQ.woff2
         ├─ L0xTDF4xlVMF-BfR8bXMIhJHg45mwgGEFl0_3vrtSM1J-gEPT5Ese6hmHSt0mf0h.woff2
         ├─ L0xTDF4xlVMF-BfR8bXMIhJHg45mwgGEFl0_3vrtSM1J-gEPT5Ese6hmHSx0mf0h.woff2
```

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

### Example of a search preview

Source: https://squidfunk.github.io/mkdocs-material/blog/2021/09/13/search-better-faster-smaller

A sample representation of a search preview showing text context around search terms.

```text
… channels, e.g., or which can be configured via mkdocs.yml …
```

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

### Enable blog plugin

Source: https://squidfunk.github.io/mkdocs-material/plugins/blog

Enables the built-in blog plugin in mkdocs.yml. This is the minimal configuration required to start writing posts.

```yaml
plugins:
  - blog

```

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

### Configure Section Index Page

Source: https://squidfunk.github.io/mkdocs-material/setup/setting-up-navigation

Example of how to structure the `nav` in `mkdocs.yml` to include an index page for a section.

```yaml
nav:
  - Section:
    - section/index.md 
    - Page 1: section/page-1.md
    ...
    - Page n: section/page-n.md

```

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

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

Source: https://squidfunk.github.io/mkdocs-material/plugins/meta

Adds the tag 'Example' to all pages in the folder containing this .meta.yml file and its subfolders. Lists are recursively merged with page front matter.

```yaml
tags:
  - Example

```

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

### Set blog_dir

Source: https://squidfunk.github.io/mkdocs-material/plugins/blog

Changes the blog directory location. The first example sets it to 'blog' (default), the second sets it to the docs root. The path is resolved from the docs directory.

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

```

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

```

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

### Enable tags plugin in mkdocs.yml

Source: https://squidfunk.github.io/mkdocs-material/plugins/tags

Adds the built-in tags plugin to your MkDocs configuration. This is the minimal setup required to start using tags on your pages.

```yaml
plugins:
  - tags

```

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

### Initialize a project with Docker

Source: https://squidfunk.github.io/mkdocs-material/creating-your-site

Bootstrap a new project using the Material for MkDocs Docker image.

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

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

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

### Initialize a new MkDocs project

Source: https://squidfunk.github.io/mkdocs-material/blog/2022/09/12/blog-support-just-landed

Use the mkdocs executable to bootstrap a new project directory.

```bash
mkdocs new .
```

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

### Set up the blog index page

Source: https://squidfunk.github.io/mkdocs-material/blog/2022/09/12/blog-support-just-landed

Replace the default content in docs/index.md to initialize the blog index.

```markdown
# Blog
```

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

### Build blog output

Source: https://squidfunk.github.io/mkdocs-material/tutorials/blogs/basic

Command to build the site and verify the exclusion of draft posts.

```bash
$ mkdocs build
$ ls site/blog
site/blog
├── 2023
│   └── 12
│       └── 31
│           └── happy-new-years-eve
│               └── index.html
...
```

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

### Build static site with MkDocs

Source: https://squidfunk.github.io/mkdocs-material/creating-your-site

Use this command to build a static site from your Markdown files when not using Docker.

```bash
mkdocs build

```

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

### Install Specific Major Version with pip

Source: https://squidfunk.github.io/mkdocs-material/getting-started

Install a specific major version of Material for MkDocs, like 9.x, to ensure compatibility and avoid breaking changes.

```bash
pip install mkdocs-material=="9.*"
```

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

### Set up upstream remote and view remotes

Source: https://squidfunk.github.io/mkdocs-material/contributing/making-a-pull-request

Shows how to add the original Material for MkDocs repository as an 'upstream' remote and verify the configured remotes. The example includes the output of 'git remote -v' before and after adding 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)
```

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

### Build static site with MkDocs in Docker (Unix/Powershell)

Source: https://squidfunk.github.io/mkdocs-material/creating-your-site

Run this command to build your static site if you are using Material for MkDocs within Docker on Unix-like systems or Powershell.

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

```

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

### View project file structure

Source: https://squidfunk.github.io/mkdocs-material/blog/2022/09/12/blog-support-just-landed

The default file structure generated after running the initialization command.

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

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

### Add Line Numbers to Code Block

Source: https://squidfunk.github.io/mkdocs-material/reference/code-blocks

Use the `linenums` option to add line numbers, specifying a starting number if needed. Line numbering starts at 1 by default.

```python
``` 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]
```
```

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

### Markdown Example

Source: https://squidfunk.github.io/mkdocs-material/blog/2021/09/13/search-better-faster-smaller

An example Markdown file demonstrating various formatting elements like headings, bold, italic, links, code blocks, numbered lists, and bullet points.

```markdown
# 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:

1. One
2. Two
3. Three

Sometimes you want bullet points:

* Start a line with a star
* Profit!

```

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

### Deploy a new documentation version

Source: https://squidfunk.github.io/mkdocs-material/setup/setting-up-versioning

Use the mike CLI to deploy a specific version and update aliases.

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

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

### Search Index JSON Example

Source: https://squidfunk.github.io/mkdocs-material/blog/2021/09/13/search-better-faster-smaller

An example of a search index JSON structure, including configuration and document entries. Each document entry contains its location, title, and stripped text content.

```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!"
    }
  ]
}

```

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

### Clone Repository

Source: https://squidfunk.github.io/mkdocs-material/customization

Initial steps to clone the theme repository.

```bash
git clone https://github.com/squidfunk/mkdocs-material
cd mkdocs-material

```

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

### Build static site with MkDocs in Docker (Windows)

Source: https://squidfunk.github.io/mkdocs-material/creating-your-site

Use this command to build your static site if you are using Material for MkDocs within Docker on Windows.

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

```

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

### Upgrade Insiders via pip to the latest development version

Source: https://squidfunk.github.io/mkdocs-material/insiders/upgrade

Run this command to upgrade to the latest development version of Insiders when installed via pip. The `--force-reinstall` flag ensures the latest version is installed.

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

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

### Build Theme

Source: https://squidfunk.github.io/mkdocs-material/customization

Compile and minify theme assets for production.

```bash
npm run build 

```

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

### Override Site Title

Source: https://squidfunk.github.io/mkdocs-material/customization

Example of overriding the htmltitle block in main.html.

```jinja2
{% extends "base.html" %}

{% block htmltitle %}
  <title>Lorem ipsum dolor sit amet</title>
{% endblock %}

```

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

### MkDocs Project Structure with Blog Plugin

Source: https://squidfunk.github.io/mkdocs-material/tutorials/blogs/basic

The blog plugin automatically creates a directory structure for your blog posts. Run 'mkdocs serve' to generate these directories if they don't exist.

```bash
docs
├── blog
│   ├── index.md
│   └── posts
└── index.md

```

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

### Complete GitHub Actions workflow for documentation deployment

Source: https://squidfunk.github.io/mkdocs-material/blog/2023/09/22/using-git-sparse-checkout-for-faster-documentation-builds

A full GitHub Actions workflow that checks out the repository with sparse checkout, sets up Python, installs dependencies, and deploys documentation using MkDocs. Ensure `fetch-depth: 0` is used with sparse checkout.

```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

```

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

### Language switching behavior

Source: https://squidfunk.github.io/mkdocs-material/setup/changing-the-language

Example of how the site maintains the current page path when switching between languages.

```text
docs.example.com/en/     -> docs.example.com/de/
docs.example.com/en/foo/ -> docs.example.com/de/foo/
docs.example.com/en/bar/ -> docs.example.com/de/bar/

```

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

### Configure Mastodon Social Link

Source: https://squidfunk.github.io/mkdocs-material/setup/setting-up-the-footer

Example of configuring a Mastodon social link with its icon and URL in `mkdocs.yml`.

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

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

### Automate deployment with GitHub Actions

Source: https://squidfunk.github.io/mkdocs-material/publishing-your-site

Create a workflow file at .github/workflows/ci.yml to automatically deploy documentation on push to master or main branches.

```yaml
name: ci 
on:
  push:
    branches:
      - master 
      - 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 
      - uses: actions/cache@v4
        with:
          key: mkdocs-material-${{ env.cache_id }}
          path: ~/.cache 
          restore-keys: |
            mkdocs-material-
      - run: pip install mkdocs-material 
      - run: mkdocs gh-deploy --force
```

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

### Update requirements for Insiders migration

Source: https://squidfunk.github.io/mkdocs-material/blog/2025/11/11/insiders-now-free-for-everyone

Diff showing the transition from the Insiders repository to the community edition in installation commands.

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

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

### Configure a standalone blog

Source: https://squidfunk.github.io/mkdocs-material/setup/setting-up-a-blog

Set up a directory structure and plugin configuration for a blog-only site.

```text
.
├─ docs/
│  ├─ posts/ 
│  ├─ .authors.yml
│  └─ index.md
└─ mkdocs.yml
```

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

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

### Configure mkdocs.yml for a standalone blog

Source: https://squidfunk.github.io/mkdocs-material/blog/2022/09/12/blog-support-just-landed

Update the configuration file to enable the blog plugin at the project root.

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

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

### Configure Blog Plugin in mkdocs.yml

Source: https://squidfunk.github.io/mkdocs-material/tutorials/blogs/basic

Add the blog plugin to your mkdocs.yml file to enable blog functionality. Ensure site_name, site_description, and site_url are set.

```yaml
site_name: Blog Tutorial
site_description: an example blog set up following the tutorial
site_url: http://www.example.com

theme:
  name: material

plugins:
  - search
  - blog

```

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

### Unordered List Example

Source: https://squidfunk.github.io/mkdocs-material/reference/lists

Unordered lists are created using '-', '*', or '+' markers. Lists can be nested within each other.

```markdown
- Nulla et rhoncus turpis. Mauris ultricies elementum leo. Duis efficitur
  accumsan nibh eu mattis. Vivamus tempus velit eros, porttitor placerat nibh
  lacinia sed. Aenean in finibus diam.

    * Duis mollis est eget nibh volutpat, fermentum aliquet dui mollis.
    * Nam vulputate tincidunt fringilla.
    * Nullam dignissim ultrices urna non auctor.
```

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

### Search index JSON structure

Source: https://squidfunk.github.io/mkdocs-material/setup/setting-up-site-search

This is an example of the JSON structure generated for the search index, showing how included sections are represented.

```json
{
  "...": "",
  "docs": [
    {
      "location":"page/",
      "text":"",
      "title":"Document title"
    },
    {
      "location":"page/#section-1",
      "text":"<p>The content of this section is included</p>",
      "title":"Section 1"
    }
  ]
}
```

```json
{
  "...": "",
  "docs": [
    {
      "location":"page/",
      "text":"<p>The content of this block is included</p>",
      "title":"Document title"
    }
  ]
}
```

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

### Configure Font Directory Structure

Source: https://squidfunk.github.io/mkdocs-material/setup/setting-up-social-cards

Example of the directory structure generated by the social plugin when using the Roboto font family.

```text
.cache/plugins/social/fonts
└─ Roboto/
    ├─ Black.ttf
    ├─ Black Italic.ttf
    ├─ Bold.ttf
    ├─ Bold Italic.ttf
    ├─ Italic.ttf
    ├─ Light.ttf
    ├─ Light Italic.ttf
    ├─ Medium.ttf
    ├─ Medium Italic.ttf
    ├─ Regular.ttf
    ├─ Thin.ttf
    └─ Thin Italic.ttf
```

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

### Configure Highlight.js and CSS

Source: https://squidfunk.github.io/mkdocs-material/setup/extensions/python-markdown-extensions

Include Highlight.js library and a default stylesheet in mkdocs.yml for browser-based syntax highlighting.

```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
```

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

### Enable meta plugin in mkdocs.yml

Source: https://squidfunk.github.io/mkdocs-material/plugins/meta

Enables the built-in meta plugin in mkdocs.yml. The plugin is included with Material for MkDocs and does not need to be installed.

```yaml
plugins:
  - meta

```

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

### Minimal Markdown Configuration

Source: https://squidfunk.github.io/mkdocs-material/setup/extensions

A basic configuration for using Material for MkDocs with essential Markdown extensions. Start here and add features as needed.

```yaml
markdown_extensions:

  # Python Markdown
  - toc:
      permalink: true

  # Python Markdown Extensions
  - pymdownx.highlight
  - pymdownx.superfences

```

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

### Minimal mkdocs.yml configuration

Source: https://squidfunk.github.io/mkdocs-material/creating-your-site

Basic configuration required to enable the Material theme.

```yaml
site_name: My site
site_url: https://mydomain.org/mysite
theme:
  name: material
```

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

### Conditional Giscus Integration

Source: https://squidfunk.github.io/mkdocs-material/tutorials/blogs/engage

Example of wrapping the Giscus script in a Jinja2 conditional to restrict comments to pages with a specific metadata flag.

```jinja2
{% if page.meta.comments %}
<script>...</script>
{% endif %}
```

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

### Configure Icons in Social Cards

Source: https://squidfunk.github.io/mkdocs-material/setup/setting-up-social-cards

Examples of using the icon property to add and tint icons within social card layers.

```yaml
size: { width: 1200, height: 630 }
layers:
  - background:
      color: "#4051b5"
  - size: { width: 144, height: 144 }
    offset: { x: 992, y: 64 }
    icon:
      value: material/cat
      color: white
```

```yaml
size: { width: 1200, height: 630 }
layers:
  - background:
      color: "#4051b5"
  - size: { width: 2400, height: 2400 }
    offset: { x: -1024, y: 64 }
    icon:
      value: material/circle
      color: "#5c6bc0"
  - size: { width: 1800, height: 1800 }
    offset: { x: 512, y: -1024 }
    icon:
      value: material/circle
      color: "#3949ab"
```

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

### Enable instant previews globally

Source: https://squidfunk.github.io/mkdocs-material/setup/setting-up-navigation

Globally enable instant previews for all header links by adding `navigation.instant.preview` to theme features. This alleviates the need for `data-preview` attributes. Ensure `site_url` is set.

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

```

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

### Set site_url for instant navigation

Source: https://squidfunk.github.io/mkdocs-material/setup/setting-up-navigation

The `site_url` setting must be set when using instant navigation, as it relies on `sitemap.xml`. Example provided.

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

```

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

### Enable the info plugin during preview with enabled_on_serve: true

Source: https://squidfunk.github.io/mkdocs-material/plugins/info

Use this setting to control whether the plugin is enabled when previewing your site. It is normally not necessary to specify this setting, but it streamlines creating and inspecting minimal reproductions.

```yaml
plugins:
  - info:
      enabled_on_serve: true

```

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

### Definition List Example

Source: https://squidfunk.github.io/mkdocs-material/reference/lists

Definition lists allow for key-value pairs. The key is on one line, followed by a colon and indented value.

```markdown
`Lorem ipsum dolor sit amet`

:   Sed sagittis eleifend rutrum. Donec vitae suscipit est. Nullam tempus
    tellus non sem sollicitudin, quis rutrum leo facilisis.

`Cras arcu libero`

:   Aliquam metus eros, pretium sed nulla venenatis, faucibus auctor ex. Proin
    ut eros sed sapien ullamcorper consequat. Nunc ligula ante.

    Duis mollis est eget nibh volutpat, fermentum aliquet dui mollis.
    Nam vulputate tincidunt fringilla.
    Nullam dignissim ultrices urna non auctor.
```
Tokens:
Raw