introduction
mdxcn is a set of React components for documentation, drawn with text: callouts, steps, timelines, tables and small charts. Every example in these docs has three tabs. .mdx is what you write in an MDX page, .tsx is the same figure in plain React, and .md is the figure as a code block you can paste into Notion, Linear or a README.
New here? Start with installation for the CLI and the mdx-components setup. Examples are complete write-ups with two figures each, for agents covers the agent skill, and Comark and Knap render the same graphs from plain .md files.
install
The CLI copies a component into your repo. You can also copy the files from GitHub by hand.
command
components
47 total
[ content ]
Markdown you'd write anyway, framed: callouts, steps, shell sessions, release notes, code notes, decisions, chats, env files, API routes, shortcuts and FAQs.
callout
An aside between paragraphs: a caveat, a tip or a warning. The body is regular Markdown. For something another person said, use Quote.
quote
A sentence someone else said, with their name underneath. For your own caveat, use Callout.
steps
A numbered procedure. Write an ordered list, bold the current step and italicize the next one. For dated events use Timeline, and for a to-do list use Check.
terminal
A shell session. Lines starting with `$` are commands, `#` marks a comment and `✓` a passing check. Source code stays in a normal code block, and a file tree is Tree.
changelog
One release, written as a Markdown list of `added:`, `changed:`, `fixed:` and `removed:` items. For numeric before-and-after changes, use Diff.
annotatenew
Code with numbered notes. End a line in the code block with `// (1)`, then explain it in an ordered list underneath. Marked lines stay bright and the rest fade. For a shell session, use Terminal.
decisionnew
One decision with the options that were on the table. Bold the chosen option, italicize the rejected ones, and add `— why` after each. Paragraphs after the list describe what happens next. For a feature grid, use Compare.
chatnew
A conversation. Write `- you: …` and `- agent: …` lines. Your turns get a prompt glyph, italic turns are asides, and back-to-back lines from one speaker share a label. For a single remark, use Quote.
envnew
Environment variables. Paste a `.env` code block: a comment above a key describes it, and a comment that says required marks it as required. For label and value rows that aren't variables, use Spec.
endpointnew
One API route. Start with a line like `POST /v1/graphs`, then a sentence, a parameter table (a bold name means required), and request and response code blocks. To list many routes in one table, use Sheet.
keysnew
Keyboard shortcuts drawn as keycaps. Write `- ⌘K: search`, `- Ctrl+Shift+P: palette` or `- g then d: docs`. Bold the one worth learning first.
faqnew
Questions and answers. Each `### heading` is a question and the Markdown under it is the answer. Bold the question people should read first. For a procedure, use Steps.
[ diagrams ]
Paths, trees, timelines, schedules and boards, written as lists inside the tag.
flow
A process drawn along dashed arrows. Write one line per path with the steps separated by →, and bold the step you're on. For a dated list use Timeline, and for a schedule use Gantt.
request → **middleware** → handlertimeline
A dated list. Write `- Mar 18: Docs`, bold the current row and italicize the next. A `— note` or an indented paragraph appears under its row. For a to-do list use Check, and for work with start and end dates use Gantt.
tree
A nested list drawn with branch lines, good for file structures or an org chart. Bold a node to highlight it.
gantt
Overlapping work on a shared calendar. Write `- build: 0.2 0.75 0.55` for start, end and progress. For a dated log, use Timeline.
boardnew
Columns of work, like a kanban board. Each `### heading` is a column with a list underneath. Bold marks what's in progress, italics what's next, and `— note` adds a line under an item. For a to-do list use Check, and for dates use Timeline.
[ data ]
Numbers with labels: stats, specs, tables and diffs.
stat
Two to four big numbers. Write `- 12,400 docs` and bold the one that matters most. For a single number with a trend, use KPI.
spec
Aligned label and value rows. Write `- Family: Geist Mono`. Inline code and links work, and an indented paragraph appears under its value. For headline numbers use Stat, and for a table with headers use Table.
check
A to-do list. Write `- [x] freeze tokens`. Text after an em dash becomes a note under the item, and a nested list becomes sub-tasks. For dated steps use Timeline, and for columns of work use Board.
diff
What was added, removed or kept. Write `- app: +31 kb` and bold the total. `- ~~old~~ new` draws one removed line and one added line. For numbers before and after, use Slope.
kpi
One big number with a sparkline underneath. Write `12,400 this week — +18%`, then a line of numbers.
table
A framed table. Write a regular Markdown table inside the tag. For grouped sections use Sheet, and for label and value rows use Spec.
sheet
A table split into titled sections, like an API reference or an RFC. Write `### Scope` followed by a Markdown table. For a flat table, use Table.
compare
Options side by side. Write a Markdown table where `yes` and `no` become ✓ and –. For exact numbers on both axes, use Matrix.
matrix
A grid of exact numbers with labels on both axes. Write a Markdown table. For shaded intensities use Heatmap, and for yes/no features use Compare.
invoice
An invoice with sender, recipient, line items and totals. Write the line items as a Markdown table and the sender and recipient as text. For a general table, use Table.
[ charts ]
Glyphs on a track: rankings, meters, sparklines and grids.
rank
Labels ranked by a number. Write `- 12,400 /docs`. To compare two histograms side by side, use Bars.
funnel
Steps that narrow as people drop off. Write `- 12,400 docs`. For a plain ranking use Rank, and for a process use Flow.
slope
Two values per row with an arrow between them. Increases use the accent and decreases fade.
bullet
An actual value against a target on one bar. The marker shows the target.
scorenew
Ratings drawn as dots. Write `- Docs: 4/5`; halves draw a half dot. Bold the row that matters and the rest fade. For actual versus target, use Bullet.
waterfall
A running total drawn as floating bars. The first row is the starting value, the last is the result, and the signed values in between move it up or down.
stack
Parts of a whole on one bar. Write `- marketing: 48 js, 22 css, 30 images`. For a share shown as cells, use Waffle.
spark
A sparkline made of block characters, scaled to the highest value. Write `2 3 5 8 — caption` inside the tag.
plot
A line or area chart built from columns of block characters. Write a list of numbers, or `- Mon: 4` rows to keep the labels.
- Mon: 4meter
A progress bar drawn with `=` characters, with dashes for the empty part. Write `67% — of the disk` inside the tag.
waffle
A grid of 100 cells, filled to the value. Write `73% — tests green` inside the tag.
cells
A small grid of filled and empty cells. Write `- fragments: 1 0 1 0 0 / 0 1 0 1 0`. To show a share out of 100, use Waffle.
bars
Two small histograms, before and after. Write `- before: 2 4 3 5 2`. For labels ranked by value, use Rank.
heatmap
A labeled grid shaded by intensity. Write a Markdown table. For exact numbers use Matrix, and for a contribution calendar use Activity.
| | 0 | 4 | 8 | | --- | --- | --- | --- | | Mon | 0 | 1 | 4 |activity
A GitHub-style contribution grid. Pass dated counts, or write `- 2026-03-02: 0 1 4 2 0*3` and the counts fill in day by day from that date.
- 2026-03-02: 0 1 4 2 0*3 3
[ time ]
Days and clocks: uptime, a month view, elapsed time and countdowns.
uptime
One glyph per day for ok, degraded, down or no data, wrapping every 30 days. Shorthand keeps long runs short: `ok*40 down*2 ok*48`.
calendar
One month as a seven-column grid. Write `- 12: launch` to mark a day; marked days use the accent and their labels are listed under the month. Today is shown in brackets, and a bold item sets it.
- 12: launch - **18: today**timer
Time since a moment, how long ago it was, or the current time, updated every second. Write the start inside the tag: `2026-09-01T09:00Z — since deploy`.
2026-09-01T09:00Z — since deploycountdown
Time remaining until a date. Once the date passes, it shows a short label you choose. Write `2026-12-01 — until launch` inside the tag.
2026-12-01 — until launch
[ primitives ]
The frame every component is drawn in.