Update /apps/docs to latest fumadocs template#576
Conversation
|
The latest updates on your projects. Learn more about Vercel for GitHub.
|
- Update package.json: pin fumadocs versions, add postinstall/types:check scripts, remove unused deps (clsx, cva, autoprefixer, etc.) - Update source.config.ts: use pageSchema/metaSchema, add includeProcessedMarkdown for LLM support - Update next.config.mjs: remove webpack hacks, add rewrites for LLM MDX - Update postcss.config.mjs: remove autoprefixer (Tailwind v4) - Update tsconfig.json: add baseUrl, forceConsistentCasingInFileNames, ESNext target - Update global.css: use new fumadocs CSS imports (neutral.css + preset.css) - Update mdx-components.tsx: rename to getMDXComponents pattern - Update lib/utils.ts: simplify cn to twMerge re-export - Move app/source.ts → lib/source.ts with lucideIconsPlugin, getPageImage, getLLMText - Move app/layout.config.tsx → lib/layout.shared.tsx with function pattern + gitConfig - Update docs page: use DocsTitle/DocsDescription/DocsBody from new import path - Update search API: use createFromSource instead of createSearchAPI - Add LLM support: llms.txt, llms-full.txt, per-page .mdx endpoints - Add OG image generation: og/docs/[...slug]/route.tsx - Add AI page-actions component: Copy Markdown, Open in ChatGPT/Claude/GitHub - Remove tailwind.config.js (Tailwind v4 doesn't need config) - Remove unused badge.tsx and button.tsx components Co-authored-by: hotlong <50353452+hotlong@users.noreply.github.com>
There was a problem hiding this comment.
Pull request overview
Updates the /apps/docs Next.js app scaffolding to the latest Fumadocs template while preserving existing docs structure and adding new documentation capabilities (LLM exports, OG images, updated search).
Changes:
- Modernized Fumadocs/Next config (new source schemas, rewrites for
.mdxLLM endpoints, updated CSS/Tailwind v4 setup). - Migrated docs source/layout utilities into
lib/and updated pages to use new Fumadocs layouts and MDX component wiring. - Added new protocol reference sections/pages (e.g., Studio, Hub) and new endpoints (
/llms.txt,/llms-full.txt, OG image routes).
Reviewed changes
Copilot reviewed 173 out of 200 changed files in this pull request and generated 8 comments.
Show a summary per file
| File | Description |
|---|---|
| content/docs/references/system/license.mdx | Updates system license reference and TS usage snippet. |
| content/docs/references/system/job.mdx | Removes large auto-generated property tables from job reference. |
| content/docs/references/system/index.mdx | Updates system reference navigation cards (adds/removes pages). |
| content/docs/references/system/http-server.mdx | Removes large auto-generated property tables from http-server reference. |
| content/docs/references/system/encryption.mdx | Removes large auto-generated property tables from encryption reference. |
| content/docs/references/system/core-services.mdx | Adds a new system reference page for core services. |
| content/docs/references/system/compliance.mdx | Removes large auto-generated property tables from compliance reference. |
| content/docs/references/system/change-management.mdx | Removes large auto-generated property tables from change-management reference. |
| content/docs/references/system/cache.mdx | Removes large auto-generated property tables from cache reference. |
| content/docs/references/system/auth-config.mdx | Removes large auto-generated property tables from auth-config reference. |
| content/docs/references/studio/plugin.mdx | Adds Studio plugin protocol reference page. |
| content/docs/references/studio/meta.json | Adds Studio section navigation metadata. |
| content/docs/references/studio/index.mdx | Adds Studio section index page with cards. |
| content/docs/references/shared/view.mdx | Removes allowed-values section from shared view reference. |
| content/docs/references/shared/metadata-types.mdx | Adds shared metadata types reference page. |
| content/docs/references/shared/metadata-persistence.mdx | Adds shared metadata persistence reference page. |
| content/docs/references/shared/meta.json | Adds new shared pages (enums/metadata-*). |
| content/docs/references/shared/mapping.mdx | Removes large auto-generated property tables from shared mapping reference. |
| content/docs/references/shared/index.mdx | Updates shared reference index cards to include new pages. |
| content/docs/references/shared/identifiers.mdx | Removes short inline descriptions under identifier headings. |
| content/docs/references/shared/http.mdx | Removes large auto-generated property tables from shared http reference. |
| content/docs/references/shared/enums.mdx | Adds shared enums reference page. |
| content/docs/references/security/territory.mdx | Removes large auto-generated property tables from territory reference. |
| content/docs/references/security/sharing.mdx | Removes large auto-generated property tables from sharing reference. |
| content/docs/references/security/rls.mdx | Removes large auto-generated property tables from rls reference. |
| content/docs/references/security/policy.mdx | Removes large auto-generated property tables from policy reference. |
| content/docs/references/security/permission.mdx | Removes large auto-generated property tables from permission reference. |
| content/docs/references/qa/testing.mdx | Removes large auto-generated property tables from testing reference. |
| content/docs/references/meta.json | Updates top-level references navigation to include Studio. |
| content/docs/references/kernel/startup-orchestrator.mdx | Removes large auto-generated property tables from startup-orchestrator reference. |
| content/docs/references/kernel/service-registry.mdx | Removes large auto-generated property tables from service-registry reference. |
| content/docs/references/kernel/plugin.mdx | Updates kernel plugin reference and TS usage snippet (adds ActivationEvent). |
| content/docs/references/kernel/plugin-versioning.mdx | Expands plugin-versioning reference and updates TS usage imports/sections. |
| content/docs/references/kernel/plugin-validator.mdx | Removes large auto-generated property tables from plugin-validator reference. |
| content/docs/references/kernel/plugin-structure.mdx | Removes large auto-generated property tables from plugin-structure reference. |
| content/docs/references/kernel/plugin-security.mdx | Updates plugin-security TS usage imports and adds new headings. |
| content/docs/references/kernel/plugin-security-advanced.mdx | Updates plugin-security-advanced content and corrects source path and schema names. |
| content/docs/references/kernel/plugin-runtime.mdx | Adds new kernel plugin runtime reference page. |
| content/docs/references/kernel/plugin-registry.mdx | Removes large auto-generated property tables from plugin-registry reference. |
| content/docs/references/kernel/plugin-lifecycle-events.mdx | Removes large auto-generated property tables from plugin-lifecycle-events reference. |
| content/docs/references/kernel/plugin-lifecycle-advanced.mdx | Removes large auto-generated property tables from plugin-lifecycle-advanced reference. |
| content/docs/references/kernel/plugin-capability.mdx | Removes large auto-generated property tables from plugin-capability reference. |
| content/docs/references/kernel/permission.mdx | Removes large auto-generated property table from kernel permission reference. |
| content/docs/references/kernel/package-registry.mdx | Removes large auto-generated property tables from kernel package-registry reference. |
| content/docs/references/kernel/meta.json | Updates kernel reference navigation ordering and includes new pages. |
| content/docs/references/kernel/manifest.mdx | Removes large auto-generated property table from kernel manifest reference. |
| content/docs/references/kernel/index.mdx | Adds cards for plugin-registry/runtime/security on kernel index. |
| content/docs/references/kernel/feature.mdx | Removes large auto-generated property tables from kernel feature reference. |
| content/docs/references/kernel/context.mdx | Removes large auto-generated property tables from kernel context reference. |
| content/docs/references/integration/object-storage.mdx | Removes large auto-generated property table from integration object-storage reference. |
| content/docs/references/integration/message-queue.mdx | Removes large auto-generated property tables from integration message-queue reference. |
| content/docs/references/integration/mapping.mdx | Removes large auto-generated property table from integration mapping reference. |
| content/docs/references/integration/http.mdx | Removes large auto-generated property table from integration http reference. |
| content/docs/references/identity/role.mdx | Removes large auto-generated property table from identity role reference. |
| content/docs/references/identity/organization.mdx | Removes large auto-generated property tables from identity organization reference. |
| content/docs/references/identity/identity.mdx | Removes large auto-generated property tables from identity reference. |
| content/docs/references/hub/tenant.mdx | Adds Hub tenant reference page. |
| content/docs/references/hub/registry-config.mdx | Adds Hub registry-config reference page. |
| content/docs/references/hub/plugin-security.mdx | Adds Hub plugin-security reference page. |
| content/docs/references/hub/plugin-registry.mdx | Adds Hub plugin-registry reference page. |
| content/docs/references/hub/meta.json | Adds Hub section navigation metadata. |
| content/docs/references/hub/license.mdx | Adds Hub license reference page. |
| content/docs/references/data/search-engine.mdx | Removes large auto-generated property table from data search-engine reference. |
| content/docs/references/data/metrics.mdx | Removes data metrics reference page. |
| content/docs/references/data/meta.json | Removes metrics from data reference navigation. |
| content/docs/references/data/mapping.mdx | Removes large auto-generated property tables from data mapping reference. |
| content/docs/references/data/hook.mdx | Removes large auto-generated property tables from data hook reference. |
| content/docs/references/data/filter.mdx | Removes large auto-generated property tables from data filter reference. |
| content/docs/references/data/external-lookup.mdx | Removes large auto-generated property tables from data external-lookup reference. |
| content/docs/references/data/driver.mdx | Removes large auto-generated property tables from data driver reference. |
| content/docs/references/data/driver-sql.mdx | Removes large auto-generated property tables from data driver-sql reference. |
| content/docs/references/data/document.mdx | Removes large auto-generated property tables from data document reference. |
| content/docs/references/data/datasource.mdx | Removes large auto-generated property tables from data datasource reference. |
| content/docs/references/data/dataset.mdx | Removes large auto-generated property tables from data dataset reference. |
| content/docs/references/data/analytics.mdx | Updates analytics TS usage and adds AggregationMetricType section; removes tables. |
| content/docs/references/automation/webhook.mdx | Removes large auto-generated property tables from automation webhook reference. |
| content/docs/references/automation/trigger-registry.mdx | Updates trigger-registry TS usage imports and removes tables. |
| content/docs/references/automation/sync.mdx | Removes large auto-generated property tables from automation sync reference. |
| content/docs/references/automation/state-machine.mdx | Removes large auto-generated union/options documentation from automation state-machine reference. |
| content/docs/references/automation/flow.mdx | Removes large auto-generated property tables from automation flow reference. |
| content/docs/references/automation/events.mdx | Removes large auto-generated property table from automation events reference. |
| content/docs/references/automation/etl.mdx | Removes large auto-generated property tables from automation etl reference. |
| content/docs/references/automation/connector.mdx | Updates connector TS usage snippet and removes Authentication section content. |
| content/docs/references/automation/approval.mdx | Removes large auto-generated property tables from automation approval reference. |
| content/docs/references/api/view.mdx | Removes allowed-values section from API view reference. |
| content/docs/references/api/versioning.mdx | Adds API versioning reference page. |
| content/docs/references/api/storage.mdx | Removes large auto-generated property tables from API storage reference. |
| content/docs/references/api/router.mdx | Removes large auto-generated property tables from API router reference. |
| content/docs/references/api/rest-server.mdx | Removes large auto-generated property tables from API rest-server reference. |
| content/docs/references/api/realtime.mdx | Updates realtime schema names in TS usage and removes tables. |
| content/docs/references/api/plugin-rest-api.mdx | Adds REST API plugin protocol reference page. |
| content/docs/references/api/package-registry.mdx | Removes large auto-generated property tables from API package-registry reference. |
| content/docs/references/api/odata.mdx | Removes large auto-generated property tables from API odata reference. |
| content/docs/references/api/object.mdx | Adds API object reference page (currently uses VersioningConfig in TS snippet). |
| content/docs/references/api/metadata.mdx | Removes large auto-generated property tables from API metadata reference. |
| content/docs/references/api/meta.json | Updates API reference navigation ordering and adds new pages (dispatcher/object/plugin-rest-api/versioning). |
| content/docs/references/api/index.mdx | Updates API reference index cards and removes Hub card; adds new cards. |
| content/docs/references/api/identity.mdx | Removes large auto-generated property table from API identity reference. |
| content/docs/references/api/http-cache.mdx | Removes large auto-generated property tables from API http-cache reference. |
| content/docs/references/api/endpoint.mdx | Removes large auto-generated property tables from API endpoint reference. |
| content/docs/references/api/dispatcher.mdx | Adds HttpDispatcher reference page. |
| content/docs/references/api/discovery.mdx | Updates discovery TS usage imports and sections; removes tables. |
| content/docs/references/api/contract.mdx | Removes large auto-generated property tables from API contract reference. |
| content/docs/references/api/connector.mdx | Removes retry-strategy allowed-values section from API connector reference. |
| content/docs/references/api/batch.mdx | Removes large auto-generated property tables from API batch reference. |
| content/docs/references/api/auth.mdx | Removes large auto-generated property tables from API auth reference. |
| content/docs/references/api/analytics.mdx | Removes large auto-generated property tables from API analytics reference. |
| content/docs/references/ai/plugin-development.mdx | Removes large auto-generated property tables from AI plugin-development reference. |
| content/docs/references/ai/meta.json | Adds MCP to AI reference navigation. |
| content/docs/references/ai/mcp.mdx | Adds new MCP protocol reference page. |
| content/docs/references/ai/index.mdx | Adds MCP card to AI reference index. |
| content/docs/references/ai/feedback-loop.mdx | Removes large auto-generated property tables from feedback-loop reference. |
| content/docs/references/ai/agent.mdx | Removes large auto-generated property tables from AI agent reference. |
| apps/docs/tsconfig.json | Modernizes TS config (baseUrl, ESNext target, casing enforcement). |
| apps/docs/tailwind.config.js | Removes Tailwind config (Tailwind v4 CSS-first approach). |
| apps/docs/source.config.ts | Updates source config to use pageSchema/metaSchema and enable processed markdown. |
| apps/docs/postcss.config.mjs | Removes autoprefixer from PostCSS config. |
| apps/docs/package.json | Pins versions, adds postinstall and types:check, removes unused deps. |
| apps/docs/next.config.mjs | Removes webpack alias hacks and adds rewrite for .mdx LLM endpoint. |
| apps/docs/mdx-components.tsx | Renames MDX component helper to getMDXComponents. |
| apps/docs/lib/utils.ts | Simplifies cn utility to a twMerge re-export. |
| apps/docs/lib/source.ts | Adds new source loader with lucide plugin and LLM/OG helpers. |
| apps/docs/lib/layout.shared.tsx | Introduces shared layout options and git config for links/actions. |
| apps/docs/components/ui/button.tsx | Removes unused UI button component. |
| apps/docs/components/ui/badge.tsx | Removes unused UI badge component. |
| apps/docs/app/source.ts | Moves docs/blog source loader from app/ to lib/. |
| apps/docs/app/og/docs/[...slug]/route.tsx | Adds OG image generation route for docs pages. |
| apps/docs/app/llms.txt/route.ts | Adds llms.txt listing for docs pages. |
| apps/docs/app/llms.mdx/docs/[[...slug]]/route.ts | Adds per-page markdown export route for LLMs. |
| apps/docs/app/llms-full.txt/route.ts | Adds full-site markdown export route for LLMs. |
| apps/docs/app/layout.tsx | Updates root layout to own <html>/<body> and applies base body styles. |
| apps/docs/app/layout.config.tsx | Moves shared layout config into lib/. |
| apps/docs/app/global.css | Updates CSS imports to Fumadocs neutral/preset styles. |
| apps/docs/app/api/search/route.ts | Migrates search API to createFromSource(source). |
| apps/docs/app/[lang]/page.tsx | Updates home page to use new shared base options. |
| apps/docs/app/[lang]/layout.tsx | Removes nested <html>/<body> wrapper and keeps provider only. |
| apps/docs/app/[lang]/docs/layout.tsx | Migrates docs layout to use new lib/source and shared layout options. |
| apps/docs/app/[lang]/docs/[[...slug]]/page.tsx | Migrates docs page rendering to new layout components and adds AI page actions. |
| apps/docs/app/[lang]/blog/[[...slug]]/page.tsx | Updates blog rendering to use new shared layout options and MDX component helper. |
Comments suppressed due to low confidence (1)
apps/docs/app/layout.tsx:1
- The root
<html lang>is now hard-coded toen, while[lang]/layout.tsxno longer renders<html lang={lang}>. This breaks correct language metadata for non-English locales (SEO/screen readers/translation tools). Consider deriving the active locale inRootLayout(e.g., from a locale cookie/header set by middleware) and setting<html lang={locale}>accordingly.
import './global.css';
| <Card href="/docs/references/system/change-management" title="Change Management" description="Source: packages/spec/src/system/change-management.zod.ts" /> | ||
| <Card href="/docs/references/system/collaboration" title="Collaboration" description="Source: packages/spec/src/system/collaboration.zod.ts" /> | ||
| <Card href="/docs/references/system/compliance" title="Compliance" description="Source: packages/spec/src/system/compliance.zod.ts" /> | ||
| <Card href="/docs/references/system/core-services" title="Core Services" description="Source: packages/spec/src/system/core-services.zod.ts" /> |
There was a problem hiding this comment.
The System reference index links to /references/system/registry-config and /references/system/tenant, but this PR adds those pages under content/docs/references/hub/* (not system/*). This will produce broken links/404s. Fix by either moving/adding the missing system/registry-config.mdx and system/tenant.mdx, or updating these cards to point to the Hub pages (e.g. /docs/references/hub/registry-config, /docs/references/hub/tenant).
| <Card href="/docs/references/system/encryption" title="Encryption" description="Source: packages/spec/src/system/encryption.zod.ts" /> | ||
| <Card href="/docs/references/system/http-server" title="Http Server" description="Source: packages/spec/src/system/http-server.zod.ts" /> | ||
| <Card href="/docs/references/system/job" title="Job" description="Source: packages/spec/src/system/job.zod.ts" /> | ||
| <Card href="/docs/references/system/license" title="License" description="Source: packages/spec/src/system/license.zod.ts" /> |
There was a problem hiding this comment.
The System reference index links to /references/system/registry-config and /references/system/tenant, but this PR adds those pages under content/docs/references/hub/* (not system/*). This will produce broken links/404s. Fix by either moving/adding the missing system/registry-config.mdx and system/tenant.mdx, or updating these cards to point to the Hub pages (e.g. /docs/references/hub/registry-config, /docs/references/hub/tenant).
| <Card href="/docs/references/system/registry-config" title="Registry Config" description="Source: packages/spec/src/system/registry-config.zod.ts" /> | ||
| <Card href="/docs/references/system/search-engine" title="Search Engine" description="Source: packages/spec/src/system/search-engine.zod.ts" /> | ||
| <Card href="/docs/references/system/service-registry" title="Service Registry" description="Source: packages/spec/src/system/service-registry.zod.ts" /> | ||
| <Card href="/docs/references/system/tenant" title="Tenant" description="Source: packages/spec/src/system/tenant.zod.ts" /> |
There was a problem hiding this comment.
The System reference index links to /references/system/registry-config and /references/system/tenant, but this PR adds those pages under content/docs/references/hub/* (not system/*). This will produce broken links/404s. Fix by either moving/adding the missing system/registry-config.mdx and system/tenant.mdx, or updating these cards to point to the Hub pages (e.g. /docs/references/hub/registry-config, /docs/references/hub/tenant).
| "qa", | ||
| "security", | ||
| "shared", | ||
| "studio", | ||
| "system", | ||
| "ui", | ||
| "quick-reference" |
There was a problem hiding this comment.
This PR introduces a new content/docs/references/hub/ section (with its own meta.json and pages), but the top-level references navigation does not include hub. As a result, the Hub protocol pages won't appear in the references sidebar/nav. Add \"hub\" to this list (and consider adding a content/docs/references/hub/index.mdx like Studio for a proper landing page).
| { params }: { params: Promise<{ slug: string[] }> }, | ||
| ) { | ||
| const { slug } = await params; |
There was a problem hiding this comment.
In Next.js route handlers, params is already a plain object; typing it as Promise<...> and await-ing it is unnecessary and makes the handler signature misleading. Prefer { params }: { params: { slug: string[] } } and remove the await.
| { params }: { params: Promise<{ slug: string[] }> }, | |
| ) { | |
| const { slug } = await params; | |
| { params }: { params: { slug: string[] } }, | |
| ) { | |
| const { slug } = params; |
| { params }: { params: Promise<{ slug?: string[] }> }, | ||
| ) { | ||
| const { slug } = await params; |
There was a problem hiding this comment.
Same issue as the OG route: params in route handlers is not a Promise. Please update the type to a plain object and drop the await to keep the handler idiomatic and easier to follow.
| { params }: { params: Promise<{ slug?: string[] }> }, | |
| ) { | |
| const { slug } = await params; | |
| { params }: { params: { slug?: string[] } }, | |
| ) { | |
| const { slug } = params; |
| const scan = source.getPages().map(getLLMText); | ||
| const scanned = await Promise.all(scan); | ||
|
|
||
| return new Response(scanned.join('\n\n')); |
There was a problem hiding this comment.
This endpoint returns plain text/markdown but does not set a Content-Type. Add an explicit response header (e.g. text/plain; charset=utf-8 or text/markdown; charset=utf-8) to avoid ambiguous content sniffing by clients.
| return new Response(scanned.join('\n\n')); | |
| return new Response(scanned.join('\n\n'), { | |
| headers: { | |
| 'Content-Type': 'text/plain; charset=utf-8', | |
| }, | |
| }); |
| </Callout> | ||
|
|
||
| ## TypeScript Usage | ||
|
|
There was a problem hiding this comment.
This api/object.mdx page appears to be documenting packages/spec/src/api/object.zod.ts, but the TypeScript usage snippet only references VersioningConfig. If the intent is to document the API Object schema, the snippet and the ## section heading below should reference the object schema/export(s) from api/object.zod.ts (or the page should be renamed if VersioningConfig is the actual subject).
Expand reference docs with explicit Properties / Allowed Values tables for many schemas (AI, conversation, cost, API, automation, data, identity, integration, kernel, system, UI, etc.), including union/option breakdowns and enum lists for message, action, and budget types. Remove several hub reference files under content/docs/references/hub. Update packages/spec/scripts/build-docs.ts to accommodate the documentation changes. These edits improve discoverability of fields and make the API/AI schemas more explicit for consumers.
Aligns the docs app scaffolding with the current
pnpm create fumadocs-appoutput while preserving all existing customizations (i18n, custom homepage, blog, middleware).Config modernization
pageSchema/metaSchemafromfumadocs-core/source/schema, enableincludeProcessedMarkdownfor LLM supportrewritesfor per-page.mdxLLM endpointspostinstall: "fumadocs-mdx"for.sourcegeneration, drop unused deps (clsx,class-variance-authority,autoprefixer,client-only,server-only)fumadocs-ui/css/neutral.css+preset.cssreplacesfumadocs-ui/style.cssbaseUrl,ESNexttarget, dropsource.config.tsexcludeautoprefixer(Tailwind v4)Structural migration
app/source.ts→lib/source.tswithlucideIconsPlugin,getPageImage,getLLMTextapp/layout.config.tsx→lib/layout.shared.tsx(baseOptions()function +gitConfig)mdx-components.tsx:useMDXComponents→getMDXComponentslib/utils.ts:cnsimplified totwMergere-exportDocsTitle/DocsDescription/DocsBodyfromfumadocs-ui/layouts/docs/page,createRelativeLinkfor MDX linkscreateFromSource(source)replacescreateSearchAPI('simple', ...)<html>/<body>;[lang]/layout.tsxprovides only<RootProvider>New features from latest template
/llms.txt,/llms-full.txt,/docs/:path*.mdx(via rewrite to/llms.mdx/docs/:path*)/og/docs/[...slug]usingfumadocs-ui/ogcomponents/ai/page-actions.tsx— Copy Markdown, Open in ChatGPT/Claude/GitHubCleanup
components/ui/badge.tsx,components/ui/button.tsx(zero imports)Build verified: 660 static pages generated, all existing + new routes functional.
Warning
Firewall rules blocked me from connecting to one or more addresses (expand for details)
I tried to connect to the following addresses, but was blocked by firewall rules:
fonts.googleapis.com/home/REDACTED/work/_temp/ghcca-node/node/bin/node node /home/REDACTED/work/spec/spec/apps/docs/node_modules/.bin/../next/dist/bin/next build git conf�� unset rom Create Fumadocs App 4@0.27.2/node_modules/@esbuild/linux-x64/bin/esbuild user.name(dns block)If you need me to access, download, or install something from one of these locations, you can either:
💬 We'd love your input! Share your thoughts on Copilot coding agent in our 2 minute survey.