### Install Theme from Source

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

Install the Material for MkDocs theme and its dependencies after cloning the repository. Use the `-e` flag for an editable installation.

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

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

### Example Directory Structure for Pure Blog

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

A folder tree structure for a pure blog setup without documentation, where the `posts` directory is directly under `docs/`.

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

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

### Install Node.js and dependencies

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

Install Node.js LTS and project-specific Node.js dependencies.

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

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

### Install jieba library

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 search plugin.

```bash
pip install jieba
```

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

### Install mkdocs-exclude-search plugin

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

Use pip to install the community-provided search exclusion plugin.

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

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

### Start Development Watcher

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

Use this command to start a watcher that rebuilds the theme on changes during development.

```bash
npm start
```

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

### Start Live Preview Server

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

Use this command to start the MkDocs live preview server. It automatically rebuilds the site on save. For faster rebuilds on large projects, consider the `--dirtyreload` flag.

```sh
mkdocs serve --livereload
```

```sh
mkdocs serve --dirtyreload
```

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

### Directory structure example

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

Illustrates how to structure your documentation directory to utilize the meta plugin. The `.meta.yml` file in the 'example' folder will affect 'a.md' and 'z.md'.

```sh
. 
├─ docs/
│  ├─ ...
│  ├─ example/
│  │  ├─ .meta.yml
│  │  ├─ a.md
│  │  ├─ ...
│  │  └─ z.md
│  └─ ...
└─ mkdocs.yml
```

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

### Install Imaging Dependencies

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

Install the imaging extra for MkDocs Material to get Pillow and CairoSVG. This is required for the social and optimize plugins.

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

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

### Complete GitHub Actions workflow with sparse-checkout

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

A full example of a GitHub Actions workflow that utilizes `git sparse-checkout` for building and deploying documentation. This workflow includes setting up Python, installing dependencies, and deploying 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
```

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

### Install RSS plugin

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

Install the RSS plugin using pip before configuring it in mkdocs.yml.

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

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

### Install MkDocs Material

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

Install the MkDocs Material theme using pip. This is the first step to using the theme.

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

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

### Project Directory Structure Example

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

Illustrates the expected directory layout for a multi-language project using the projects plugin.

```sh
. 
├─ docs/ 
├─ projects/ 
│  ├─ en/ 
│  │  ├─ docs/ 
│  │  └─ mkdocs.yml 
│  └─ de/ 
│     ├─ docs/ 
│     └─ mkdocs.yml 
└─ mkdocs.yml
```

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

### Install pngquant on Linux

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

Install pngquant on Linux using the system's package manager, such as apt-get on Ubuntu.

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

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

### Install Cairo Graphics Dependencies on openSUSE

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

Install Cairo Graphics development libraries on openSUSE using zypper.

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

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

### Install Python dependencies

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

Install project dependencies and nodeenv.

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

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

### Start MkDocs Live Preview Server

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

Run this command in a separate terminal to serve the MkDocs site with live theme updates. Access the preview at http://localhost:8000.

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

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

### Example Directory Structure with Blog Subdirectory

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

An alternative directory structure where posts are organized within a `blog/posts/` path inside the `docs` directory.

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

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

### Manage dependencies with lockfiles

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

Create a requirements file to ensure reproducible builds and install from it.

```sh
pip freeze > requirements.txt
```

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

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

### Install GLightbox Plugin - Pip

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

Install the GLightbox plugin using pip for image zoom functionality.

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

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

### 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. This command is for the UCRT64 environment.

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

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

### Install Material for MkDocs via pip

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

Use these commands to install the latest version or a specific major version of the package.

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

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

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

### Archive creation output

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

Example terminal output after running mkdocs build with the info plugin enabled.

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

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

### Installing additional MkDocs plugins

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

This snippet shows how to install MkDocs Material along with other plugins or Markdown extensions using pip. Ensure these are listed when you need to extend MkDocs functionality.

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

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

### Blog Directory Structure Example

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

This is the default directory layout expected by the blog plugin. Missing directories or files will be created automatically.

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

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

### Install MkDocs RSS Plugin

Source: https://github.com/squidfunk/mkdocs-material/blob/master/docs/tutorials/blogs/engage.md

Install the MkDocs RSS plugin using pip. Ensure essential site settings are configured in mkdocs.yml for feed generation.

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

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

### Show Installed Version

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

Check the currently installed version of Material for MkDocs using pip. This is useful for verifying the upgrade or diagnosing issues.

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

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

### Inspect downloaded assets

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

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

```sh
.
└─ 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
```

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

### Install latest release with pip

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

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

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

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

### Install Cairo Graphics Dependencies on Ubuntu

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

Install Cairo Graphics development libraries on Ubuntu using apt-get.

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

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

### Enable the meta plugin in mkdocs.yml

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

Add this configuration to your `mkdocs.yml` file to activate the built-in meta plugin. It requires no separate installation.

```yaml
plugins:
  - meta
```

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

### Enable optimize plugin

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

Add this to your mkdocs.yml to enable the optimize plugin. It is built-in and requires no separate installation.

```yaml
plugins:
  - optimize
```

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

### Enable typeset plugin

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

Add this configuration to your mkdocs.yml to enable the typeset plugin. It requires no installation as it's built-in.

```yaml
plugins:
  - typeset
```

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

### Install specific release with pip

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

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

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

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

### Configure Blog Directory in mkdocs.yml

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

Set the `blog_dir` option in `mkdocs.yml` to '.' to place blog posts in the root directory, enabling a pure blog setup without a 'blog' subdirectory in the URL.

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

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

### Example Blog Post Front Matter

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

Front matter for a blog post, including draft status, date, and categories. Draft posts are excluded from the build output by default.

```yaml
---

```

```yaml
draft: true

```

```yaml
date: 2024-01-31

```

```yaml
categories:

```

```yaml
  - Hello

```

```yaml
  - World

```

```yaml
---

```

```markdown
# Hello world!

```

```markdown
...
```

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

### Link Section Index Page in Navigation

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

Example of how to link an `index.md` file as the entry point for a section in `mkdocs.yml`.

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

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

### Create Blog Post Directory Structure

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

Create a `posts` directory within `docs/` and add a new Markdown file for your first blog post, `hello-world.md`.

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

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

### Minimal Markdown Extension Configuration

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

A basic configuration setup for new projects, enabling essential extensions like table of contents, syntax highlighting, and super fences.

```yaml
markdown_extensions:

  # Python Markdown
  - toc:
      permalink: true

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

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

### Blog Post with Multiple Dates

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

Example of front matter for a blog post specifying both creation and update dates. The creation date must be set under `date.created`.

```yaml
---

```

```yaml
date:

```

```yaml
  created: 2022-01-31

```

```yaml
  updated: 2022-02-02

```

```yaml
---

```

```markdown
# Hello world!

```

```markdown
...
```

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

### Install pngquant on macOS

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

Install pngquant on macOS using Homebrew. This is a dependency for the optimize plugin.

```bash
brew install pngquant
```

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

### Define Project Configuration Transformation Function

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

Example Python function to transform project configuration, inheriting settings like `use_directory_urls` from the top-level configuration.

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

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

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

### Set Site URL for Instant Navigation

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

The `site_url` setting must be configured when using instant navigation, as it relies on `sitemap.xml`. This example shows a typical configuration.

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

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

### Create New MkDocs Project

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

Bootstrap a new MkDocs project in the current directory. This command sets up the basic file structure for your project.

```bash
mkdocs new .
```

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

### Install git-authors Plugin

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

Install the git-authors plugin using pip. This plugin is a lightweight alternative to git-committers.

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

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

### Create a Blog Post

Source: https://github.com/squidfunk/mkdocs-material/blob/master/docs/tutorials/blogs/basic.md

Write your first blog post in a Markdown file. Include a header with at least a `date` entry, a level one heading for the slug, and use `<!-- more -->` to define the excerpt.

```markdown
---
date:
  created: 2023-12-31
---

# Happy new years eve!

We hope you are all having fun and wish you all the best for the new year!
<!-- more -->

Lorem ipsum dolor sit amet, consectetur adipiscing elit, sed do eiusmod
tempor incididunt ut labore et dolore magna aliqua.

```

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

### Install git-revision-date-localized Plugin

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

Install the `mkdocs-git-revision-date-localized-plugin` using pip. This plugin is required to display document dates.

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

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

### Clone repository

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

Initial steps to clone the project repository.

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

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

### Build All Theme Files Including Overrides

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

Use this command if you have forked the theme and need to build all theme files, including overrides, icon search index, schema files, and additional assets. This command takes longer to execute.

```bash
npm run build:all
```

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

### Run MkDocs Serve with Docker

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

These commands allow you to run the MkDocs live preview server within a Docker container, ensuring a consistent environment. Mount your project directory to the container to serve your documentation.

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

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

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

### Install git-committers Plugin

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

Install the git-committers plugin using pip. Ensure you use the recommended fork for improvements.

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

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

### Configure instant previews via Markdown extensions

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

Enable instant previews for specific pages or sections by adding the preview extension to your configuration.

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

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

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

### Install Cairo Graphics Dependencies on Fedora

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

Install Cairo Graphics development libraries on Fedora using yum.

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

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

### Enable Instant Prefetching

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

Enable this experimental feature in `mkdocs.yml` to prefetch pages when a user hovers over a link, reducing perceived loading times.

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

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

### Create virtual environment

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

Commands to initialize and activate a Python virtual environment.

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

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

### Install Cairo Graphics on Windows with MSYS2

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

Install the Cairo Graphics library on Windows using MSYS2. This command is for the UCRT64 environment.

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

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

### Create New MkDocs Project with Docker

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

Run this command to bootstrap a new MkDocs project when using Material for MkDocs within Docker. Choose the appropriate command based on your shell.

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

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

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

### Install Cairo Graphics Dependencies on macOS

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. This is required for image processing features.

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

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

### Configure Standalone Blog

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

Configure `mkdocs.yml` for a standalone blog. Set `blog_dir` to '.' to host the blog at the project root. Includes essential theme features and plugins.

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

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

### Configure Blog Plugin in mkdocs.yml

Source: https://github.com/squidfunk/mkdocs-material/blob/master/docs/tutorials/blogs/basic.md

Add the blog plugin to your `mkdocs.yml` configuration to enable blog functionality. Ensure `search` is also included if needed.

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

```

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

### Build MkDocs Site with Docker

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

Use these Docker commands to build your static documentation site. This is useful for ensuring a consistent build environment, especially when deploying.

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

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

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

### Add Line Numbers to Code Block

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

Use the `linenums="<start>"` option to add line numbers to a code block, specifying the starting line number.

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

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

### Custom Table of Contents Slugify Function

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

Use a custom slugify function for table of contents entries, for example, to control casing. This example uses 'pymdownx.slugs.slugify' for lowercase slugs.

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

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

### Configure MathJax and MkDocs JavaScript

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

Set up the MathJax runtime and include necessary scripts in the project configuration.

```js
window.MathJax = {
  tex: {
    inlineMath: [["\\(", "\\)"]],
    displayMath: [["\\[", "\\]"]],
    processEscapes: true,
    processEnvironments: true
  },
  options: {
    ignoreHtmlClass: ".*|",
    processHtmlClass: "arithmatex"
  }
};

document$.subscribe(() => { // (1)!
  MathJax.startup.output.clearCache()
  MathJax.typesetClear()
  MathJax.texReset()
  MathJax.typesetPromise()
})
```

```yaml
extra_javascript:
  - javascripts/mathjax.js
  - https://unpkg.com/mathjax@3/es5/tex-mml-chtml.js
```

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

### Deploy a new documentation version

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

Use this command to deploy a specific version and update the alias to point to it.

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

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

### Classic Admonition Syntax

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

Example of the classic admonition appearance.

```markdown
!!! classic "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.
```

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

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

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

Ensure the meta plugin is defined before the blog plugin to correctly apply default properties.

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

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

### Admonition Type Examples

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

Syntax for various admonition types supported by Material for MkDocs.

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

```markdown
!!! abstract

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

```markdown
!!! info

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

```markdown
!!! tip

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

```markdown
!!! success

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

```markdown
!!! question

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

```markdown
!!! warning

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

```markdown
!!! failure

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

```markdown
!!! danger

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

```markdown
!!! bug

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

```markdown
!!! example

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

```markdown
!!! quote

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

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

### Configure KaTeX in mkdocs.yml

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

Add these settings to your `mkdocs.yml` to use KaTeX. Include the necessary JavaScript and CSS files in `extra_javascript` and `extra_css`.

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

extra_javascript:
  - javascripts/katex.js
  - https://unpkg.com/katex@0/dist/katex.min.js
  - https://unpkg.com/katex@0/dist/contrib/auto-render.min.js

extra_css:
  - https://unpkg.com/katex@0/dist/katex.min.css

```

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

### Enable Footnotes Extension

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

Add this to your mkdocs.yml to enable the footnotes extension. Ensure Python-Markdown is installed.

```yaml
markdown_extensions:
  - footnotes
```

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

### Configure macOS Library Path

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

Workaround to set the library path for Homebrew installations on macOS.

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

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

### Set FontAwesome Admonition Icons

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

Example configuration using FontAwesome for all standard admonition types.

```yaml
theme:
  icon:
    admonition:
      note: fontawesome/solid/note-sticky
      abstract: fontawesome/solid/book
      info: fontawesome/solid/circle-info
      tip: fontawesome/solid/bullhorn
      success: fontawesome/solid/check
      question: fontawesome/solid/circle-question
      warning: fontawesome/solid/triangle-exclamation
      failure: fontawesome/solid/bomb
      danger: fontawesome/solid/skull
      bug: fontawesome/solid/robot
      example: fontawesome/solid/flask
      quote: fontawesome/solid/quote-left
```

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

### Set Octicons Admonition Icons

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

Example configuration using Octicons for all standard admonition types.

```yaml
theme:
  icon:
    admonition:
      note: octicons/tag-16
      abstract: octicons/checklist-16
      info: octicons/info-16
      tip: octicons/squirrel-16
      success: octicons/check-16
      question: octicons/question-16
      warning: octicons/alert-16
      failure: octicons/x-circle-16
      danger: octicons/zap-16
      bug: octicons/bug-16
      example: octicons/beaker-16
      quote: octicons/quote-16
```

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

### Enable global instant previews

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

Activate instant previews for all header links globally in the theme features.

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

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

### Configure GLightbox Plugin - MkDocs

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

Add this line to `mkdocs.yml` to enable the GLightbox plugin for image zoom.

```yaml
plugins:
  - glightbox
```

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

### Privacy Plugin Configuration

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

Configuration example for enabling the built-in privacy plugin in your mkdocs.yml file.

```APIDOC
## Enable Privacy Plugin

### Description
Enables the built-in privacy plugin to automatically self-host external assets.

### Method
Configuration

### Endpoint
n/a

### Parameters
#### Request Body
- **plugins** (array) - Required - List of plugins to enable.
  - **privacy** (object) - Optional - Configuration for the privacy plugin.
    - **enabled** (boolean) - Optional - `true` to enable, `false` to disable. Defaults to `true`.
    - **concurrency** (integer) - Optional - Number of parallel processes for handling assets. Defaults to available CPUs - 1.

### Request Example
```yaml
plugins:
  - privacy
```

### Request Example with Options
```yaml
plugins:
  - privacy:
      enabled: !ENV [CI, false]
      concurrency: 4
```

### Response
This plugin operates during the build process and does not have a direct API response in the traditional sense. Its effects are seen in the generated site files.
```

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

### Create a virtual environment

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

Initializes a new isolated Python runtime environment.

```bash
python3 -m venv venv
```

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

### Override site title block

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

Example of replacing the default site title block in main.html.

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

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

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

### Build Static Site

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

This command generates the static HTML files for your documentation site. The output is placed in the `site` directory.

```sh
mkdocs build
```

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

### Cairo Library Error Output

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

Example of the error message displayed when the Cairo library cannot be located by the system.

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

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

### Build with environment variables

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

Enable multiple plugin groups by setting environment variables during the build process.

```shell
CI=true INSIDERS=true mkdocs build
```

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

### Enable built-in blog plugin

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

Add this to your mkdocs.yml to enable the blog plugin. No further configuration is needed if you don't have a navigation definition.

```yaml
plugins:
  - blog
```

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

### Split and Get Macro

Source: https://github.com/squidfunk/mkdocs-material/blob/master/src/templates/partials/social.html

Utility macro to split a string by a separator and return the element at a specific index.

```jinja2
{% macro split_and_get(value, sep, index) %} {%- if value.split is defined -%} {%- set parts = value.split(sep) -%} {%- else -%} {%- set parts = value | split(sep) -%} {%- endif -%} {{- parts[index] -}} {% endmacro %}
```

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

### Split and Get Macro

Source: https://github.com/squidfunk/mkdocs-material/blob/master/material/templates/partials/social.html

Utility macro to split a string by a separator and return the element at a specific index.

```jinja2
{%- macro split_and_get(value, sep, index) %} {%- if value.split is defined -%} {%- set parts = value.split(sep) -%} {%- else -%} {%- set parts = value | split(sep) -%} {%- endif -%} {{- parts[index] -}} {% endmacro %}
```

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

### Create a basic card grid using list syntax

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

Wraps an unordered list in a div with 'grid' and 'cards' classes to generate a card layout.

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

- :fontawesome-brands-html5: __HTML__ for content and structure
- :fontawesome-brands-js: __JavaScript__ for interactivity
- :fontawesome-brands-css3: __CSS__ for text running out of boxes
- :fontawesome-brands-internet-explorer: __Internet Explorer__ ... huh?

</div>
```

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

### Configure pip virtual environment enforcement

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

Environment variable to ensure pip only installs within a virtual environment.

```bash
export PIP_REQUIRE_VIRTUALENV=true
```

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

### Enable info plugin on serve

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

Enable the plugin during local development previews by setting enabled_on_serve to true.

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

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

### Enable group plugin

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

Add this to your mkdocs.yml to include the group plugin. It's built-in and requires no separate installation.

```yaml
plugins:
  - group
```

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

### Language switching path behavior

Source: https://github.com/squidfunk/mkdocs-material/blob/master/docs/setup/changing-the-language.md

Example of how the language selector 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 Post Directory

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

Change the file system location for blog posts.

```yaml
plugins:
  - blog:
      post_dir: "{blog}/articles"
```

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

### Annotated JSON Example

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

Demonstrates using a code annotation within a JSON string, enabled by custom selectors.

```json
{
  "key": "value (1)"
}
```

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

### Enable social plugin

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

Add this to your mkdocs.yml to enable the built-in social plugin. Ensure image processing dependencies are installed.

```yaml
plugins:
  - social
```

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

### Recommended project directory structure

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

Recommended file structure to keep custom layouts outside the docs directory.

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

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

### Mermaid Entity-Relationship Diagram Example

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

Illustrates an entity-relationship diagram showing entities and their relationships. Useful for database schema representation.

```mermaid
erDiagram
  CUSTOMER ||--o{ ORDER : places
  ORDER ||--|{ LINE-ITEM : contains
  LINE-ITEM {
    string name
    int pricePerUnit
  }
  CUSTOMER }|..|{ DELIVERY-ADDRESS : uses
```

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

### Mermaid Class Diagram Example

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

Defines a class diagram with inheritance, attributes, and methods. Use this to model object-oriented structures.

```mermaid
classDiagram
  Person <|-- Student
  Person <|-- Professor
  Person : +String name
  Person : +String phoneNumber
  Person : +String emailAddress
  Person: +purchaseParkingPass()
  Address "1" <-- "0..1" Person:lives at
  class Student{
    +int studentNumber
    +int averageMark
    +isEligibleToEnrol()
    +getSeminarsTaken()
  }
  class Professor{
    +int salary
  }
  class Address{
    +String street
    +String city
    +String state
    +int postalCode
    +String country
    -validate()
    +outputAsLabel()
  }
```

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

### Example of external script before privacy plugin

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

This HTML snippet shows an external script reference before processing by the privacy plugin.

```html
<script src="https://example.com/script.js"></script>
```

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

### Create definition lists

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

Use the definition list syntax to create key-value pairs when the def_list extension is enabled.

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

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

### Use Emoji Shortcode

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

Integrate emojis into your Markdown content by enclosing their shortcodes within colons. This example uses the 'smile' emoji.

```markdown
:smile:
```

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

### Limit Table of Contents Depth

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

Control the heading levels included in the table of contents by setting 'toc.toc_depth'. This example limits it to 3 levels.

```yaml
markdown_extensions:
  - toc:
      toc_depth: 3
```

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

### Enable Projects Plugin

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

Add the 'projects' plugin to your mkdocs.yml to enable building and serving multiple MkDocs projects concurrently.

```yaml
plugins:
  - projects
```