cmba-bylaws/.ai/skills/mkdocs/SKILL.md

name, description

name	description
mkdocs	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:

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:

mkdocs build --strict
mkdocs serve

For large sites, consider:

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:

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