Content Patterns
Opinionated MDX patterns for building pages that make the docs shell feel complete.
Sparse pages make even a good docs framework feel unfinished. The fastest way to make the portal feel more like the Fumadocs reference is to author pages that actually use the reading system well.
Use multiple content shapes on a page
Good docs pages should mix:
- short explanatory prose
- cards for navigation
- steps for ordered flows
- tabs for compact comparison
- callouts for important framing
- accordions for secondary detail
Start with scanning surfaces
Shortcuts
Use cards when readers need clear next moves.
Compare Options
Use tabs for platform, role, or workflow comparisons.
Sequence Work
Use steps when order matters and readers should not guess.
Keep the TOC alive
The sticky TOC only shines when a page has enough heading depth to follow. Aim for a rhythm like this:
Open with context
Explain what the page is for in one or two paragraphs so a reader can decide whether to stay.
Break the rest into decision-sized sections
Use ## and ### headings to split the page into chunks that a reviewer can scan from the right rail.
End with next actions
Give the reader obvious places to continue, such as visual theming or preview environments.
Show, then explain
A wall of plain bullets explains the feature, but it does not prove the docs shell can carry richer documentation.
Prose mixed with cards and callouts gives the page shape, but still may not demonstrate sequence or comparison well.
Combine cards, steps, tabs, and accordions on pages where they match the content model. The shell feels much more complete because readers can move through several interaction types without leaving the docs.
Recommended writing habits
| Habit | Why it helps |
|---|---|
| Use precise section titles | Better sidebar and TOC scanning |
| Add explicit next-page links | Stronger pathing through the docs tree |
| Prefer examples over abstract claims | Makes the product feel more real |
| Keep each page opinionated | Readers trust pages that make a call |