infinite-canvas 文档站技术指南：基于 Fumadocs 与 Next.js 的 MDX 文档系统架构与部署

AI 应用媒体生成前端AI AgentAI 技能【免费下载链接】infinite-canvas面向 AI 创作的开源无限画布工作台集成 AI 生图、参考图编辑、视频生成、Agent 智能助手、画布编排、对话创作、提示词库与素材管理等能力支持可视化创作流程与多 Agent 协同工作。兼容 OpenAI 接口生态支持 chatgpt2api、grok2api、flow2api、newapi 等渠道接入。项目地址https://gitcode.com/gh_mirrors/infinit/infinite-canvas点击查看免费下载导读本文以 docs/README.md 为核心系统讲解 infinite-canvas 开源项目中文档站docs/目录的整体架构、路由组织、内容加载机制以及从本地开发到 Docker 部署的完整流程。该文档站基于 Fumadocs 与 Next.js 构建采用服务端渲染与独立standalone输出模式负责承载项目的中英文产品文档、开发指南与进度规划等内容。读完本文你将掌握这套 MDX 文档系统的目录结构、loader()内容源适配原理、搜索与 LLM 文本路由的实现方式并能独立完成文档站的本地调试、构建与容器化部署。一、文档站技术栈与总体架构docs/是 infinite-canvas 仓库中独立于主应用web/的文档子系统由 Create Fumadocs 可以看到其核心依赖next16.2.6—— 服务端渲染框架与路由承载fumadocs-core16.9.3—— 内容源、搜索、i18n 等核心逻辑fumadocs-mdx15.0.10—— MDX 内容编译与集合collections机制fumadocs-ui16.9.3—— 文档布局、侧边栏、导航等 UI 组件orama/orama^3.1.18—— 本地全文搜索索引引擎tailwindcss^4.3.0与postcss—— 样式体系。架构上它有四个关键特征服务端文档站点文档页面由 Next.js 在服务端渲染而非纯静态导出。Standalone 独立输出next.config.mjs中显式设置了output: standalone将构建产物自包含化便于在容器内仅用node server.js启动。运行时 Route Handler 可用搜索接口、LLM 文本接口等路由处理器Route Handler在运行时依然生效不会因构建方式改变而失效。中英文双语通过 docs/src/lib/i18n.ts 定义en与zh-CN两种语言默认语言为en采用dot命名空间解析方式并通过hideLocale: default-locale隐藏默认语言前缀。从源码结构看文档内容主体位于 docs/content/docs 目录下按overview、canvas、business、development、progress、support六个业务分类组织每个分类下都同时存在.mdx与.zh-CN.mdx双语版本以及meta.json/meta.zh-CN.json元数据文件共同构成站点导航树与页面内容。二、目录结构与关键文件职责docs/目录中几个核心文件承担着不同职责理解它们有助于快速定位问题文件职责next.config.mjs启用 MDX 编译插件配置standalone输出与/、/docs/:path*到/en的 URL 重写source.config.ts通过defineDocs声明内容集合collections与 frontmatter schemasrc/lib/source.ts内容源适配器loader()提供访问内容的统一接口src/lib/layout.shared.tsx布局共享选项含站点名、导航链接与 UI 文案国际化src/lib/i18n.ts语言定义与路径本地化工具函数src/app/api/search/route.ts站内全文搜索的 Route Handlersrc/app/llms.txt/route.ts面向 LLM 的llms.txt聚合文本接口Dockerfile多阶段构建镜像将 standalone 产物打包为可运行容器docker-compose.yml/docker-compose.local.yml拉取发布镜像 / 本地构建镜像的编排配置其中 docs/next.config.mjs 值得展开说明import { createMDX } from fumadocs-mdx/next; const withMDX createMDX(); /** type {import(next).NextConfig} */ const config { output: standalone, reactStrictMode: true, async rewrites() { return [ { source: /, destination: /en }, { source: /docs/:path*, destination: /en/docs/:path* }, ]; }, }; export default withMDX(config);createMDX()将 MDX 编译能力注入 Next.js 构建链output: standalone使.next/standalone目录包含完整的服务端运行环境两条 rewrite 规则把根路径和/docs/*统一指向默认语言英文的对应页面保证默认语言用户无需在 URL 中携带语言前缀。三、本地开发一条命令启动文档站文档站要求使用 Bun 作为包管理器与运行时docs/bun.lock为锁文件Dockerfile亦以oven/bun:1.3.13作为构建阶段镜像。启动开发服务器的命令为bun run dev该命令实际执行next dev见 docs/package.json 的 scripts启动后即可访问文档站并实时预览 MDX 内容改动。需要注意两个安装细节package.json中定义了postinstall: fumadocs-mdx即安装依赖后会自动执行 MDX 内容编译生成.source相关产物安装后无需手动触发仓库根目录的skills-lock.json、各子包锁文件表明整个 monorepo 以 lockfile 约束依赖版本安装时应使用bun install --frozen-lockfile保证可复现。四、构建与本地生产运行文档站支持标准的构建-运行两步流程bun run build bun run startbun run build执行next build先生成 MDX 内容产物再产出包含standalone自包含服务端应用的.next目录bun run start执行next start以生产模式启动服务供本地验证构建产物。如需在 CI 或部署前做类型与配置检查可使用bun run types:check该命令会依次执行fumadocs-mdx next typegen tsc --noEmit对内容集合类型、Next.js 路由类型与 TypeScript 代码做完整校验。五、Docker 部署镜像发布与本地构建两种方式5.1 直接使用发布镜像docs/docker-compose.yml 定义了从容器镜像仓库拉取最新发布镜像并启动文档站的编排services: docs: image: ghcr.io/basketikun/infinite-canvas-docs:latest ports: - 3001:3000 restart: unless-stopped运行命令docker compose up -d容器将宿主机的3001端口映射到容器内3000端口restart: unless-stopped保证异常退出后自动重启。该方式适合生产环境快速上线无需本地构建。5.2 本地源码构建镜像docs/docker-compose.local.yml 则使用本地源码构建镜像services: docs: build: context: .. dockerfile: docs/Dockerfile ports: - 3001:3000 restart: unless-stopped运行命令docker compose -f docker-compose.local.yml up -d --build注意这里context是仓库根目录..相对docs/而言因此构建时会把整个仓库作为上下文交给docs/Dockerfile适合开发者验证最新代码或离线环境部署。5.3 Dockerfile 的多阶段构建细节docs/Dockerfile 采用两阶段构建构建阶段基于oven/bun:1.3.13先仅复制package.json与bun.lock并利用构建缓存执行bun install --frozen-lockfile --ignore-scripts再复制源码、CHANGELOG.md依次执行bun run postinstall与bun run build运行阶段基于node:22-bookworm-slim设置NODE_ENVproduction、HOSTNAME0.0.0.0、PORT3000创建非 root 的nextjs用户仅复制构建产物public、content、.source、source.config.ts、.next/standalone、.next/static等最后以node server.js启动。该镜像刻意只携带运行所需的最小文件集并以普通用户运行兼顾镜像体积与安全性HOSTNAME0.0.0.0确保容器内服务可被外部访问。六、内容源适配器loader()与source.tsdocs/src/lib/source.ts 是 README 重点点名的内容源适配器负责把 MDX 集合转换为可供页面与搜索消费的查询接口import { docs } from collections/server; import { loader } from fumadocs-core/source; import { docsContentRoute, docsRoute } from ./shared; import { i18n } from ./i18n; export const source loader({ baseUrl: docsRoute, source: docs.toFumadocsSource(), i18n, plugins: [], });loader()的入参来源可追溯到 docs/source.config.tsexport const docs defineDocs({ dir: content/docs, docs: { schema: pageSchema, postprocess: { includeProcessedMarkdown: true, }, }, meta: { schema: metaSchema, }, });即内容目录固定为content/docsfrontmatter 采用fumadocs-core/source/schema提供的pageSchema/metaSchema做校验并开启includeProcessedMarkdown以保留处理后的 Markdown 文本——这正是 LLM 文本接口的数据基础。source.ts还导出了两个上层封装函数getPageMarkdownUrl(page)根据页面 slug 与语言拼出对应 Markdown 源文件的下载路径/llms.mdx/docs/...供查看 Markdown功能使用getLLMText(page)读取页面处理后的纯文本拼装为# 标题 (URL) 正文的格式供 LLM 接口输出。从源码结构看docsRoute /docs与docsContentRoute /llms.mdx/docs两个常量定义在 docs/src/lib/shared.ts 中页面 URL 与内容下载 URL 因此是解耦的两套路径体系。七、布局共享与站点导航docs/src/lib/layout.shared.tsx 提供各页面布局共用的选项README 中注明它可选但建议保留因为导航与文案一旦分散到各页面将难以维护。该文件的核心内容分两部分UI 文案国际化通过i18n.translations().extend(uiTranslations())在 Fumadocs 官方文案基础上补充中文翻译搜索、目录、主题切换、复制代码等 UI 术语保证中文界面完整本地化。baseOptions(locale)布局选项根据语言返回导航配置——站点名称Infinite Canvas/无限画布与 Logo、指向/docs/overview/quick-start的文档导航入口、在线体验外链以及菜单中的 GitHub / QQ 图标链接。实际使用时docs/src/app/[lang]/docs/layout.tsx 将baseOptions(lang)与source.getPageTree(lang)生成的文档树一起传给DocsLayout并注入DocsSidebarTabs/DocsTopTabs分区标签最终形成完整的文档页布局。八、路由结构速查README 给出了路由组织速查表结合源码可归纳如下路由说明app/(home)落地页landing page路由组位于 docs/src/app/[lang]/(home)app/docs文档布局与页面位于 docs/src/app/[lang]/docsapp/api/search/route.ts搜索接口 Route Handler位于 docs/src/app/api/search/route.tsapp/llms.txt/route.ts面向 LLM 的聚合文本接口app/llms.mdx/docs/[[...slug]]/route.tsMarkdown 源文件下载接口app/llms-full.txt/route.ts全量 LLM 文本接口另外从 docs/src/app/[lang]/layout.tsx 与(home)目录结构可以推断语言前缀路由[lang]是整个站点的顶层组织方式en与zh-CN共用一套页面组件、按 locale 参数加载不同内容。九、站内搜索的实现原理docs/src/app/api/search/route.ts 是搜索功能的实际载体export const revalidate false; export const { staticGET: GET } createFromSource(source, { localeMap: { en: { language: english, }, zh-CN: { components: { tokenizer: createDocsSearchTokenizer(), }, }, }, });要点有三基于 Fumadocs 的createFromSource直接消费上文loader()生成的内容源无需单独维护索引数据revalidate false表明搜索索引在构建期生成、运行期不再重新验证属于静态路由处理器中文搜索通过 docs/src/lib/search-tokenizer.ts 提供的createDocsSearchTokenizer()自定义分词器以解决中文无空格分词问题底层索引引擎为orama/orama。前端侧docs/src/components/search.tsx 调用该接口并展示搜索结果配合layout.shared.tsx中搜索文档 / 没有找到结果等中文提示完成交互闭环。十、面向 LLM 与 Agent 的文本接口文档站不只是给人看的也面向大模型与检索 Agent 提供机器可读的聚合文本。以 docs/src/app/llms.txt/route.ts 为例export async function GET(request: Request) { const locale new URL(request.url).searchParams.get(locale) ?? en; const docsIndex await readFile(join(process.cwd(), locale zh-CN ? index.zh-CN.md : index.md), utf8); return new Response([docsIndex, llms(source).index(locale)].join(\n\n)); }该接口拼接两层内容根目录下由人工维护的index.md/index.zh-CN.md总览以及fumadocs-core/source提供的llms(source)按语言生成的文档索引每条目对应页面标题与 URL。请求方可通过?localezh-CN获取中文聚合版本。配合source.ts中的getLLMText()与getPageMarkdownUrl()llms.mdx与llms-full.txt路由分别提供单页处理文本与全量文本构成了完整的 LLM 可读内容管线——这也与仓库根目录 skills-lock.json 及plugins/infinite-canvas/skills/中面向 AI Agent 的技能说明相互呼应共同服务于 AI 创作工作台的文档生态。十一、Fumadocs MDX 与 frontmatter 定制source.config.ts是 Fumadocs MDX 的配置入口README 提示可在此定制 frontmatter schema 等选项。当前仓库的配置即展示了两类可扩展点页面 schemadocs.schema pageSchema如需为页面增加自定义 frontmatter 字段如tags、readingTime可基于pageSchema扩展pageSchema.extend({ ... })meta schemameta.schema metaSchema控制meta.json的字段校验影响侧边栏分类的排序与展示mdxOptionsdefineConfig中的mdxOptions字段可注入额外的 remark/rehype 插件扩展 Markdown 渲染能力。内容侧的 frontmatter 由各meta.json与 MDX 文件的头部字段承载例如docs/content/docs/overview/meta.json定义了该分类在导航中的名称与顺序。修改 schema 后需重新执行bun run types:check验证类型一致性。十二、部署架构小结与排查建议综合上述内容文档站从源码到线上服务的完整链路为docs/content/docs (MDX 双语内容) │ fumadocs-mdx 编译postinstall / build ▼ source.config.ts → collections → loader() 内容源 │ ├─ 页面路由app/[lang]/docs/[...slug] SSR 渲染 ├─ 搜索app/api/search/route.ts构建期静态索引 ├─ LLM 文本llms.txt / llms.mdx / llms-full.txt └─ Markdown 下载llms.mdx/docs/[[...slug]] │ ▼ next buildstandalone→ Docker 多阶段镜像 → docker compose 启动端口 3001:3000常见问题排查建议本地启动报 MDX 相关错误先确认已执行bun install触发 postinstall 生成内容产物或手动运行bun run postinstall修改 frontmatter schema 后类型报错运行bun run types:check重新生成类型新增文档分类不显示在导航检查对应目录是否包含meta.json中文还需meta.zh-CN.json且文件名与[lang]路由约定一致生产容器无法访问确认宿主机端口映射默认3001与容器PORT3000、HOSTNAME0.0.0.0配置未被覆盖。本文所有命令与配置均以当前仓库 docs/README.md、docs/package.json、docs/next.config.mjs、docs/Dockerfile 及 docs/src 源码为准可直接在本地仓库中对照验证与实操。赞分享AI 应用媒体生成前端AI AgentAI 技能【免费下载链接】infinite-canvas面向 AI 创作的开源无限画布工作台集成 AI 生图、参考图编辑、视频生成、Agent 智能助手、画布编排、对话创作、提示词库与素材管理等能力支持可视化创作流程与多 Agent 协同工作。兼容 OpenAI 接口生态支持 chatgpt2api、grok2api、flow2api、newapi 等渠道接入。项目地址https://gitcode.com/gh_mirrors/infinit/infinite-canvas点击查看免费下载相关推荐open-slide 官方文档站apps/web架构解析基于 Next.js 与 Fumadocs 的 MDX 文档系统运行指南open slide 官方文档站apps/web架构解析基于 Next.js 与 Fumadocs 的 MDX 文档系统运行指南 本指南围绕 open sSuperagent 文档站技术解析基于 Next.js 与 Fumadocs 的 MDX 文档工程实践Superagent 文档站技术解析基于 Next.js 与 Fumadocs 的 MDX 文档工程实践 Superagent 是一个面向 AI AgentAI 安全治理应用安全MCP 服务AI AgentOpenUI 文档站点架构解析基于 Next.js 与 Fumadocs 构建 SDK 技术文档OpenUI 文档站点架构解析基于 Next.js 与 Fumadocs 构建 SDK 技术文档 OpenUI 是面向 Generative UI 的开源标准上一篇清华PPT模板终极指南3分钟打造专业学术演示文稿下一篇Cangaroo终极指南从零构建专业的CAN总线分析环境创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考