Orientation
Content Processing
Search Infrastructure
Rendering and UI
Developer Tooling
How It Works
The following files were used as context for generating this wiki page:
Syntax Highlighting in this system is powered by Shiki, leveraging its high-performance tokenization capabilities to provide semantic code highlighting within MDX and React components. The system is designed to operate both as a static build-time transformation—converting code blocks into HTML structures during MDX compilation—and as a dynamic runtime client-side service for specialized components.
By decoupling the highlighter instance from the UI, the architecture allows for flexible theme management and on-demand language loading. The system handles the complexities of metadata parsing, line numbering, and icon injection through a pipeline of rehype plugins, ensuring that code blocks are rendered with proper styling, accessibility, and interactivity.
The system addresses the challenge of large bundle sizes by employing lazy-loading for languages and themes. When an unknown language or theme is requested, the system attempts to resolve and load it asynchronously. This ensures the initial bundle remains small while keeping the documentation flexible enough to support a vast array of programming languages and design tokens.
The syntax highlighting system operates as a multi-stage pipeline, primarily integrated through rehype. During the build, the rehype-code plugin detects code nodes, parses meta-strings for configuration, and transforms them into syntax-highlighted HAST (HTML Abstract Syntax Tree) structures.
Sources: packages/core/src/mdx-plugins/rehype-code.ts:19-34, packages/core/src/mdx-plugins/rehype-code.core.ts:82-142
The ShikiFactory provides a mechanism for initializing and accessing the highlighter instance. It ensures that expensive initialization only occurs once, supporting lazy-loading of engines (either js or oniguruma via WASM).
Tip
The getOrInit method ensures that the highlighter instance is reused across the entire application lifecycle, preventing redundant loading of the heavy tokenization engine.
Meta strings inside code blocks (e.g., ts {1,3} title="example.ts") are processed by custom parsers. The core logic extracts data attributes like titles, line numbers, and custom metadata, transforming them into a structured data object used by the Shiki pipeline.
The parseMetaString function allows users to define custom transformations. For example, lineNumbers=5 is stripped from the meta string and converted into the data-line-numbers-start attribute.
For interactive or documentation-heavy UI components (like API Docs or OpenApi), the system uses dynamic highlighting at runtime. This avoids shipping large bundles to the browser while maintaining high-fidelity code display.
Sources: packages/core/src/highlight/shiki/react.ts:27-59, packages/base-ui/src/components/dynamic-codeblock.core.tsx:45-67
To keep the system performant, utils.ts contains logic to check if languages and themes are already registered in the current HighlighterCore instance. If a language or theme is requested but not present, the loadMissingLanguage and loadMissingTheme helpers are triggered to fetch them asynchronously before execution.
Shiki transformers are used to manipulate the AST before serialization. The system includes pre-defined transformers for notation diffing, focus, and word highlighting, along with custom extensions like icon injection.
Warning
Transformers are executed sequentially. The order in which they are added to the transformers array is critical, especially when modifying node structures.
To implement a syntax-highlighted code block in a React component, use the DynamicCodeBlock provided by the base UI package:
import { DynamicCodeBlock } from 'fumadocs-ui/components/dynamic-codeblock.core';
import { getHighlighter } from 'fumadocs-core/highlight';
export default function MyPage() {
return (
<DynamicCodeBlock
highlighter={() => getHighlighter('js')}
lang="typescript"
code="const greeting: string = 'Hello World';"
options={{ theme: { light: 'github-light', dark: 'github-dark' } }}
/>
);
}