---
name: mkdocs-material
description: Use when creating, configuring, editing, building, publishing, or troubleshooting MkDocs documentation sites that use the Material theme, including mkdocs.yml, navigation, plugins, Markdown extensions, theme overrides, and build warnings.
---

# MkDocs Material

## Overview

Preserve the project's documentation conventions, verify version-sensitive
options against the selected environment, and make the smallest complete
change. Treat configuration, Markdown content, dependencies, assets, and build
commands as one system.

## Establish project context

1. Locate `mkdocs.yml` and `mkdocs.yaml` plus repository instructions,
   dependency files, Dockerfiles, CI workflows, and documentation scripts.
2. If several configs exist, resolve which site the request targets from the
   user's wording and repository evidence. Ask before editing when it remains
   ambiguous.
3. Read the chosen config for `docs_dir`, `site_dir`, `theme`, `nav`, plugins,
   Markdown extensions, assets, hooks, and overrides. Inspect the referenced
   paths rather than assuming the default layout.
4. Identify the established execution path: project virtual environment,
   package-manager command, container, or CI task. Query actual installed
   versions when behavior depends on them; a requirement declaration alone
   does not prove the active version.

## Make changes

- Use the relevant official Material for MkDocs and MkDocs pages for unfamiliar
  or version-sensitive keys. Never invent a configuration option.
- Preserve existing YAML style and entries. Keep `nav` paths, `docs_dir`,
  Markdown files, plugins, extensions, `extra_css`, `extra_javascript`, and
  `theme.custom_dir` consistent.
- Distinguish related features. For example, content tabs require
  `pymdownx.tabbed`; `content.tabs.link` only synchronizes tabs with equal
  labels. Read [configuration.md](references/configuration.md) for setup,
  content, navigation, extensions, plugins, assets, or overrides.
- Identify missing packages and the file that should declare them. Installing
  or upgrading dependencies changes the environment: do it only when the user
  requested or approved it.
- Publishing and deployment change external state. Preparing or inspecting a
  publish workflow does not authorize running it.

## Verify

Run the project's established command from the directory and environment it
expects. Start with a normal build when the baseline is unknown. Use
`mkdocs build --strict` when the project already requires strict builds or after
warnings have been classified. Separate failures introduced by the requested
change from pre-existing warnings and report both.

Use `mkdocs serve` only for local preview; it is not a production server or
deployment check. When a build fails or output differs between preview and
hosting, read [troubleshooting.md](references/troubleshooting.md).

## Quick reference

Prefer repository scripts over these generic commands.

| Intent | Local environment | Official image |
|---|---|---|
| Create in current directory | `mkdocs new .` | `docker run --rm -it -v ${PWD}:/docs squidfunk/mkdocs-material new .` |
| Preview | `mkdocs serve` | `docker run --rm -it -p 8000:8000 -v ${PWD}:/docs squidfunk/mkdocs-material` |
| Build | `mkdocs build` | `docker run --rm -it -v ${PWD}:/docs squidfunk/mkdocs-material build` |
| Treat warnings as errors | `mkdocs build --strict` | append `build --strict` to the project container command |

Use `--config-file PATH` when running outside the config directory. Adapt
volume syntax to the active shell and reuse a project Dockerfile when it adds
plugins not present in the official image.

## Common mistakes

| Mistake | Correction |
|---|---|
| Editing the first config found | Resolve the intended site and execution path first. |
| Replacing whole YAML sections | Merge the requested entry and preserve unrelated settings. |
| Adding a plugin or extension key only | Confirm its package and compatible version in the project environment. |
| Using `content.tabs.link` to enable tabs | Enable `pymdownx.tabbed`; add linking only if synchronized labels are wanted. |
| Treating every strict warning as a regression | Compare with the baseline and attribute warnings. |
| Treating `serve` as publishing validation | Build the static site and inspect the actual deployment workflow. |

## Official entry points

- [Installation](https://squidfunk.github.io/mkdocs-material/getting-started/)
- [Creating a site](https://squidfunk.github.io/mkdocs-material/creating-your-site/)
- [Material setup](https://squidfunk.github.io/mkdocs-material/setup/)
- [Customization](https://squidfunk.github.io/mkdocs-material/customization/)
- [MkDocs CLI](https://www.mkdocs.org/user-guide/cli/)
- [MkDocs configuration](https://www.mkdocs.org/user-guide/configuration/)