chapter-analyzer
Validates and analyzes Docusaurus MDX chapters for structure, pedagogical quality, and component usage.
When & Why to Use This Skill
The Chapter Analyzer is a specialized tool designed to validate and optimize Docusaurus MDX chapters for high-quality technical documentation. It ensures structural integrity through YAML frontmatter checks, enforces pedagogical standards for educational content, and verifies the correct implementation of interactive components like quizzes and simulations. This skill streamlines the technical writing process by maintaining consistent tone, accessibility, and professional formatting across documentation projects.
Use Cases
- Automated Documentation Audits: Scan Docusaurus directories to ensure every MDX file meets structural requirements and follows SEO-friendly heading hierarchies.
- Educational Quality Assurance: Verify that technical tutorials include essential pedagogical elements such as learning objectives, interactive knowledge checks, and concise summaries.
- Component Validation: Detect and fix errors in custom MDX components, including quizzes, simulations, and multi-language code blocks, before deployment.
- Style and Tone Consistency: Maintain a professional yet accessible 'we-centric' voice across large-scale technical textbooks and documentation sites.
| name | Chapter Analyzer |
|---|---|
| description | Validates and analyzes Docusaurus MDX chapters for structure, pedagogical quality, and component usage. |
Chapter Analyzer Logic
Target Directory
- Location:
textbook/docs/ - Format: MDX (
.mdxor.md)
Structural Validation
Every chapter must have valid YAML frontmatter:
---
id: my-chapter-id
title: My Chapter Title
sidebar_label: Sidebar Label
description: Brief summary of the chapter.
---
Content Rules
- Heading Hierarchy:
- The Docusaurus title acts as H1.
- Start content with H2 (
##). - Do not use H1 (
#) within the body.
- Pedagogical Flow:
- Introduction: Hook the reader.
- Learning Objectives: Bullet points on what will be learned.
- Core Content: Explained with text + diagrams/code.
- Interactive Element: At least one Quiz or Simulation per major section.
- Summary: Recap key points.
Interactive Components
We use custom components in MDX:
<Quiz questions={[...]} />: For knowledge checks.<Simulation type="ros2-node" ... />: For embedded simulations.<Tabs>/<TabItem>: For multi-language code blocks (Python/C++).
Tone Check
- Voice: Encouraging, Authoritative but Accessible.
- Perspective: "We will learn", "Let's explore".
- Clarity: Avoid jargon without explanation.