unfold-mdx
A React & MDX library for progressive technical explanations. Highlights changes sentence by sentence and token by token as readers drill deeper.
The Origin & Problem
Writing technical docs is hard because readers have different backgrounds. Beginners need context, while experienced devs just want the core details. Standard fixes like accordions, tabs, or separate pages break reading flow and cause jarring scroll jumps.
I created unfold-mdx to solve this with progressive disclosure. You write your explanation in increasing levels of depth, and readers step through at their own pace.
Instead of hiding and showing big chunks of text, the library diffs each level sentence by sentence and code token by token. Readers see exactly what changed as the concept unfolds.
Specs & Info
- Published package:@unfold-mdx/react
- NPM Keywords:mdx, headless, diff
- Main Tech:React, Shiki, DiffMatchPatch
- License:MIT
Live Interactive Demonstration
Step through the progressive disclosure explanation of a react side-effect below
How It Works Under the Hood
Sentence Prose Diffing
Diffing prose character-by-character creates ugly, choppy highlights. unfold-mdx splits text into full sentences first, runs diff-match-patch on them, and highlights new or modified sentences cleanly.
Line & Token Code Diffing
For code snippets, it finds changed lines first. If only a variable name or small argument changed inside a line, it diffs individual tokens so you don't get giant green blocks for a one-word tweak.
Asynchronous Shiki Coloring
Shiki produces great syntax highlighting, but loading language grammars takes time. unfold-mdx renders unhighlighted diffs instantly on load, then applies syntax colors as soon as Shiki finishes without causing layout shifts.
SSR & No-JS Graceful Fallback
Search engines need to read the full text. All depth levels render in the initial server HTML, defaulting to the complete explanation. Once JavaScript loads, the interactive step controls take over.
Usage & Code Sample
import { Depth, DepthLevel, DepthCode } from "@unfold-mdx/react";
import "@unfold-mdx/react/theme.css";
<Depth show="both" orientation="horizontal" ratio={0.5} indicators={true}>
<DepthLevel label="Basic">
Fission splits a heavy atom into two lighter ones.
</DepthLevel>
<DepthCode lang="js">
```js
const status = "splitting";
```
</DepthCode>
<DepthLevel label="Triggered">
Fission splits a heavy atom into two lighter ones.
The split is triggered by a neutron striking the nucleus.
</DepthLevel>
<DepthCode lang="js">
```js
const status = "splitting";
const trigger = "neutron";
```
</DepthCode>
</Depth>