Local Markdown Dev

Last updated Jul 2, 2026

Relevant source files

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.

Storage and File Management

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);

Sources: packages/local-md/src/storage.ts:25-140, packages/local-md/src/index.ts:171

Markdown Compilation Pipeline

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.

Sources: packages/local-md/src/md/compiler.ts:62-162

Virtual JavaScript 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

Dev Server and Hot Reloading

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

Design Trade-offs

Design Choice	Benefit	Cost
`ExpressionSync` engine	Portable, works in Workerd/Edge	Limited JS feature support
WebSocket-based reloads	Extremely low latency	Requires open port/server-side state
`WeakMap` for caching	Automatic garbage collection of AST results	Potentially higher memory footprint per page