skills.rest
castacks
castacksOFFICIAL
Explore all skills by this author →
Website𝕏@airlabcmuGitHub

write-mkdocs-documentation

Automate frontmatter-driven MkDocs documentation drafting and governance for AirStack projects.

84|28|Updated Jun 7, 2024
Search Tags:#documentation#markdown#navigation#quality#visualization#mkdocs
One-click install
npx skills add https://github.com/castacks/AirStack --skill write-mkdocs-documentation
Or copy as Structured Prompt for Agent▼
Please help me install this Agent Skill.
Skill: write-mkdocs-documentation
Source: https://github.com/castacks/AirStack/tree/main/.agents/skills/write-mkdocs-documentation
Command: npx skills add https://github.com/castacks/AirStack --skill write-mkdocs-documentation

SYSTEM DOCUMENTATION & REQUIREMENTS

What problem does it solve?

Guides teams to create, organize, and maintain AirStack MkDocs documentation by providing a structured approach, frontmatter-driven entry points, and standardized formatting that reduces confusion and ensures quality.

Core Features & Use Cases

  • Progressive Disclosure: structure docs so newcomers see what matters first and link to deeper material, with clear Learn more patterns.
  • Concise Yet Complete: keep pages focused, avoid duplication, and make each section independently scannable.
  • Visual Learning: encourage diagrams with Mermaid, reference tables, code examples, and contextual admonitions to improve comprehension.
  • MkDocs-Specific Rules: enforce blank lines before lists, navigation conventions, and consistent usage of module vs system docs.
  • Documentation Structure Guidance: distinguish module-level READMEs from system docs and outline recommended organization (module docs under module paths; system docs under docs/).

Quick Start

Write or update MkDocs pages following the provided module-system guidelines, verify formatting, and validate navigation and rendering.

Frequently Asked Questions about write-mkdocs-documentation

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

FAQPage Schema
How do I structure MkDocs documentation for large projects with multiple modules?▼

Structure MkDocs documentation by separating module-level docs under their specific module paths and system-level docs under the root docs directory. This organization maintains clear navigation and prevents documentation duplication across large project sets.

What is progressive disclosure in MkDocs documentation and how does it work?▼

Progressive disclosure in MkDocs documentation structures pages so newcomers see the most important information first, using clear Learn more patterns to link deeper material. It keeps pages concise yet complete while making each section independently scannable.

How do I add diagrams and visual elements to MkDocs markdown files?▼

Add diagrams to MkDocs markdown files using Mermaid syntax for visual learning. Combine these diagrams with reference tables, code examples, and contextual admonitions to improve reader comprehension and maintain consistent visual guidance.

Does MkDocs require blank lines before lists and specific frontmatter formatting?▼

MkDocs requires blank lines before lists to ensure proper rendering. Frontmatter-driven entry points must follow standardized formatting conventions to enforce documentation quality checks and maintain consistent navigation across all pages.

What is the best way to enforce consistent formatting across a large MkDocs documentation set?▼

Enforce consistent MkDocs formatting by applying structured frontmatter rules, standardized navigation conventions, and quality checks. Distinguish module-level READMEs from system docs to maintain high-quality, independently scannable documentation pages.

Why does my MkDocs navigation display incorrectly when mixing module and system level documentation?▼

MkDocs navigation displays incorrectly when module and system level documentation paths are mixed. Place module docs under their specific module paths and system docs under the root docs directory to enforce proper navigation conventions and rendering.

Related Skills

Explore More Content & Communication Skills→
C0ntr0lledCha0sC0ntr0lledCha0s
3

managing-docs

Automate project documentation structure and governance with configurable tooling.

Community
Advanced
safeai-aussafeai-aus
6

Site Review

Audit Zensical site builds, links, headings, assets, and SEO metadata.

Community
Advanced
cgm-freecgm-free

mermaid

Parse and render Mermaid diagrams within Markdown code blocks.

Community
Advanced
soo-kate-yeonsoo-kate-yeon

moai-docs-generation

Generate API documentation from source code and OpenAPI specifications.

Community
Advanced