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:
"Local Markdown Dev" provides the infrastructure for Fumadocs to handle local Markdown and MDX content, including storage management, compilation pipelines, and a development-time hot-reloading mechanism. By bridging raw filesystem content with the documentation framework, it allows for efficient content scanning, caching, and dynamic revalidation during development.
The subsystem is architected around a central storage engine that manages file parsing and invalidation. It exposes interfaces for both static and dynamic sources, enabling developers to integrate filesystem-based documentation into their sites seamlessly. It maintains a robust separation of concerns between raw content parsing, Markdown compilation (using remark and rehype), and runtime execution of code embedded within documentation files.
In addition to core compilation, this component introduces a WebSocket-based development server. This server facilitates communication between the filesystem and the client, ensuring that any modifications to source files automatically trigger UI refreshes via router.refresh(). This architecture addresses the latency and manual re-run overhead typical in documentation development, offering a high-performance experience that remains compatible with modern JavaScript environments.
The storage layer handles the discovery and parsing of local documentation files. It interacts with the filesystem via glob patterns to create a representation of pages and metadata, providing an invalidation mechanism that is crucial for the dev-server functionality.
// Accessing file storage and invalidation
const storage = createStorage(config);
// ... later, triggered by watcher events:
storage.invalidateCache(absolutePath);The compilation system is modular, supporting different configurations for standard Markdown and MDX. It utilizes remark and rehype plugin architectures to process documents into AST or JS outputs.
Important
The compiler handles MDX files by generating JS functions, while standard Markdown files are processed into HAST trees for efficient execution.
For Markdown files that require executing code (e.g., dynamic components), the subsystem includes a virtual JS engine (executorVirtual). This is an implementation of estree-util-build-jsx logic that evaluates AST nodes within a controlled context, bypassing the need for a full Node.js vm module, which is beneficial for edge-runtime compatibility.
Sources: packages/local-md/src/eval-estree-expression/index.ts:82-837, packages/local-md/src/js/executor-virtual.ts:7-21
The dev server uses chokidar to observe filesystem changes. When a file is modified, it broadcasts a WebSocket event to the connected clients. The client-side DevClient receives these events and calls router.refresh() to update the page view in real-time.
Sources: packages/local-md/src/dev/node-server.ts:33-163, packages/local-md/src/dev/react-client.ts:6-40
Sources: packages/local-md/src/eval-estree-expression/index.ts:2-4, packages/local-md/src/index.ts:92, packages/local-md/src/dev/node-server.ts:58-62