MTUCI-RAG-Example/support_files/codex_files/skills/mkdocs-material/SKILL.md

name, description

name	description
mkdocs-material	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 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.

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
• Creating a site
• Material setup
• Customization
• MkDocs CLI
• MkDocs configuration