Migrate documentation site to Fumadocs with monorepo structure and shared content by Copilot · Pull Request #11 · objectstack-ai/framework

Copilot · 2026-01-18T17:10:08Z

Replace the custom @objectdocs/cli documentation tooling with Fumadocs, a modern Next.js-based documentation framework, and restructure it into a proper monorepo architecture under apps/docs/ while keeping documentation content at the root level for sharing.

Changes

Monorepo Structure

Multi-package Architecture: Moved all Next.js files to apps/docs/ to avoid polluting the root directory
Workspace Isolation: Documentation site now has its own package.json with isolated dependencies
Clean Separation: Clear boundary between protocol packages (packages/*) and applications (apps/*)
Shared Content: Documentation content remains at /content/docs/ (root level) for easy access and sharing across the repository

Core Infrastructure

Next.js 16 + App Router: Full static site generation for 136 documentation pages
Fumadocs MDX: Auto-compilation from /content/docs/ (root level) with type-safe collection handling
Tailwind CSS v4: New CSS architecture with @tailwindcss/postcss

Directory Structure

Repository Root:
├── content/docs/     # Documentation content (MDX files) - SHARED LOCATION
│   ├── concepts/
│   ├── references/
│   └── specifications/
└── apps/docs/
    ├── app/              # Next.js App Router
    ├── source.config.ts  # Fumadocs collection config (references ../../content/docs)
    ├── next.config.mjs   # Next.js configuration
    ├── tailwind.config.js
    ├── postcss.config.mjs
    ├── tsconfig.json
    └── package.json      # Isolated dependencies

Configuration

// apps/docs/source.config.ts - Collection definition
export const docs = defineDocs({
  dir: '../../content/docs',  // References root-level content
}) as any; // Workaround for pnpm zod@4 type portability

// apps/docs/app/source.ts - Loader setup
import { docs } from 'fumadocs-mdx:collections/server';
export const source = loader({
  baseUrl: '/docs',
  source: (docs as any).toFumadocsSource(),
});

UI Components

Collapsible sidebar with auto-generated navigation from meta.json files
Search (⌘K), theme toggle, GitHub integration
MDX components (Callout, Card, Cards) rendered via fumadocs-ui/mdx

Build Output

Route (app)
├ ○ /
└ ● /docs/[[...slug]] (136 pages)
  ├ /docs
  ├ /docs/concepts/*
  ├ /docs/references/*
  └ /docs/specifications/*

Workspace Configuration

Updated pnpm-workspace.yaml to include apps/*
Root package.json scripts use workspace filters: pnpm --filter @objectstack/docs
Root package.json includes shared dependencies (lucide-react) used by MDX files
Root tsconfig.json excludes apps directory
.gitignore updated for apps structure

Screenshot

Scripts

Scripts remain the same from repository root:

pnpm docs:dev    # Start development server
pnpm docs:build  # Build for production
pnpm docs:start  # Start production server

Benefits

Clean Root Directory: No Next.js files in repository root
Shared Content: Documentation content at /content/docs/ accessible to other tools and workflows
Workspace Isolation: Each app/package manages its own dependencies
Scalability: Easy to add more apps (e.g., apps/playground, apps/studio)
Standard Pattern: Follows Turborepo/Nx monorepo conventions
Maintainability: Clear separation of concerns

All existing MDX content preserved at the root level. The .source/ directory (auto-generated by Fumadocs) is gitignored.

Original prompt

帮我使用fumadocs搭建此文档站点

💬 We'd love your input! Share your thoughts on Copilot coding agent in our 2 minute survey.

vercel · 2026-01-18T17:10:57Z

The latest updates on your projects. Learn more about Vercel for GitHub.

Project	Deployment	Review	Updated (UTC)
spec	Error		Jan 19, 2026 5:28am

Co-authored-by: huangyiirene <7665279+huangyiirene@users.noreply.github.com>

…rver Co-authored-by: huangyiirene <7665279+huangyiirene@users.noreply.github.com>

hotlong · 2026-01-19T00:51:55Z

@copilot nextjs项目使用多包架构放到apps/docs，不要污染根目录

Co-authored-by: hotlong <50353452+hotlong@users.noreply.github.com>

Copilot · 2026-01-19T01:01:20Z

@copilot nextjs项目使用多包架构放到apps/docs，不要污染根目录

Done! The Next.js documentation site has been moved to apps/docs/ following monorepo best practices.

Changes:

✅ All Next.js files moved to apps/docs/
✅ Documentation content now in apps/docs/content/
✅ Root directory cleaned up
✅ Workspace configuration updated
✅ Scripts still work from root: pnpm docs:dev, pnpm docs:build

See commit 3124fe9 for the complete restructuring.

hotlong · 2026-01-19T04:12:22Z

@copilot 我的文档还是放在很目录，不要换位置 /content/docs

Co-authored-by: hotlong <50353452+hotlong@users.noreply.github.com>

Copilot · 2026-01-19T04:20:13Z

@copilot 我的文档还是放在很目录，不要换位置 /content/docs

Done! Documentation content is now kept at the root directory /content/docs/ as requested.

Changes:

✅ Content moved back to /content/docs/ (root level)
✅ apps/docs/source.config.ts updated to reference ../../content/docs
✅ lucide-react added to root dependencies (required by MDX files)
✅ Build verified: All 136 pages generated successfully

The Next.js app remains in apps/docs/ but references the shared content at the root. This provides the best of both worlds: clean app structure while keeping content accessible at the root level.

See commit c60ebe7 for the changes.

…mprove documentation formatting, and refine build scripts

… prevent H1 generation in new files

…sociated script

… hero section, and implement feature cards

Moved reference .mdx files into protocol-based subdirectories (data, ui, system, ai, misc) and added meta.json files for each category. Updated build-docs.ts to generate documentation into these new directories and to update meta.json for navigation. This improves organization and navigation of API reference documentation.

Copilot

Pull request overview

This PR migrates the documentation site from a custom @objectdocs/cli tooling to Fumadocs, a modern Next.js-based documentation framework, while restructuring the repository into a proper monorepo architecture. The documentation content remains at the root level (/content/docs/) for sharing, while the Next.js application is cleanly isolated in apps/docs/.

Changes:

Replaced custom documentation CLI with Fumadocs + Next.js 16
Restructured to monorepo with apps/docs/ containing the site and /content/docs/ containing shared MDX content
Updated build scripts to categorize auto-generated schema documentation by protocol (data, ui, system, ai)
Removed duplicate H1 headings from MDX files (now handled by page layout)
Added proper workspace configuration with isolated dependencies

Reviewed changes

Copilot reviewed 157 out of 160 changed files in this pull request and generated 5 comments.

Show a summary per file

File	Description
`pnpm-workspace.yaml`	Added `apps/*` to workspace packages
`package.json`	Updated scripts to use workspace filters, moved dependencies to appropriate locations
`tsconfig.json`	Excluded apps and packages directories from root TypeScript config
`apps/docs/*/`	New Next.js 16 documentation site with Fumadocs integration
`packages/spec/scripts/build-docs.ts`	Enhanced to categorize generated docs by protocol type
`content/docs/*/.mdx`	Removed duplicate H1 titles, escaped inline code with braces
`content/docs/references/*/meta.json`	Added category metadata for navigation
`.gitignore`	Added Next.js and Fumadocs specific ignores
`pnpm-lock.yaml`	Removed `@objectdocs/cli`, added Fumadocs dependencies

Files not reviewed (1)

pnpm-lock.yaml: Language not supported

Copilot · 2026-01-19T05:31:32Z

+          </div>
+
+          <h1 className="text-4xl font-extrabold tracking-tight sm:text-6xl md:text-7xl bg-gradient-to-br from-foreground to-foreground/60 bg-clip-text text-transparent pb-2">
+            The Post-SaaS <br/> Operatings System


Spelling error: "Operatings" should be "Operating". This is a critical typo in the main heading of the homepage.

Suggested change

The Post-SaaS <br/> Operatings System

The Post-SaaS <br/> Operating System

Copilot · 2026-01-19T05:31:32Z

+// 1. Scan source files to build map
+Object.keys(CATEGORIES).forEach(category => {
+  const dir = path.join(SRC_DIR, category);
+  if (fs.existsSync(dir)) {
+    const files = fs.readdirSync(dir).filter(f => f.endsWith('.ts'));
+    for (const file of files) {
+      const content = fs.readFileSync(path.join(dir, file), 'utf-8');
+
+      // Regex to find exported const schemas (e.g. "export const ObjectSchema = ...")
+      // also matches "export const ObjectCapabilities = ..."
+      // We assume conventions are followed
+      const matches = content.matchAll(/export const (\w+)(?:Schema)?\s*=\s*z\./g);
+      for (const match of matches) {
+        // match[1] is the name (e.g. Object).
+        // Note: build-schemas.ts strips 'Schema' suffix. 
+        // We match (\w+) which captures 'ObjectSchema' or 'ObjectCapabilities'.
+        // logic in build-schemas: `key.endsWith('Schema') ? key.replace('Schema', '') : key`
+
+        let schemaName = match[1]; // e.g. Object from ObjectSchema
+        if (!content.includes(`export const ${schemaName}Schema =`)) {
+           // Wait, regex above captures "Object" from "ObjectSchema" IF I put Schema in non-capturing group?
+           // No, (\w+) captures "ObjectSchema". (?:Schema)? is applied to verify/consume suffix but regex is tricky.
+           // Simplified regex: /export const (\w+)\s*=/
+           // Then apply naming logic.
+        }
+      }
+    }
+  }
+});


Dead code: Lines 20-48 contain commented-out or incomplete code that was replaced by the scanCategories function starting at line 50. This dead code should be removed to improve maintainability and avoid confusion.

Copilot · 2026-01-19T05:31:32Z

+
+export const docs = defineDocs({
+  dir: '../../content/docs',
+}) as any;


Type safety issue: The use of as any on line 5 bypasses TypeScript's type checking. The PR description mentions this is a "workaround for pnpm zod@4 type portability", but this defeats the purpose of TypeScript and could hide type errors. Consider finding a proper solution or at least adding a detailed comment explaining why this workaround is necessary and tracking it for future removal.

Suggested change

}) as any;

});

Copilot · 2026-01-19T05:31:33Z

+
+export const source = loader({
+  baseUrl: '/docs',
+  source: (docs as any).toFumadocsSource(),


Type safety issue: Another use of as any that bypasses TypeScript type checking. This is consistent with the workaround in source.config.ts but should be properly addressed or documented.

Suggested change

source: (docs as any).toFumadocsSource(),

// @ts-expect-error: fumadocs-mdx virtual module typings do not currently expose `toFumadocsSource`

source: docs.toFumadocsSource(),

Copilot · 2026-01-19T05:31:33Z

-if (!fs.existsSync(DOCS_DIR)) {
-  fs.mkdirSync(DOCS_DIR, { recursive: true });
+// 2. Prepare Directories
+const miscDir = path.join(DOCS_ROOT, 'misc');


Unused variable miscDir.

Initial plan

916b305

Copilot AI assigned Copilot and huangyiirene Jan 18, 2026

Copilot started work on behalf of huangyiirene January 18, 2026 17:10 View session

vercel Bot had a problem deploying to Preview January 18, 2026 17:10 Failure

Add Fumadocs documentation site setup

c98c758

Co-authored-by: huangyiirene <7665279+huangyiirene@users.noreply.github.com>

vercel Bot had a problem deploying to Preview January 18, 2026 17:37 Failure

Complete Fumadocs documentation site setup - working build and dev se…

2e5bfa6

…rver Co-authored-by: huangyiirene <7665279+huangyiirene@users.noreply.github.com>

vercel Bot deployed to Preview January 18, 2026 17:43 View deployment

Copilot AI changed the title ~~[WIP] Add setup for Fumadocs documentation site~~ Migrate documentation site from custom @objectdocs/cli to Fumadocs Jan 18, 2026

Copilot AI requested a review from huangyiirene January 18, 2026 17:46

Copilot finished work on behalf of huangyiirene January 18, 2026 17:46

Copilot started work on behalf of hotlong January 19, 2026 00:52 View session

Refactor: Move documentation site to apps/docs for monorepo structure

3124fe9

Co-authored-by: hotlong <50353452+hotlong@users.noreply.github.com>

vercel Bot had a problem deploying to Preview January 19, 2026 01:01 Failure

Copilot AI changed the title ~~Migrate documentation site from custom @objectdocs/cli to Fumadocs~~ Migrate documentation site to Fumadocs with monorepo structure (apps/docs) Jan 19, 2026

Copilot AI requested a review from hotlong January 19, 2026 01:02

Copilot finished work on behalf of hotlong January 19, 2026 01:02

Copilot started work on behalf of hotlong January 19, 2026 04:12 View session

Keep documentation content at root /content/docs as requested

c60ebe7

Co-authored-by: hotlong <50353452+hotlong@users.noreply.github.com>

vercel Bot had a problem deploying to Preview January 19, 2026 04:20 Failure

Copilot AI changed the title ~~Migrate documentation site to Fumadocs with monorepo structure (apps/docs)~~ Migrate documentation site to Fumadocs with monorepo structure and shared content Jan 19, 2026

Copilot finished work on behalf of hotlong January 19, 2026 04:21

Enhance Fumadocs setup: Update webpack config for alias resolution, i…

2719472

…mprove documentation formatting, and refine build scripts

vercel Bot had a problem deploying to Preview January 19, 2026 05:08 Failure

hotlong added 2 commits January 19, 2026 13:10

Remove H1 headers from documentation files and update build script to…

1de4265

… prevent H1 generation in new files

Remove H1 headers from multiple documentation files and delete the as…

2973586

…sociated script

vercel Bot had a problem deploying to Preview January 19, 2026 05:12 Failure

hotlong added 2 commits January 19, 2026 13:20

Enhance HomePage component: Replace redirect with content layout, add…

974feda

… hero section, and implement feature cards

Update page.tsx

b869b74

vercel Bot had a problem deploying to Preview January 19, 2026 05:23 Failure

vercel Bot had a problem deploying to Preview January 19, 2026 05:28 Failure

hotlong marked this pull request as ready for review January 19, 2026 05:29

Copilot AI review requested due to automatic review settings January 19, 2026 05:29

Copilot started reviewing on behalf of hotlong January 19, 2026 05:29 View session

hotlong merged commit 2984aaa into main Jan 19, 2026
5 of 7 checks passed

Copilot AI reviewed Jan 19, 2026

View reviewed changes

Copilot AI mentioned this pull request Feb 16, 2026

feat(ui): add InterfaceNavItemSchema, disambiguate PageTypeSchema overlaps #697

Merged

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

Migrate documentation site to Fumadocs with monorepo structure and shared content#11

Migrate documentation site to Fumadocs with monorepo structure and shared content#11
hotlong merged 11 commits intomainfrom
copilot/setup-fumadocs-site

Copilot AI commented Jan 18, 2026 •

edited

Loading

Uh oh!

vercel Bot commented Jan 18, 2026 •

edited

Loading

Uh oh!

hotlong commented Jan 19, 2026

Uh oh!

Copilot AI commented Jan 19, 2026

Uh oh!

hotlong commented Jan 19, 2026

Uh oh!

Copilot AI commented Jan 19, 2026

Uh oh!

Uh oh!

Copilot AI left a comment

Uh oh!

Copilot AI Jan 19, 2026

Uh oh!

Copilot AI Jan 19, 2026

Uh oh!

Copilot AI Jan 19, 2026

Uh oh!

Copilot AI Jan 19, 2026

Uh oh!

Copilot AI Jan 19, 2026

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

4 participants

	The Post-SaaS <br/> Operatings System
	The Post-SaaS <br/> Operating System

	source: (docs as any).toFumadocsSource(),
	// @ts-expect-error: fumadocs-mdx virtual module typings do not currently expose `toFumadocsSource`
	source: docs.toFumadocsSource(),

Conversation

Copilot AI commented Jan 18, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Changes

Monorepo Structure

Core Infrastructure

Directory Structure

Configuration

UI Components

Build Output

Workspace Configuration

Screenshot

Scripts

Benefits

Uh oh!

vercel Bot commented Jan 18, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

hotlong commented Jan 19, 2026

Uh oh!

Copilot AI commented Jan 19, 2026

Uh oh!

hotlong commented Jan 19, 2026

Uh oh!

Copilot AI commented Jan 19, 2026

Uh oh!

Uh oh!

Copilot AI left a comment

Choose a reason for hiding this comment

Pull request overview

Reviewed changes

Uh oh!

Copilot AI Jan 19, 2026

Choose a reason for hiding this comment

Uh oh!

Copilot AI Jan 19, 2026

Choose a reason for hiding this comment

Uh oh!

Copilot AI Jan 19, 2026

Choose a reason for hiding this comment

Uh oh!

Copilot AI Jan 19, 2026

Choose a reason for hiding this comment

Uh oh!

Copilot AI Jan 19, 2026

Choose a reason for hiding this comment

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

4 participants

Copilot AI commented Jan 18, 2026 •

edited

Loading

vercel Bot commented Jan 18, 2026 •

edited

Loading