Site Generation & Frontend Integration Overview

Overview

The Site Generation & Frontend Integration subsystem is responsible for transforming DeepDoc's AI-generated documentation plan into a fully functional, navigable documentation website. It automates the scaffolding, configuration, and integration of the Fumadocs frontend, ensuring that all generated documentation, navigation, assets, and interactive features (like search and chatbot) are consistently built and deployed.

This component is central to the DeepDoc architecture, bridging the gap between backend documentation planning and the user-facing site. It handles legacy migration, configures site theming and branding, and integrates advanced features such as OpenAPI rendering and chatbot Q&A.

For a high-level view of how this fits into the overall system, see DeepDoc Architecture & System Overview. For details on the document planning pipeline, see Pipeline & Generation Engine. For the chunking and summarization logic that powers search and chatbot, see Documentation Chunking and Summarization.

Files Covered

Architecture & Design

The site generation system is designed as a layered builder that takes a documentation plan and produces a ready-to-serve Fumadocs/Next.js site. It handles:

• Legacy migration: Converts old Markdown/MDX and navigation to the new structure.
• Frontend scaffolding: Generates all required config, assets, and React components.
• Feature integration: Adds OpenAPI, chatbot, and search features as needed.
• Theming and branding: Injects custom colors, logos, and layout options from config.

The builder is modular: each step (scaffold, page tree, assets, config, layouts) is handled by a dedicated function, making it easy to extend or customize.

Key Components

build_fumadocs_from_plan()

File: deepdoc/site/fumadocs_builder_v2.py:24
What it does:
Main entry point. Builds the Fumadocs site from a documentation plan (DocPlan). Handles migration, navigation, assets, and feature integration.

Signature:

def build_fumadocs_from_plan(
    repo_root: Path,
    output_dir: Path,
    cfg: dict[str, Any],
    plan: DocPlan,
    has_openapi: bool = False,
) -> None:

How it's used:

• Called by CLI commands and automation to generate/update the docs site.
• Consumes the output of the Pipeline & Generation Engine.

Key steps (all in deepdoc/site/fumadocs_builder_v2.py):

• _rename_md_to_mdx(): Converts .md files to .mdx.
• _rename_legacy_intro_to_index(): Migrates legacy intro pages.
• _ensure_mdx_frontmatter(): Ensures all MDX files have frontmatter.
• _ensure_landing_page(): Creates/updates the landing page.
• _build_page_tree_from_plan(): Builds the navigation tree.
• _ensure_app_scaffold(): Generates the Next.js/Fumadocs app scaffold.
• _write_page_tree(): Writes the navigation structure.
• _write_static_assets(): Adds logos and favicon.
• _cleanup_legacy_artifacts(): Removes obsolete files.

Example usage:

from deepdoc.site.fumadocs_builder_v2 import build_fumadocs_from_plan
build_fumadocs_from_plan(repo_root, output_dir, cfg, plan, has_openapi=True)

_ensure_app_scaffold()

File: deepdoc/site/fumadocs_builder_v2.py:64
What it does:
Writes or updates all files needed for a working Fumadocs/Next.js app, including package.json, tsconfig.json, configs, layouts, and React components.

Key outputs:

• [path-not-found], [path-not-found], [path-not-found], etc.
• [path-not-found], [path-not-found]
• [path-not-found] (chatbot), [path-not-found] (search API)
• [path-not-found] (navigation tree)

Configuration options:

• Project name, repo URL, colors, OpenAPI integration, chatbot config.

_build_page_tree_from_plan()

File: deepdoc/site/fumadocs_builder_v2.py:127
What it does:
Builds a navigation tree for Fumadocs from the documentation plan, handling special cases for overview and API reference pages.

Returns:
A dict representing the navigation structure, written to [path-not-found].

_write_static_assets()

File: deepdoc/site/fumadocs_builder_v2.py:353
What it does:
Creates placeholder logo and favicon assets in site/public/.

_rename_legacy_intro_to_index()

File: deepdoc/site/fumadocs_builder_v2.py:396
What it does:
Migrates legacy intro/overview files to the Fumadocs index.mdx convention.

_ensure_landing_page()

File: deepdoc/site/fumadocs_builder_v2.py:443
What it does:
Ensures a landing page exists, generating a cards-based overview if needed.

_mdx_components_tsx()

File: deepdoc/site/fumadocs_builder_v2.py:677
What it does:
Generates the MDX components registry, wiring up Fumadocs UI, custom components (Mermaid, APIPage), and feature toggles.

_app_layout_tsx()

File: deepdoc/site/fumadocs_builder_v2.py:705
What it does:
Defines the root React layout, branding, and global providers.

_global_css()

File: deepdoc/site/fumadocs_builder_v2.py:749
What it does:
Injects Tailwind, Fumadocs, and custom CSS, including theme colors from config.

_openapi_ts()

File: deepdoc/site/fumadocs_builder_v2.py:1951
What it does:
Integrates OpenAPI schemas for API reference pages.

_chatbot_config_ts()

File: deepdoc/site/fumadocs_builder_v2.py:2028
What it does:
Configures chatbot integration, using NEXT_PUBLIC_DEEPDOC_CHATBOT_BASE_URL or a backend URL from config.

_chatbot_toggle_tsx() and _chatbot_panel_tsx()

File: deepdoc/site/fumadocs_builder_v2.py:2042, deepdoc/site/fumadocs_builder_v2.py:2117
What they do:
Provide the chatbot UI toggle and panel, conditionally rendered based on config.

Configuration

The following environment variables and config keys affect site generation and frontend integration:

How Other Components Use This

• CLI and automation: The CLI (see CLI Commands & Tooling) invokes build_fumadocs_from_plan() to generate/update the site.
• Webhook triggers: Site builds can be triggered by webhooks (see Webhook Integrations).
• Chunking & search: The Documentation Chunking and Summarization system prepares content for search/chatbot, which is surfaced via the generated site.
• Anthropic/LLM integration: Content generation and Q&A features rely on the site being correctly scaffolded (see Anthropic Integration).
• Frontend features: The generated site exposes search, API reference, and chatbot features, all wired up via the builder.

Edge Cases & Failure Modes

• Legacy file migration: If both introduction.mdx and index.mdx exist, only index.mdx is kept. Old files are unlinked after migration.
• Missing frontmatter: _ensure_mdx_frontmatter() injects minimal frontmatter if missing, but may infer a generic title if none is found.
• Partial config: If required config keys (e.g., colors, repo URL) are missing, defaults are used, which may result in generic branding.
• Chatbot API misconfiguration: If NEXT_PUBLIC_DEEPDOC_CHATBOT_BASE_URL is set incorrectly, the chatbot UI may fail to connect.
• OpenAPI integration: If no OpenAPI schema is found, API reference pages are omitted.
• File system errors: All file writes use Path.mkdir(parents=True, exist_ok=True) and check for existence, but permission errors or disk issues will cause failures.
• Legacy artifacts: _cleanup_legacy_artifacts() attempts to remove obsolete files, but may leave directories if not empty.
• MD/MDX conversion: If a .md file cannot be read or parsed, it is skipped, which may result in missing pages.

Diagrams

Component Diagram

Site Generation Flow

Quick Reference

See Also

• DeepDoc Architecture & System Overview
• Site Builder Workflow and Frontend Integration
• Pipeline & Generation Engine
• Webhook Integrations
• CLI Commands & Tooling
• Anthropic Integration
• Documentation Chunking and Summarization

component_summary

TODO: This section (component_summary) needs to be filled in with details from the source files listed above.