Add AI documentation skills
This commit is contained in:
166
.ai/skills/mkdocs/SKILL.md
Normal file
166
.ai/skills/mkdocs/SKILL.md
Normal file
@@ -0,0 +1,166 @@
|
||||
---
|
||||
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
|
||||
```
|
||||
Reference in New Issue
Block a user