docusaurus-conventions

Docusaurus builds often fail due to incorrect file naming, invalid MDX syntax, duplicate frontmatter IDs, or broken internal links. Applying strict content authoring conventions ensures deterministic routing and a clean build output.

To fix MDX syntax issues, avoid problematic characters and do not use Mermaid diagrams in your MDX files. Following documented MDX safety rules and recovery patterns resolves common build errors and improves author productivity.

Use README.md for module index files and NN-descriptive-name.md for lessons to ensure deterministic routing and ordering. Strict naming patterns prevent routing conflicts and help your documentation build reliably.

Docusaurus does not safely support Mermaid diagrams in MDX files under these conventions. To ensure build stability, avoid problematic characters and Mermaid, relying instead on standard non-Mermaid diagram usage.

Resolve duplicate frontmatter ID errors by enforcing frontmatter structure and ID uniqueness across modules and lessons. Documented recovery patterns provide debugging steps to fix these common build errors quickly.