How this repository integrates Fumadocs, where MDX lives, and how to add structured technical docs that render correctly in /docs

Fumadocs Authoring and Integration Guide

This page explains exactly how docs are wired in this repository.

1) Runtime Integration Overview

The docs stack uses:

fumadocs-mdx for MDX source generation
fumadocs-core for source loading and page tree
fumadocs-ui for docs layout and MDX components

Key Files

source.config.ts                 # MDX source config
next.config.ts                   # createMDX integration
mdx-components.tsx               # MDX component mapping
lib/source.ts                    # loader + page tree
lib/layout.shared.tsx            # nav/github layout options
app/docs/layout.tsx              # DocsLayout wrapper
app/docs/[[...slug]]/page.tsx    # page renderer
content/docs/*.mdx               # documentation content

2) Request Flow

Browser -> /docs/... route
      -> app/docs/[[...slug]]/page.tsx
      -> source.getPage(slug)
      -> render MDX body with getMDXComponents()
      -> DocsLayout sidebar + toc

3) Creating a New Document

Add a new file in content/docs.
Include frontmatter with title and description at minimum.
Link from content/docs/index.mdx if it should be discoverable quickly.

Minimal Template

---
title: "My New Guide"
description: "What this guide teaches"
---

# My New Guide

Write your content here.

4) Recommended Frontmatter for This Repository

---
title: "..."
description: "..."
author: "PanOS Development Team"
version: "2.0.0"
lastUpdated: "2026-03-09"
difficulty: "beginner|intermediate|advanced"
estimatedReadTime: "X min"
section: "Area"
order: 99
keywords: ["tag-a", "tag-b"]
slug: "optional-custom-slug"
---

Because source.config.ts uses pageSchema.passthrough(), custom metadata fields are accepted.

5) Supported MDX Patterns

Standard Markdown

headings
tables
fenced code blocks
lists and checklists

Fumadocs MDX Components

Cards and Card are supported via default Fumadocs MDX components.

<Cards>
  <Card title="Architecture" href="./06-architecture.mdx">
    Deep dive into internals.
  </Card>
</Cards>

6) Link Strategy

Prefer relative links inside docs:

[Build Guide](./04-building.mdx)

Relative links are resolved using createRelativeLink(source, page).

7) Validation Workflow

After writing docs, run:

npm run lint
npm run build

Optional local check:

npm run dev
# open /docs

8) Common Errors and Fixes

Error: page not found

Ensure file is inside content/docs.
Ensure route path matches filename slug.

Error: MDX compile failure

Validate frontmatter syntax.
Check unclosed code fences.
Verify JSX-like MDX tags are balanced.

Error: Links not resolving

Use relative .mdx links between docs.
Ensure target filenames exist.

9) Maintenance Rules

Keep docs in English for consistency.
Prefer practical examples over conceptual-only text.
Include at least one runnable snippet in technical pages.
Update lastUpdated and version when substantial changes are made.

10) Suggested Authoring Pipeline

draft -> local lint/build -> docs review -> merge -> release notes update

Next Read

Return to index.mdx and continue through the integration and design tracks.

Fumadocs Authoring and Integration Guide

On this page