Writing Docs

Writing Medusa Documentation

Skill for writing and updating MDX documentation across the book, resources, ui, user-guide, and cloud projects under www/apps/.

Constraints

> CRITICAL: Violating these will corrupt the documentation or break CI.

• Never document @ignore-tagged items — any option, method, or parameter with @ignore in its TSDoc must be skipped entirely
• Never touch www/apps/resources/references/ — auto-generated, will be overwritten
• Never touch www/apps/ui/specs/components/ — auto-generated, will be overwritten
• Never touch www/apps/api-reference/ — managed by a separate process
• Never run yarn prep or yarn lint:content — these run automatically after your session
• Never invent Cloudinary screenshot URLs in user-guide — leave <!-- TODO: add screenshot --> instead

Load Reference Files When Needed

> Load at least one reference file before writing any content.

| Task | Load |

|------|------|

| Deciding if a change needs docs | reference/when-to-document.md |

| Writing any MDX content | reference/mdx-patterns.md |

| Writing for the book project | reference/book-style.md |

| Writing for the resources project | reference/resources-style.md |

| Writing for the user-guide project | reference/user-guide-style.md |

| Writing for the cloud project | reference/cloud-style.md |

| Checking prose quality | reference/vale-rules.md |

Quick Reference

Project paths and writable directories

| Project | Content path | Sidebar file |

|---------|-------------|--------------|

| book | www/apps/book/app/ | www/apps/book/sidebar.mjs |

| resources | www/apps/resources/app/ | www/apps/resources/sidebars/*.mjs |

| ui | www/apps/ui/app/, www/apps/ui/specs/examples/ | www/apps/ui/sidebar.mjs |

| user-guide | www/apps/user-guide/app/ | www/apps/user-guide/sidebar.mjs |

| cloud | www/apps/cloud/app/ | www/apps/cloud/sidebar.mjs |

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