---
name: mkdocs
description: "Use when creating, configuring, debugging, or customizing MkDocs sites pinned to MkDocs 1.6.1 with Material for MkDocs 9.7.1, including mkdocs.yml, nav, Markdown authoring, theme overrides, plugins, search, deployment, and version-safe upgrades."
---

# MkDocs

## When to use

Use this skill for work on documentation sites that use:

- `mkdocs==1.6.1`
- `mkdocs-material==9.7.1`

Typical tasks:

- create or restructure a docs site
- update `mkdocs.yml`
- fix navigation, links, assets, or Markdown rendering
- enable or tune Material features, plugins, and extensions
- add CSS/JS overrides or theme template overrides
- prepare deployment for GitHub Pages or another static host

## Version guardrails

- Treat `MkDocs 1.6.1` and `Material for MkDocs 9.7.1` as fixed unless the user explicitly asks to upgrade.
- Keep recommendations compatible with those versions.
- If a repo is missing pinned versions, prefer adding explicit pins rather than floating latest versions.

## Procedure

### 1) Inspect the current site shape first

Check:

- `mkdocs.yml`
- `docs/`
- dependency files such as `requirements.txt`, `pyproject.toml`, `uv.lock`, or `poetry.lock`
- any `overrides/`, `docs/stylesheets/`, `docs/javascripts/`, or CI deploy workflow

### 2) Start from the canonical baseline

Prefer this baseline unless the existing site already has an intentional alternative:

```yaml
site_name: Example Docs
site_url: https://example.com/docs/
theme:
  name: material
```

Recommendations drawn from the versioned docs:

- Always set `site_url`. Material relies on it for several features, and MkDocs uses it for canonical URLs and path-aware local serving.
- Prefer an explicit `nav` for stable ordering once a site has more than a few pages.
- Keep internal links relative between Markdown files. Avoid absolute doc links.
- Put static assets under `docs/` so MkDocs copies them through unchanged.
- Keep `site/` out of version control.

### 3) Author content the MkDocs way

- Use `index.md` for section landing pages. `README.md` is also supported for index pages, but do not keep both `index.md` and `README.md` in the same directory.
- Prefer shallow, readable navigation over deep nesting.
- If pages are intentionally hidden from global navigation, remember they still build and must still have valid links.
- When fixing broken anchors, verify the generated heading slug rather than guessing.

Primary references:

- `references/upstream/mkdocs-1.6.1-docs/user-guide/writing-your-docs.md`
- `references/upstream/mkdocs-1.6.1-docs/user-guide/configuration.md`

### 4) Customize Material with the lowest-friction tool first

Choose the least invasive option that solves the task:

1. small visual tweaks: `extra_css` and `extra_javascript` under `docs/`
2. theme HTML changes: `theme.custom_dir: overrides`
3. template changes: prefer block overrides with `main.html` and `{{ super() }}` over copying full templates

Recommendations:

- Prefer `docs/stylesheets/extra.css` and `docs/javascripts/extra.js` for minor changes.
- For HTML customization, install Material via package name and set `theme.name: material`; do not fork the theme when `custom_dir` will do.
- When overriding templates, prefer extending `base.html` or overriding blocks instead of replacing whole partials.
- If custom JavaScript must run after client-side navigation, attach it via Material's `document$` observable.

Primary references:

- `references/upstream/mkdocs-material-9.7.1-docs/customization.md`
- `references/upstream/mkdocs-1.6.1-docs/user-guide/customizing-your-theme.md`
- `references/upstream/mkdocs-material-9.7.1-docs/setup/`

### 5) Use Material features intentionally

- Keep `theme.name: material` unless the repo deliberately uses another theme.
- Add only the features actually needed; avoid turning on large feature sets blindly.
- For search, analytics, navigation, blog, tags, privacy, social cards, and versioning, consult the matching Material setup/plugin page before editing config.
- If editing `mkdocs.yml` directly is error-prone, use Material's schema support in the editor.

Primary references:

- `references/upstream/mkdocs-material-9.7.1-docs/creating-your-site.md`
- `references/upstream/mkdocs-material-9.7.1-schema.json`
- `references/upstream/mkdocs-material-9.7.1-docs/setup/`
- `references/upstream/mkdocs-material-9.7.1-docs/plugins/`
- `references/upstream/mkdocs-material-9.7.1-docs/reference/`

### 6) Validate before deployment

Default verification flow:

```bash
mkdocs build --strict
mkdocs serve
```

For large sites, consider:

```bash
mkdocs serve --dirtyreload
```

Deployment guardrails:

- Review the local build before `mkdocs gh-deploy`.
- Do not run `mkdocs gh-deploy` from a dirty working tree unless the deployed output is meant to include those changes.
- For GitHub Pages custom domains, keep `CNAME` in `docs/`.
- For offline or `file://` output, set `site_url: ""`, set `use_directory_urls: false`, and do not rely on the default search plugin.

Primary references:

- `references/upstream/mkdocs-1.6.1-docs/user-guide/deploying-your-docs.md`
- `references/upstream/mkdocs-1.6.1-docs/user-guide/cli.md`
- `references/upstream/mkdocs-material-9.7.1-docs/publishing-your-site.md`
- `references/upstream/mkdocs-material-9.7.1-docs/setup/building-for-offline-usage.md`

## Reference map

Open only the specific files needed:

- core MkDocs usage:
  `references/upstream/mkdocs-1.6.1-docs/getting-started.md`
- config:
  `references/upstream/mkdocs-1.6.1-docs/user-guide/configuration.md`
- authoring and links:
  `references/upstream/mkdocs-1.6.1-docs/user-guide/writing-your-docs.md`
- deployment:
  `references/upstream/mkdocs-1.6.1-docs/user-guide/deploying-your-docs.md`
- Material bootstrap:
  `references/upstream/mkdocs-material-9.7.1-docs/getting-started.md`
- Material site setup:
  `references/upstream/mkdocs-material-9.7.1-docs/creating-your-site.md`
- Material customization:
  `references/upstream/mkdocs-material-9.7.1-docs/customization.md`
- Material setup pages:
  `references/upstream/mkdocs-material-9.7.1-docs/setup/`
- Material plugin pages:
  `references/upstream/mkdocs-material-9.7.1-docs/plugins/`
- Material writing features:
  `references/upstream/mkdocs-material-9.7.1-docs/reference/`

For quick discovery inside the bundled docs:

```bash
rg -n "^#|^##" references/upstream/mkdocs-1.6.1-docs references/upstream/mkdocs-material-9.7.1-docs
```