Writing Docs

Load Reference Files When Needed

Load at least one reference file before writing any content.

Quick Reference

Project paths and writable directories

MDX file minimum structure

export const metadata = {
  title: `Page Title`,
}

# {metadata.title}

Content here.

For book pages that use chapter numbering, the title uses ${pageNumber}:

export const metadata = {
  title: `${pageNumber} Chapter Title`,
}

Cross-project links

[text](!docs!/learn/path)        → book
[text](!resources!/path)         → resources
[text](!user-guide!/path)        → user-guide

Common Mistakes

• Adding a new option, method, or parameter without a version note
• Documenting any option, method, or parameter tagged with @ignore in its TSDoc — skip these entirely
• Touching references/ or specs/components/ directories
• Using we, us, let's, our in prose (use "you" or imperative)
• Using "Medusa API" to mean the backend — use "Medusa backend" instead
• Writing "Medusa Cloud" — use "Medusa" (noun form) or "Cloud" (location/service)
• Using e.g., — write for example instead
• Using em dashes (—) — rewrite sentence to avoid them
• Using passive voice ("is created", "can be configured") — write active ("you can configure", "call X to create")
• Writing code lines longer than 64 characters
• Forgetting to add a new page to the sidebar file
• Removing ${pageNumber} from book page titles
• Using <img> or bare HTML instead of MDX components
• Documenting internal implementation details (only public APIs)

Reference Files

reference/when-to-document.md   - Decision tree: does this change need docs?
reference/mdx-patterns.md       - MDX syntax, code blocks, components
reference/book-style.md         - book-specific structure and conventions
reference/resources-style.md    - resources-specific structure and conventions
reference/user-guide-style.md   - user-guide writing style and conventions
reference/cloud-style.md        - cloud-specific structure and conventions
reference/vale-rules.md         - Vale + lint rules to follow in prose