---
title: "Overview"
description: "Fumadocs is a modular documentation framework designed to bridge the gap between static content and dynamic, reactive documentation sites. At its core, the system solves the complexity of managing ..."
last_updated: "2026-07-02T09:46:39.394231+00:00"
canonical_url: "https://www.doc0.dev/docs/e8872a72-1909-479c-b585-dc74c6e26726/technical/orientation/overview"
---

<details>
<summary>Relevant source files</summary>

The following files were used as context for generating this wiki page:

- [packages/mdx/src/vite/index.ts](https://github.com/blade47/fumadocs/blob/main/packages/mdx/src/vite/index.ts)
- [packages/preview/src/pages/[...slugs].tsx](https://github.com/blade47/fumadocs/blob/main/packages/preview/src/pages/%5B...slugs%5D.tsx)
- [packages/mdx/src/runtime/dynamic.ts](https://github.com/blade47/fumadocs/blob/main/packages/mdx/src/runtime/dynamic.ts)
- [packages/content/src/index.ts](https://github.com/blade47/fumadocs/blob/main/packages/content/src/index.ts)
- [packages/core/package.json](https://github.com/blade47/fumadocs/blob/main/packages/core/package.json)
- [packages/mdx/package.json](https://github.com/blade47/fumadocs/blob/main/packages/mdx/package.json)
- [packages/api-docs/package.json](https://github.com/blade47/fumadocs/blob/main/packages/api-docs/package.json)
- [packages/local-md/package.json](https://github.com/blade47/fumadocs/blob/main/packages/local-md/package.json)
- [packages/openapi/package.json](https://github.com/blade47/fumadocs/blob/main/packages/openapi/package.json)
- [packages/content/src/runtime.ts](https://github.com/blade47/fumadocs/blob/main/packages/content/src/runtime.ts)
- [packages/preview/package.json](https://github.com/blade47/fumadocs/blob/main/packages/preview/package.json)
- [packages/base-ui/registry/index.ts](https://github.com/blade47/fumadocs/blob/main/packages/base-ui/registry/index.ts)
- [packages/typescript/package.json](https://github.com/blade47/fumadocs/blob/main/packages/typescript/package.json)
- [packages/mdx/tsdown.config.ts](https://github.com/blade47/fumadocs/blob/main/packages/mdx/tsdown.config.ts)
- [packages/obsidian/package.json](https://github.com/blade47/fumadocs/blob/main/packages/obsidian/package.json)
- [packages/mdx/src/runtime/types.ts](https://github.com/blade47/fumadocs/blob/main/packages/mdx/src/runtime/types.ts)
- [packages/base-ui/src/mdx.server.tsx](https://github.com/blade47/fumadocs/blob/main/packages/base-ui/src/mdx.server.tsx)
- [packages/radix-ui/registry/index.ts](https://github.com/blade47/fumadocs/blob/main/packages/radix-ui/registry/index.ts)
- [packages/sanity/registry/index.ts](https://github.com/blade47/fumadocs/blob/main/packages/sanity/registry/index.ts)
- [packages/twoslash/package.json](https://github.com/blade47/fumadocs/blob/main/packages/twoslash/package.json)
- [packages/doc-gen/package.json](https://github.com/blade47/fumadocs/blob/main/packages/doc-gen/package.json)
- [packages/mdx-remote/package.json](https://github.com/blade47/fumadocs/blob/main/packages/mdx-remote/package.json)
- [packages/content-collections/src/index.ts](https://github.com/blade47/fumadocs/blob/main/packages/content-collections/src/index.ts)
- [packages/preview/src/components/provider.tsx](https://github.com/blade47/fumadocs/blob/main/packages/preview/src/components/provider.tsx)
- [packages/python/package.json](https://github.com/blade47/fumadocs/blob/main/packages/python/package.json)
- [packages/mdx/src/config/index.ts](https://github.com/blade47/fumadocs/blob/main/packages/mdx/src/config/index.ts)
- [packages/radix-ui/package.json](https://github.com/blade47/fumadocs/blob/main/packages/radix-ui/package.json)
- [packages/asyncapi/package.json](https://github.com/blade47/fumadocs/blob/main/packages/asyncapi/package.json)
- [packages/cli/src/registry/plugins/preserve.ts](https://github.com/blade47/fumadocs/blob/main/packages/cli/src/registry/plugins/preserve.ts)
- [packages/story/package.json](https://github.com/blade47/fumadocs/blob/main/packages/story/package.json)
</details>

Fumadocs is a modular documentation framework designed to bridge the gap between static content and dynamic, reactive documentation sites. At its core, the system solves the complexity of managing Markdown/MDX content by providing a robust pipeline that handles everything from file parsing and MDX transformation to runtime data orchestration.

The system is architected around a collection-based data model. Instead of treating files as isolated entities, Fumadocs groups them into collections, allowing for structured access via plugins. This separation of concerns—parsing and transformation in the build/runtime phase versus presentation in the UI components—allows developers to use Fumadocs across various frameworks, including Next.js, Vite, and Waku.

Central to this architecture is the `Core` package, which provides the foundational logic for source handling and schema validation. By layering specific "source" packages (like `mdx`, `local-md`, or `openapi`) on top of this core, the framework enables high-performance content delivery, incremental updates via file system watchers, and specialized integrations like TypeScript type-table generation and OpenAPI documentation.

## Core Content Orchestration

The content orchestration mechanism functions as a multi-stage pipeline that ensures data consistency across the development lifecycle. When a content collection is defined—for example, via `docsCollection` or `mdxCollection`—the framework registers hooks (like `onEmit`) to generate the necessary glue code that links the static source with the application's runtime.

The system uses a virtual file generator to create manifests. In the case of `DocsCollection`, this mechanism ensures that the relationship between documentation content and metadata is preserved and type-safe.

```mermaid
flowchart TD
    Config["Configuration (source.config.ts)"] --> Core["Fumadocs Core Initialization"]
    Core --> Loaders["Collection Loaders (MDX, Meta)"]
    Loaders --> Emit["Emitter (Write to .source/)"]
    Emit --> Runtime["Runtime Consumption (docsStore)"]
```
Sources: [packages/mdx/src/vite/index.ts:106-108](https://github.com/blade47/fumadocs/blob/main/packages/mdx/src/vite/index.ts#L106-L108), [packages/content/src/index.ts:58-69](https://github.com/blade47/fumadocs/blob/main/packages/content/src/index.ts#L58-L69)

## Build-Time vs. Runtime Content

Fumadocs employs a two-pronged strategy for content processing: static compilation for production and dynamic runtime execution for development or edge-case scenarios. The `mdx` package provides a Vite plugin interface (`mdx(config)`) that manages this transition.

During the Vite build process, the plugin initializes a `Core` instance that builds the configuration, then configures `mdxLoader` and `metaLoader` to intercept file transformations.

> [!NOTE]
> The `id.includes('virtual:vite-rsc')` guard in the Vite plugin is a crucial invariant. It prevents the MDX loader from attempting to process compiled RSC (React Server Components) client references, which would otherwise corrupt the JavaScript output stream.

Sources: [packages/mdx/src/vite/index.ts:57-86](https://github.com/blade47/fumadocs/blob/main/packages/mdx/src/vite/index.ts#L57-L86)

## Dynamic Execution Path

When running in dynamic mode (e.g., during development or when using `dynamic.ts`), content is evaluated using `executeMdx`. This avoids re-compilation for every single request by leveraging a caching mechanism in `convertLazyEntries`.

The flow for retrieving dynamic content is:
1. `getDocCollection` verifies the collection name.
2. `convertLazyEntries` registers a map of file paths to lazy compilation functions.
3. The lazy function (`body[path]`) uses `cachedResult` to ensure the compilation occurs only once per instance.

```mermaid
sequenceDiagram
    participant User
    participant Loader as Dynamic Loader
    participant Compiler as MDX Builder
    User->>Loader: doc(name, entries)
    Loader->>Compiler: buildMDX(core, info)
    Compiler-->>Loader: Compiled MDX Properties
    Loader->>Loader: Execute and Cache
    Loader-->>User: Returns Compiled Component
```
Sources: [packages/mdx/src/runtime/dynamic.ts:67-92](https://github.com/blade47/fumadocs/blob/main/packages/mdx/src/runtime/dynamic.ts#L67-L92)

## Source Integration and Schema

The `packages/core` system exposes schema definitions (`pageSchema`, `metaSchema`) that are used by all content collections. This standardizes the frontmatter structure across different content types.

| Constant | Role |
| :--- | :--- |
| `pageSchema` | Standard Zod-like schema for MDX frontmatter validation. |
| `metaSchema` | Schema for defining directory-level navigation and metadata. |
| `docsStore` | Runtime helper that wraps MDX and Meta collections into a single source. |

Sources: [packages/content/src/index.ts:6](https://github.com/blade47/fumadocs/blob/main/packages/content/src/index.ts#L6), [packages/content/src/runtime.ts:44-50](https://github.com/blade47/fumadocs/blob/main/packages/content/src/runtime.ts#L44-L50)

## Plugin System and Registry

Fumadocs supports an extensible architecture through "Registry" plugins, used primarily by the CLI for scaffolded UI components. Components are registered with a `dir` and a `files` array that maps source paths to destination targets in the consumer's project.

> [!TIP]
> Use the `pluginPreserveLayouts` helper if you are developing custom documentation layouts. It prevents the CLI from overwriting core `fumadocs-ui` layout files unless a direct installation is requested by the user.

Sources: [packages/cli/src/registry/plugins/preserve.ts:6-13](https://github.com/blade47/fumadocs/blob/main/packages/cli/src/registry/plugins/preserve.ts#L6-L13), [packages/radix-ui/registry/index.ts:9-14](https://github.com/blade47/fumadocs/blob/main/packages/radix-ui/registry/index.ts#L9-L14)

## Design Trade-offs

The architecture makes deliberate choices to balance speed against developer experience.

| Design Choice | Benefit | Cost |
| :--- | :--- | :--- |
| Virtual Manifests | Enables rapid, decoupled builds. | Requires an internal `.source/` folder. |
| Lazy MDX Compilation | Reduces initial start-up time for large sites. | Adds latency to the first access of a page. |
| Standardized Core Schema | Guaranteed compatibility across packages. | Strict constraints on custom metadata. |

Sources: [packages/mdx/src/vite/index.ts:35](https://github.com/blade47/fumadocs/blob/main/packages/mdx/src/vite/index.ts#L35), [packages/mdx/src/runtime/dynamic.ts:91](https://github.com/blade47/fumadocs/blob/main/packages/mdx/src/runtime/dynamic.ts#L91)

## Full Worked Example: Custom Collection

To integrate a new collection that automatically includes shared remark plugins, you can use the `docsMdxCollection` utility.

```typescript
import { docsMdxCollection } from 'fumadocs-content';
import { pageSchema } from 'fumadocs-core/source/schema';

// This demonstrates how to define a collection that 
// includes standard remark plugins during the bundling phase.
export const docCollection = docsMdxCollection({
  dir: 'content/docs',
  frontmatter: pageSchema,
  options: {
    remarkPlugins: [/* Add custom plugins here */],
  },
});
```
Sources: [packages/content/src/index.ts:16-33](https://github.com/blade47/fumadocs/blob/main/packages/content/src/index.ts#L16-L33)

## Related

- [Quick Start](https://www.doc0.dev/docs/e8872a72-1909-479c-b585-dc74c6e26726/technical/orientation/quick-start)
- [Project Structure](https://www.doc0.dev/docs/e8872a72-1909-479c-b585-dc74c6e26726/technical/orientation/project-structure)


## Sitemap

See the full [sitemap](https://www.doc0.dev/docs/e8872a72-1909-479c-b585-dc74c6e26726/llms.txt) for all pages in this wiki.