unfold-mdx
Progressive-depth prose & code explanations for React and MDX. Diffs consecutive snapshots at sentence & line/token levels with zero accordions or scroll jumps.
The Origin & Problem
Technical tutorials and documentation platforms face a constant compromise: how to address both beginners and advanced developers in the same explanation. Traditional tools solve this with accordion panels, tab switches, or separate pages, all of which break focus, cause scroll jumps, and isolate content.
unfold-mdx is a headless React framework that enables inline progressive disclosure of text and code. By arranging multiple "depth levels" within a single container, the reader can drill down into a concepts details step-by-step.
Rather than simple hiding or revealing, the engine dynamically performs sentence-level prose diffing and line-and-token-level code diffing using custom tokenization algorithms. Added, updated, or deleted segments are subtly highlighted with customizable styling, creating an intuitive flow of modifications.
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
Technical Deep Dive
Sentence Prose Diffing
Instead of diffing by character or word, which creates distracting fragments, `unfold-mdx` tokenizes prose by sentence. It runs Google's `diff-match-patch` across these sentence arrays, pinpointing exactly where items are added or modified, and mapping them to visual states with data-attributes.
Line & Token Code Diffing
For code codeblocks, the library computes line-by-line additions and updates. If a line is modified, it runs a secondary character diff to generate token spans for added text inline. This avoids drawing full block insertions for single-character edits.
Asynchronous Shiki Coloring
Syntax coloring uses Shiki's highlighter engine. Because Shiki is heavy and loads grammars asynchronously, the library falls back to uncolored raw diff markup instantly on hydration, then swap colors once loaded without layout jumps.
SSR & No-JS Graceful Fallback
To satisfy SEO indexing requirements, all code snapshots and text levels are compiled into the server-rendered HTML payload. The deepest level is shown by default. Once client JS loads, active visibility switches over and hydrates into the interactive control deck.
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>