Docusaurus Conventions Skill

Persona

Think like a Docusaurus expert who ensures all content builds successfully on the first attempt. You understand the quirks of MDX parsing, file naming conventions, and how Docusaurus resolves document IDs.

Pre-Flight Questions

Before creating or modifying any Docusaurus content, ask yourself:

1. File Naming

• Q: What file extension should I use?

  • A: Always .md (NOT .mdx)
  • Why: The project doesn't use MDX components; .mdx causes unnecessary complexity

• Q: What should chapter/module index files be named?

  • A: Always README.md (NOT index.md)
  • Why: Docusaurus resolves README.md as the index; index.md can cause duplicate ID errors

• Q: What naming pattern for lesson files?

  • A: NN-descriptive-name.md (e.g., 01-digital-to-physical.md)
  • Why: Numeric prefix ensures correct ordering; descriptive name aids navigation

2. MDX Syntax Safety

• Q: Does my content contain < characters outside of code blocks?

  • A: Replace with spelled-out alternatives
  • Examples:
    • <2 seconds → less than 2 seconds
    • <10 hours → under 10 hours
    • [<10 hrs → [under 10 hrs
  • Why: MDX parser interprets < as JSX tag start, causing build errors

• Q: Am I using comparison operators in prose?

  • A: Use words instead of symbols
  • Examples:
    • latency < 100ms → latency under 100ms or use inline code: latency < 100ms
    • if (x < 5) in code block is fine (code blocks are not parsed as MDX)

3. Diagrams

• Q: Am I using Mermaid diagrams?

  • A: NO - Mermaid plugin is not configured

  • Alternatives:

    • ASCII text diagrams for simple flows
    • Image files for complex diagrams
    • Code blocks showing structure

  • Example replacement:

    # Instead of mermaid:
    ```mermaid
    graph TD
      A --> B
    

    Use ASCII:

    A → B → C
    └── D
    

4. Internal Links

• Q: How should I link to other lessons?
  • A: Use relative paths with .md extension
  • Examples:
    • Same chapter: [Next](./02-next-lesson.md)
    • Different chapter: [Overview](../chapter-2-topic/README.md)
    • Module root: [Module](../README.md)
  • Never use: .mdx extension or index.md

Principles

Principle 1: Build-First Validation

Before committing any content, verify it builds.

npm run build 2>&1 | tail -30

Expected: [SUCCESS] Generated static files in "build"

If errors:

1. Check for duplicate doc IDs (two files with same id frontmatter)
2. Check for MDX syntax errors (unexpected character errors)
3. Check for broken links (file not found warnings)

Principle 2: Consistent File Structure

Module structure:

docs/module-N-name/
├── README.md                    # Module overview (NOT index.md)
├── chapter-1-topic/
│   ├── README.md                # Chapter overview
│   ├── 01-first-lesson.md
│   ├── 02-second-lesson.md
│   └── ...
├── chapter-2-topic/
│   └── ...
└── ...

Principle 3: Frontmatter ID Uniqueness

Every lesson must have unique id:

---
id: lesson-1-1-digital-to-physical   # Unique across entire docs folder
title: "Lesson 1.1: From ChatGPT to Walking Robots"
---

ID pattern: lesson-{chapter}-{lesson}-{slug}

• lesson-1-1-digital-to-physical
• lesson-3-2-turtlesim-action
• custom-messages (for standalone topics)

Principle 4: Safe Text Patterns

Avoid these patterns in prose (outside code blocks):

Safe in code blocks:

if x < 5:  # This is fine - inside code block
    pass

Checklist (Use Before Every Lesson Creation)

• File extension is .md (not .mdx)
• Index files named README.md (not index.md)
• Unique id in frontmatter
• No < or > in prose outside code blocks
• No Mermaid diagrams (use ASCII or images)
• Internal links use .md extension
• Internal links use README.md not index.md
• Build passes: npm run build

Recovery Patterns

Fix: Duplicate Doc ID Error

Error: The docs plugin found docs sharing the same id

Solution:

1. Delete one of the duplicate files
2. Or change the id in frontmatter to be unique

Fix: MDX Syntax Error

Unexpected character 'N' (U+004E) before name

Solution:

1. Find the < character in prose
2. Replace with word equivalent (less than, under)
3. Or wrap in inline code

Fix: Mermaid Not Rendering

Solution:

1. Replace mermaid block with ASCII text diagram
2. Or create image and reference it

Version History