SpecsModelExplore
MDX Basics
MDX Basics

Write specifications using Markdown plus MDX components.

Specs are written in MDX: standard Markdown for structure, plus components for richer blocks like callouts, tabs, steps, and live model embeds. Lead with Markdown and reach for components only when they improve comprehension.

Markdown first

Use familiar Markdown for the bulk of a page:

## Context

The billing service charges tenants monthly. It depends on the
[subscription service](../modeling/explore) for plan data.

- Idempotent charges
- Retries with backoff

Images on the page

Put screenshots in _attachments/ next to the page (./_attachments/file.png). They commit with the spec, reset with the branch, and survive git-sync. Do not append ?version= to the URL.

Reference syntax

For the full Markdown rules (headings, tables, code blocks, escaping, and what is not supported), see the Markdown reference.

Add components where they help

GoalComponent
Highlight a warning or noteCallout
Show alternativesTabs
Communicate a procedureSteps
Link to related pagesCards / Card
Embed model contextObjects, Workflow, Artifact

Example:

<Callout type="warning" title="Breaking change">
  Rotate service tokens before enabling strict validation.
</Callout>

<Steps>
### Validate
Run checks locally and in CI.

### Publish

Release the spec and changelog together.

</Steps>

Use real component props

Each component has a specific prop API. For example, tabs use <Tab value="...">, not title. See the MDX Components reference for exact props.

Good practices

Capture intent

Write requirements and decisions before styling.

Keep blocks purposeful

Use a component because it clarifies, not for decoration.

Embed instead of copy

Reference the live model rather than pasting a static diagram.

If a heading and a list communicate clearly, prefer that over a custom block. Restraint keeps specs scannable.

Last updated on