167 lines
6.3 KiB
Markdown
167 lines
6.3 KiB
Markdown
---
|
|
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
|
|
```
|