Overview

Overview

Fumadocs is a modern, framework-agnostic documentation ecosystem designed for React applications, providing a modular architecture that separates core document processing, source loading, and layout presentation packages/core/package.json:2-4. It addresses the complexity of building documentation sites by decoupling headless primitives and build-time content compilation from opinionated styling layers and frontend frameworks. The project is organized as a monorepo workspace containing runtime engines, bundler integration plugins, and user interface implementations [packages/core/package.json:2-4, packages/radix-ui/package.json:2-4. Fumadocs integrates closely with tools like BaseHub Integration and MDX Runtime Compilation to support flexible content workflows and dynamic rendering [packages/basehub/package.json:4-4, packages/mdx/src/runtime/server.ts:1-2.

Architecture and Design Philosophy

Fumadocs is architected around a strict separation of concerns, decoupling framework-agnostic document processing, source loading, and state management from concrete UI implementations packages/core/package.json:2-4. The core runtime library (fumadocs-core) delivers navigation tree generation, internationalization negotiation, search server indexing, syntax highlighting, and remark/rehype markdown AST transformations without depending on a specific frontend framework or bundler [packages/core/package.json:2-4, packages/core/package.json:42-87.

The ecosystem provides explicit framework routing adapters and runtime provider packages for Next.js, React Router, TanStack, Waku, and Vite [packages/core/package.json:29-33, packages/radix-ui/package.json:104-108. This modular layer separation allows documentation content models and source schemas to be compiled independently of presentation components, which are supplied separately through accessible UI packages like fumadocs-ui backed by Radix UI primitives [packages/radix-ui/package.json:2-4, packages/radix-ui/package.json:134-143.

Sources: packages/core/package.json:20-88, packages/content/package.json:17-21, packages/radix-ui/package.json:18-117, packages/shared/package.json:4-8, packages/mdx/package.json:24-44

Sources: packages/content/package.json:32-46

Sources: packages/core/package.json:29-33

Monorepo Package Structure and Roles

Core Runtime and Content Compilers

The Fumadocs workspace organizes its source code into specialized packages, separating the framework-agnostic runtime engine from build-time content compilation and UI layers. The core runtime package, fumadocs-core, provides foundational services including source file discovery, page tree calculations, internationalization negotiation, search server indexing, syntax highlighting, and unified remark/rehype markdown AST transformations packages/core/package.json:2-4, packages/core/package.json:42-87.

Build-time processing is handled by fumadocs-mdx, which exposes integration entry points for bundlers and runtime loaders, including Next.js, Vite, Webpack, Rolldown, and Bun packages/mdx/package.json:24-44. Content validation and schema mapping across standard schemas are delegated to @fumadocs/content, which relies on fuma-content and @standard-schema/spec packages/content/package.json:32-46.

Sources: packages/core/package.json:2-4, packages/core/package.json:42-87, packages/mdx/package.json:24-44, packages/content/package.json:32-46

Sources: packages/mdx/package.json:24-44

UI Implementations and Layouts

Presentation components are factored into distinct UI packages that target specific primitive ecosystems. The two primary UI design implementations are fumadocs-ui (backed by Radix UI primitives) and @fumadocs/base-ui (built for Base UI) packages/base-ui/package.json:2-4, packages/radix-ui/package.json:2-4, packages/cli/src/commands/shared.ts:1-4. Both packages provide identical export paths for documentation layouts, navigation slots, code blocks, search dialogs, and interactive UI widgets packages/base-ui/package.json:18-114, packages/radix-ui/package.json:18-117.

Sources: packages/base-ui/package.json:18-114, packages/radix-ui/package.json:18-117, packages/api-docs/package.json:18-67, packages/cli/src/commands/shared.ts:1-4]

Sources: packages/cli/src/commands/shared.ts:1-4

Tooling, Extensibility, and Preview Packages

Specialized plugins and developer tooling are isolated into independent workspace packages to keep runtime footprints minimal packages/preview/package.json:2-4, packages/typescript/package.json:2-4, packages/twoslash/package.json:2-4, packages/doc-gen/package.json:2-4, packages/create-app/package.json:2-4. These include fumadocs-typescript for type table extractions via ts-morph packages/typescript/package.json:39-49, fumadocs-twoslash for Shiki-based compiler diagnostics packages/twoslash/package.json:45-53, fumadocs-docgen for remark utilities like remark-ts2js packages/doc-gen/package.json:26-30, packages/doc-gen/package.json:41-50, fumadocs-preview for Waku-backed fast content previews with AI search features packages/preview/package.json:2-4, packages/preview/package.json:35-88, and create-fumadocs-app for project scaffolding packages/create-app/package.json:2-4, packages/create-app/package.json:43-52.

Sources: packages/preview/package.json:2-4, packages/preview/package.json:35-88, packages/typescript/package.json:2-4, packages/typescript/package.json:39-49, packages/twoslash/package.json:2-4, packages/twoslash/package.json:45-53, packages/doc-gen/package.json:2-4, packages/doc-gen/package.json:26-30, packages/doc-gen/package.json:41-50, packages/create-app/package.json:2-4, packages/create-app/package.json:43-52

Content Compilation and Source Processing

Document Schemas and Collection Configuration

Document parsing and type-safe frontmatter validation rely on @standard-schema/spec [packages/content/package.json:32-34, packages/mdx/package.json:56-58]. The @fumadocs/content package provides helper utilities like docsMdxCollection and docsCollection to structure directories containing MDX documents and metadata files packages/content/src/index.ts:16-53. By default, docsMdxCollection integrates mdxPreset configurations with remark include plugins for content composition packages/content/src/index.ts:24-32.

Sources: packages/content/package.json:32-34, packages/content/src/index.ts:16-53, packages/mdx/package.json:56-58]

Sources: packages/content/src/index.ts:16-19]

Runtime and Dynamic MDX Compilation

The fumadocs-mdx package supports runtime compilation and dynamic execution of MDX files through its runtime modules [packages/mdx/package.json:37-40]. The dynamic utility resolves collections and compiles raw content entries into hydrated properties packages/mdx/src/runtime/dynamic.ts:47-95.

Copyasync function executeMdx(compiled: string, options: ExecuteOptions = {}) {
  const { opts: scopeOpts, ...scope } = options.scope ?? {};
  const fullScope = {
    opts: {
      ...(scopeOpts as object),
      ...(options.jsxRuntime ?? jsxRuntimeDefault),
      baseUrl: options.baseUrl,
    },
    ...scope,
  };
 
  const hydrateFn = new AsyncFunction(...Object.keys(fullScope), compiled);
  return await hydrateFn.apply(hydrateFn, Object.values(fullScope));
}

Sources: packages/mdx/src/runtime/dynamic.ts:32-45]

The DocsCollection class manages code generation by listening to emission hooks and constructing virtual code modules that link back to stores packages/content/src/index.ts:55-70. Concurrently, toFumadocsSource maps underlying file collection stores into structured static sources containing page and metadata entries packages/content/src/runtime.ts:12-42.

Sources: packages/content/src/index.ts:55-70, packages/content/src/runtime.ts:12-42]

Presentation Primitives and Layout Systems

Headless UI Implementations and UI Registries

Fumadocs separates visual styling and component layout architectures into two alternative UI implementations: @fumadocs/base-ui and fumadocs-ui (backed by Radix UI primitives) packages/base-ui/package.json:2-4, packages/radix-ui/package.json:2-4. These UI variants share identical export paths for foundational primitives, layout slots, and navigation contexts while consuming distinct underlying primitives. The command line utility references these two packages under the identifiers base-ui and radix-ui packages/cli/src/commands/shared.ts:1-4.

Sources: packages/base-ui/package.json:2-4, packages/radix-ui/package.json:2-4, packages/cli/src/commands/shared.ts:1-4, packages/radix-ui/package.json:131-154]

Sources: packages/base-ui/package.json:18-114, packages/radix-ui/package.json:18-117]

Layout Presets and Markdown Compilation Pipeline

Layout presets determine how documentation pages and structural containers renderpackages/preview/src/pages/[...slugs].tsx:80-96. The preview server configuration supports dynamic markdown rendering pipelines incorporating remark and rehype plugins for math, headings, GFM, code tabs, package manager persistence, and Mermaid diagramspackages/preview/src/pages/[...slugs].tsx:29-46.

Copyconst compiler = createMarkdownCompiler({
  remarkPlugins: [
    remarkGfm,
    remarkMath,
    remarkMdxMermaid,
    plugin(remarkHeading, { generateToc: false }),
    plugin(remarkNpm, { persist: { id: 'package-manager' } }),
    remarkCodeTab,
  ],
  remarkRehypeOptions: {
    passThrough: ['mdxJsxFlowElement', 'mdxJsxTextElement'],
  },
  rehypePlugins: [
    rehypeKatex,
    plugin(rehypeCode, { lazy: true, fallbackLanguage: 'text' }),
    plugin(rehypeToc, { exportToc: { as: 'data' } }),
  ],
});

Sources: packages/preview/src/pages/...slugs.tsx:29-46]

The dynamic page renderer inspects the layout preset configuration (docs or flux) to load corresponding layout modules and page components dynamicallypackages/preview/src/pages/[...slugs].tsx:80-96. When rendering documentation containers, AI search widgets are conditionally injected alongside layout slots if AI support is enabledpackages/preview/src/pages/[...slugs].tsx:113-138.

Sources: packages/preview/src/pages/...slugs.tsx:80-96, packages/preview/src/pages/...slugs.tsx:113-138]

Tooling and Extensibility Ecosystem

Specification Generators and Language Integration Plugins

Fumadocs provides specialized packages that ingest specification files and foreign source code, transforming them into documentation structures. The fumadocs-openapi package parses OpenAPI v3 and Swagger definitions to generate MDX documentation pages, client request generators, and interactive UI components, with exports for C#, cURL, Go, Java, JavaScript, and Python request generatorspackages/openapi/package.json:2-37. Similarly, @fumadocs/asyncapi processes AsyncAPI specifications to generate documentation for asynchronous message-driven architectures with dedicated server and internationalization entry pointspackages/asyncapi/package.json:2-25. For Python codebases, fumadocs-python and the underlying fumapy module inspect source code and docstrings using Griffe and Griffe typing extensions to extract API documentationpackages/python/package.json:2-4, packages/python/pyproject.toml:2-8.

Sources: packages/python/package.json:2-32, packages/openapi/package.json:2-37, packages/asyncapi/package.json:2-25, packages/python/pyproject.toml:2-8, packages/story/package.json:2-24]

Sources: packages/story/package.json:14-24]

Standalone Content Sources and Export Utilities

Additional packages extend content ingestion and distribution capabilities beyond standard Markdown and MDX files. The @fumadocs/local-md package parses local Markdown files and executes embedded expressions in Node and browser runtimes, exposing execution targets such as executor, executor-native, and executor-virtualpackages/local-md/package.json:2-30. For offline reading, fumadocs-epub bundles compiled documentation pages, assets, and tables of contents into EPUB ebookspackages/epub/package.json:2-26. Integration with headless CMS platforms is supported by registry modules like fumadocs/sanity, which provides installable component snippets for rendering portable text collections packages/sanity/registry/index.ts:1-100.

Sources: packages/local-md/package.json:2-30, packages/epub/package.json:2-26, packages/sanity/registry/index.ts:1-100]

Developer CLI Workflows

The Fumadocs CLI (@fumadocs/cli) and site scaffolding tool (create-fumadocs-app) orchestrate project initialization, component management, and export actionspackages/cli/src/index.ts:1-116, packages/create-app/package.json:2-31. The CLI runner initializes configuration files, customizes UI layouts, downloads registry components via local or HTTP connectors, exports documentation to EPUB format, and converts file tree structures into JavaScript or MDX modulespackages/cli/src/index.ts:17-114.

Copyprogram
  .command('add')
  .description('add a new component to your docs')
  .argument('[components...]', 'components to download')
  .option('--dir <string>', 'the root url or directory to resolve registry')
  .action(async (input: string[], options: { config?: string; dir?: string }) => {
    const config = await createOrLoadConfig(options.config);
    const client = createClientFromDir(options.dir);
    await add(input, client, config);
  });
 
const exportCmd = program.command('export').description('export documentation to various formats');
 
exportCmd
  .command('epub')
  .description('export documentation to EPUB format (run after production build)')
  .requiredOption('--framework <name>', 'React framework: next, tanstack-start, react-router, waku')
  .option('--output <path>', 'output file path', 'docs.epub')
  .option('--scaffold-only', 'only scaffold the EPUB route, do not copy')
  .action(async (options: { output?: string; framework: string; scaffoldOnly?: boolean }) => {
    await exportEpub({
      output: options.output,
      framework: options.framework,
      scaffoldOnly: options.scaffoldOnly,
    });
  });

Sources: packages/cli/src/index.ts:44-69]

Sources: packages/cli/src/index.ts:57-69]

Where to go next

Related

• Quick Start
• Project Structure
• Source Loader