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  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