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:
The Preview Environment subsystem provides a robust, real-time development and documentation rendering experience. By integrating dynamic compilation, filesystem watching, and reactive UI components, it enables developers to view documentation content as it is authored while supporting advanced features like AI-powered search, API playground interactions, and hot reloading.
The environment acts as a bridge between static content and a live, interactive UI. It orchestrates the loading of documentation sources from the filesystem, processes MDX content through a unified compiler, and renders the result within a framework-agnostic layout. Central to this architecture is the decoupling of the content engine from the rendering framework, allowing for consistent behavior whether running in development or a production-preview context.
By centralizing configuration (via load-runtime.ts) and leveraging hot-reloading mechanisms (via waku.server.tsx), the Preview Environment ensures that changes to source files are immediately reflected in the user's view. This system eliminates the latency typical of static site regeneration during development, creating a fluid, high-fidelity experience for authors and technical documentation consumers alike.
The system employs a dynamic compilation pipeline to transform Markdown and MDX content on the fly. This avoids pre-build overhead and ensures the latest document content is always available. When a request is made, the compiler (a createMarkdownCompiler instance) processes the source using remark and rehype plugins, including support for GFM, math, code blocks, and Mermaids diagrams.
The pipeline specifically handles file resolution through getPage and compiles the document content within the MdContent component. If compilation fails, the system catches the error and renders an error page displaying the stack trace, preventing the entire application from crashing.
Sources: packages/preview/src/pages/[...slugs].tsx:29-46,140-194
The Preview Environment includes an integrated AI chat interface, AISearch, which allows users to query documentation interactively. This component uses the @ai-sdk/react library to stream responses from an AI model.
The chat mechanism relies on a tool-calling pattern where the AI can invoke a search tool. This tool queries a local Flexsearch index built at runtime from the documentation source files. The system guards against excessive usage via a simple IP-based rate limiter located in the API endpoint.
Important
The rate limiter identifies clients by their IP address derived from headers (x-forwarded-for or cf-connecting-ip). If a bucket reaches rateLimitMaxRequests (20), the system returns a 429 status code and a Retry-After header.
Sources: packages/preview/src/components/ai/search.tsx:292-304,331-388, packages/preview/src/pages/_api/api/chat.ts:55-156
To facilitate immediate feedback, the system monitors the filesystem for changes. The initHotReload function in the server entry point establishes a WebSocket connection with the client-side HotReload component.
When the file watcher detects a change, it performs two critical steps:
![packages/preview/src/pages/_api/og/[...slugs]/image.webp.tsx](https://github.com/blade47/fumadocs/blob/main/packages/preview/src/pages/_api/og/%5B...slugs%5D/image.webp.tsx){kind=link}
filesCache.getSource.revalidate(false) to force a refresh of the content source, ensuring that subsequent requests pull the modified data.The client-side component then receives a revalidate event and triggers a router.reload(). This creates a seamless development loop for content authors.
Sources: packages/preview/src/waku.server.tsx:56-92, packages/preview/src/components/hot-reload.tsx:6-26
For API-driven documentation, the system leverages ServerProvider and Operation contexts. These components maintain the state of API servers and request schemas. The schema UI uses a path-tracking system (PathItemType[]) to allow users to navigate nested objects within OpenAPI definitions via a popover.
Sources: packages/asyncapi/src/ui/contexts/api.tsx:47-124, packages/openapi/src/ui/operation/context.tsx:20-82, packages/api-docs/src/components/schema/client.tsx:83-185
The application configuration is parsed dynamically. The system provides a centralized getConfigRuntime function which resolves the config path, loads it, and returns a validated ParsedAppConfig. This is then injected throughout the application via the source loader, ensuring that project-specific directories (where Markdown files are found) are correctly identified during startup.
// Initializing the configuration for the preview app
const configPath = await findConfigPath();
const config = await loadConfig(configPath);Sources: packages/preview/src/config/load-runtime.ts:26-31
The system exposes a custom image proxy API (/api/img) to resolve image assets from projects that may exist outside the public directory. It checks for assets in the page's relative directory, configured asset directories, or the project root. This ensures documentation images remain linked correctly even in complex file structures.
Note
The file lookup logic follows a strict order: relative page directory → project-configured assets directories → root public directory. If a file is not found, the proxy falls back to a 404.
Sources: packages/preview/src/pages/_api/img.ts:19-66