skills.rest
DeepSpaceCartel
DeepSpaceCartelOFFICIAL
Explore all skills by this author →
WebsiteGitHub

mkdocs

Builds and verifies documentation sites with MkDocs and Material for MkDocs.

Updated Sep 9, 2026
Search Tags:#documentation#markdown#technical writing#static site#mkdocs#ci verification#material for mkdocs
One-click install
npx skills add https://github.com/DeepSpaceCartel/skills --skill mkdocs-deepspacecartel
Or copy as Structured Prompt for Agent▼
Please help me install this Agent Skill.
Skill: mkdocs
Source: https://github.com/DeepSpaceCartel/skills/tree/main/skills/mkdocs
Command: npx skills add https://github.com/DeepSpaceCartel/skills --skill mkdocs-deepspacecartel

SYSTEM DOCUMENTATION & REQUIREMENTS

💡 This Skill requires mkdocs, mkdocs-material, and includes references (resource) components.

What problem does it solve? Documentation sites rot when they state things that are no longer true, and broken links or stale examples quietly erode reader trust. This Skill provides the structure, writing principles, and verification discipline needed to build a MkDocs site that stays accurate and navigable. ## Core Features & Use Cases - Site Structure & Navigation: Organize pages by reader questions (concepts, reference, project) with folder layout and nav mirroring each other, plus deliberate mkdocs.yml settings and pinned theme versions. - Material Components: Use tabs, admonitions, grid cards, abbreviations, mermaid diagrams, and code annotations to match the shape of content to the right visual component. - Strict-Build Verification: Run mkdocs build --strict locally and in CI to catch broken internal links and heading anchors before readers do. - Use Case: When restructuring an existing docs site, apply the audience-based grouping, rewrite the landing page as a real quick start, and wire a strict-build check into CI so every PR touching docs is validated automatically. ## Quick Start Use the mkdocs skill to create a new documentation site structure with Material theme components and a strict-build CI check.

Frequently Asked Questions about mkdocs

High-intent search queries and answers about installing and using this skill.

FAQPage Schema
How do I build a documentation site with MkDocs and Material?▼

Create a docs/ folder with an index.md landing page, group pages by reader questions (concepts, reference, project), and mirror that grouping in the nav section of mkdocs.yml. Pin mkdocs and mkdocs-material versions in requirements.txt, then verify with mkdocs build --strict.

How to catch broken links in MkDocs before publishing?▼

Run mkdocs build --strict, which turns warnings about broken internal links and missing heading anchors into a nonzero exit code. Run it after renaming headings or moving files, and wire it into CI so every PR touching docs is validated automatically.

What Material for MkDocs components should I use for warnings and variants?▼

Use admonitions (!!! warning, !!! danger) so warnings look like warnings, tabs for variant forms of the same concept, grid cards for landing-page navigation, and mermaid fenced blocks for editable diagrams. Each requires enabling the matching markdown extension in mkdocs.yml.

Does mkdocs build --strict catch pages missing from nav?▼

No, pages that exist but are not in nav produce only an INFO-level message, not an error. This is deliberate, allowing clearly-labeled non-public content to stay in the repo unpublished; check each such page is intentional rather than chasing the count to zero.

Why do MkDocs links break after renaming a heading?▼

Heading anchors are auto-generated by lowercasing, replacing spaces with hyphens, and stripping punctuation, so renaming a heading changes its anchor and silently breaks every inbound link. Running mkdocs build --strict after any heading rename catches these failures at build time.

Related Skills

Explore More Software Engineering Skills→
wunkiwunki
19

tech-docs-writer

Generate README files, API documentation, and architecture guides from codebases.

Community
Intermediate
brainbrewlabsbrainbrewlabs
7

doc-publishing

Publishes documentation to GitHub Pages, Vercel, or Netlify from source docs and build outputs.

Official
Intermediate
christopher-busschristopher-buss
6

diataxis

Classify, audit, generate, and restructure documentation into Diátaxis quadrants.

Community
Advanced
SayBGMSayBGM

moai-docs-generation

Generate technical documentation from source code and API definitions.

Community
Advanced