Documenso 文档站深度解析基于 Next.js 与 Fumadocs 的 MDX 内容管线与 LLM 友好输出【免费下载链接】documensoThe Open Source DocuSign Alternative.项目地址: https://gitcode.com/GitHub_Trending/do/documensoDocumenso 的官方文档站发布在 docs.documenso.com是独立于主应用的 monorepo 子包用 Next.js 与 Fumadocs 技术栈将content/docs/下的 MDX 内容编译为多栏文档站点。本文以 apps/docs/README.md 为核心骨架结合该应用的真实源码完整讲清文档站的目录结构、内容源适配器、侧边栏分区机制、MDX 渲染管线以及 llms.txt / llms-full.txt 等面向搜索引擎与 LLM 的可检索输出实现读完你既能本地跑起文档站也能理解一个生产级 Fumadocs 站点的关键配置。快速上手本地运行文档站文档站包名为documenso/docsREADME 给出的唯一启动命令就是从 monorepo 根目录执行# From the monorepo root npm run dev --filterdocumenso/docs--filter是 npm workspaces 语法只启动该子包对应的next dev。查看 apps/docs/package.json 可以确认各脚本的底层行为脚本实际执行说明devnext dev开发模式buildnext build静态构建配合generateStaticParams预渲染全部文档页startnext start启动生产构建postinstallfumadocs-mdx安装后生成 MDX 类型定义types:checkfumadocs-mdx next typegen tsc --noEmit先重新生成 MDX 类型再生成 Next.js 路由类型最后做类型检查值得注意的是postinstall钩子每次npm install后都会自动运行fumadocs-mdx代码生成器扫描 MDX 内容并产出页面类型定义这也是PageProps/docs/[[...slug]]这类精确路由类型可用的前提。依赖侧的核心是三个 Fumadocs 包fumadocs-core、fumadocs-mdx、fumadocs-ui均为 16.x 版本线再配合 Next.js 16、React 19 与 Tailwind CSS 4见 apps/docs/package.json。站点结构总览README 列出了文档站的三大结构支柱逐一对照仓库即可验证content/docs/全部文档页面以 MDX 组织。该目录目前包含 143 个.mdx页面与 30 个meta.jsonFumadocs 的目录元数据文件用于自定义侧边栏分组、排序与图标lib/source.ts内容源适配器是整站读取内容的唯一入口实际位于 apps/docs/src/lib/source.tslib/layout.shared.tsx共享布局配置实际位于 apps/docs/src/lib/layout.shared.tsx。围绕这三者src/app/下按 Next.js App Router 组织了完整的渲染层apps/docs/src/app/ ├── (home)/ # 文档站首页 ├── docs/[[...slug]]/ # 文档页面catch-all 路由 ├── llms.txt/ # 全站页面索引LLM 入口 ├── llms-full.txt/ # 全站完整 Markdown 文本 ├── llms.mdx/docs/ # 单页原始 Markdown 端点 ├── og/docs/[...slug]/ # 每页 OG 分享图动态生成 └── api/search/ # 搜索 API其中docs/[[...slug]]/page.tsx是文档页核心通过source.getPage(params.slug)按 slug 取页取不到即notFound()并用generateStaticParams()让构建期预渲染全部页面见 apps/docs/src/app/docs/[[...slug]]/page.tsx。页面头部还挂了两个 LLM 相关组件——LLMCopyButton与ViewOptions前者生成${page.url}.mdx地址供一键复制/下载 Markdown后者拼出源码编辑链接指向contentPath: apps/docs/content/docs的对应 mdx 文件见 page.tsx。内容收集配置source.config.tsFumadocs 的内容收集逻辑定义在 apps/docs/source.config.ts这是fumadocs-mdx代码生成器的入口配置import { remarkMdxMermaid } from fumadocs-core/mdx-plugins; import { defineConfig, defineDocs, frontmatterSchema, metaSchema } from fumadocs-mdx/config; export const docs defineDocs({ dir: content/docs, // MDX 内容根目录 docs: { schema: frontmatterSchema, // frontmatter 字段校验 postprocess: { includeProcessedMarkdown: true, // 保留处理后的 Markdown 文本 }, }, meta: { schema: metaSchema, // meta.json 结构校验 }, }); export default defineConfig({ mdxOptions: { remarkPlugins: [remarkMdxMermaid], // MDX 内支持 Mermaid 流程图 }, });两个关键细节postprocess.includeProcessedMarkdown: truesource.config.ts#L10-L12会让每页额外保留一份“处理后的 Markdown”副本这正是后文 llms.txt 系列端点能吐出纯文本的基础而不仅仅是渲染后的 HTML。remarkMdxMermaid插件source.config.ts#L19-L23使 MDX 中可以直接写 Mermaid 图表代码块渲染时交给自定义组件处理下文 MDX 管线部分展开。frontmatter 与meta.json均使用 Fumadocs 内置 Zod schemafrontmatterSchema/metaSchema意味着title、description、toc等字段在代码生成阶段就被静态校验写错字段会在npm run types:check时报错。内容源适配器lib/source.tsapps/docs/src/lib/source.ts 是全站数据的单一出口export const source loader({ baseUrl: /docs, // 所有文档页挂载在 /docs 前缀下 source: docs.toFumadocsSource(), // 把收集的 MDX 数据源交给 loader plugins: [lucideIconsPlugin()], // 支持 frontmatter 中用字符串引用 lucide 图标 });baseUrl: /docs决定了 URL 形态content/docs/users/documents.mdx对应/docs/users/documents与首页根路径互不冲突lucideIconsPlugin允许在meta.json中直接写图标名而不必 import 组件。侧边栏分区过滤getFilteredPageTree文档站把内容分成三大根分区Users / Developers / Self-Hosting外加三个共享分区。source.ts用getFilteredPageTree实现了“进入某分区时侧边栏只显示该分区内容 共享资源”的逻辑source.ts#L13-L63// 所有主分区侧边栏都应出现的共享小节 const SHARED_SECTIONS [concepts, compliance, policies]; const SECTION_TITLES: Recordstring, string { users: User Guide, developers: Developer Guide, self-hosting: Self-Hosting Guide, };函数先按名字找到目标根文件夹再从整棵树中过滤出共享文件夹最终拼装成[主分区分隔条, ...主分区子节点, Resources 分隔条, ...共享文件夹]的新树。找不到目标文件夹时直接返回完整树兜底。调用侧在 apps/docs/src/app/docs/layout.tsx解析pathname第二段命中ROOT_SECTIONSusers / developers / self-hosting就用过滤树否则展示完整树同时侧边栏顶部渲染SectionSwitcher让用户在三大会话间快速切换const ROOT_SECTIONS [ { id: users, label: Users, subtitle: Send and sign documents, href: /docs/users }, { id: developers, label: Developers, subtitle: API and integrations, href: /docs/developers }, { id: self-hosting, label: Self-Hosting, subtitle: Deploy your own instance, href: /docs/self-hosting }, ];页面图片与 LLM 文本的两个辅助函数同一文件还提供两个被路由层复用的工具函数getPageImagesource.ts#L65-L72按页面 slug 拼出/og/docs/.../image.png供文档页的generateMetadata生成 OpenGraph / Twitter 卡片图动态路由实现在src/app/og/docs/[...slug]/route.tsxgetLLMTextsource.ts#L74-L80调用page.data.getText(processed)取出处理后的 Markdown再补一个# 标题首行——这正是 llms 端点的文本生产函数。MDX 渲染管线next.config.mjs顶部用createMDX()包裹整个 Next 配置启用fumadocs-mdx/next的编译集成next.config.mjs#L1-L3。页面渲染时MDX 组件由 apps/docs/src/mdx-components.tsx 统一提供export function getMDXComponents(components?: MDXComponents): any { return { ...defaultMdxComponents, // Fumadocs 内置组件Alert、Steps 等 ...TabsComponents, // 多语言代码 Tab Mermaid, // 配合 remarkMdxMermaid 插件渲染图表 EnvelopeWarning, // 文档专用的自定义警告块 ...components, }; }自定义的Mermaid组件src/components/mdx/mermaid.tsx让source.config.ts注册的remarkMdxMermaid插件真正落地MDX 中的 Mermaid 代码块被转成Mermaid组件再在浏览器端用 mermaid 库绘制这样文档可以内嵌流程图而不影响 SSR。EnvelopeWarning则是针对 Documenso 文档中“Envelope 相关功能”语义的专用警告组件。布局品牌则由 apps/docs/src/lib/layout.shared.tsx 的baseOptions()提供导航栏标题内嵌 Documenso 的 SVG logo并配置了仓库入口地址供 Fumadocs UI 的头部链接使用。面向 LLM 与 Agent 的可检索输出这是文档站最有工程价值的设计同一份 MDX 内容除 HTML 页面外还以纯文本形式暴露让搜索引擎爬虫和 LLM/Agent 能以最小上下文代价获取文档。llms.txt 与 llms-full.txtapps/docs/src/app/llms.txt/route.ts遍历source.getPages()逐页输出- 标题: 描述形式的索引清单是标准的 llms.txt 约定站点地图级摘要apps/docs/src/app/llms-full.txt/route.ts对每页并发调用getLLMText用空行拼接全站完整 Markdown输出全量纯文本。两者都声明revalidate false即每次请求实时生成保证与content/docs/的最新内容一致。单页 Markdown 端点与 URL 重写apps/docs/src/app/llms.mdx/docs/[[...slug]]/route.ts 按 slug 取单页、返回text/markdown响应。再配合next.config.mjs中的重写规则next.config.mjs#L8-L15async rewrites() { return [ { source: /docs/:path*.mdx, destination: /llms.mdx/docs/:path*, }, ]; },任何文档页 URL 加上.mdx后缀例如/docs/users/documents.mdx都会透明地重写到 Markdown 端点。页面顶部的LLMCopyButton正是利用这一点生成${page.url}.mdx链接读者或 Agent点击即可拿到当前页的原始 Markdown而不必解析 HTML。旧版站点路由迁移文档站经历过一次从“无 /docs 前缀”到“/docs 前缀”的站点改版next.config.mjs的redirects()保留了约 90 条永久重定向301规则以保住旧链接按模块分组注释例如{ source: /users/organisations/sso, destination: /docs/users/organisations/single-sign-on, permanent: true }, { source: /developers/self-hosting/how-to, destination: /docs/self-hosting/getting-started/quick-start, permanent: true }, { source: /developers/embedding/authoring/:path*, destination: /docs/developers/embedding/editor/:path*, permanent: true },可以看到迁移不只是机械加前缀还伴随信息架构重组如self-hosting从 developers 下提升为顶级分区、public-api改名为api、embedded-authoring并入embedding/editor。完整清单见 next.config.mjs#L16-L474这也是做文档站改版时值得参考的路由治理范本用静态声明式 redirect 表承接所有历史 URL。文档写作规范README 最后指向仓库根目录的写作规范文档 WRITING_STYLE.md其中定义了 Documenso 文档的语言风格与写作约定。为content/docs/贡献内容时新页面需要遵循该规范撰写 MDX 正文在meta.json中声明页面分组schema 由metaSchema校验frontmatter 提供title/description它们会直接成为 llms.txt 索引与 OG 元数据的来源。小结Documenso 文档站是一个小型但完整的生产级 Fumadocs 实践source.config.ts声明内容收集与 MDX 插件lib/source.ts作为全站数据出口并实现分区侧边栏与 LLM 文本函数src/app/层把内容编译为静态文档页、llms.txt 端点、OG 图路由与 Markdown 重写端点最后用一张声明式 redirect 表完成旧站 URL 治理。对想自建文档站的读者这套“MDX 单一数据源 多形态输出HTML / 纯文本索引 / 全量文本 / 单页 Markdown”的管线设计可以直接复用。【免费下载链接】documensoThe Open Source DocuSign Alternative.项目地址: https://gitcode.com/GitHub_Trending/do/documenso创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考 Documenso 文档站深度解析：基于 Next.js 与 Fumadocs 的 MDX 内容管线与 LLM 友好输出
Documenso 文档站深度解析基于 Next.js 与 Fumadocs 的 MDX 内容管线与 LLM 友好输出【免费下载链接】documensoThe Open Source DocuSign Alternative.项目地址: https://gitcode.com/GitHub_Trending/do/documensoDocumenso 的官方文档站发布在 docs.documenso.com是独立于主应用的 monorepo 子包用 Next.js 与 Fumadocs 技术栈将content/docs/下的 MDX 内容编译为多栏文档站点。本文以 apps/docs/README.md 为核心骨架结合该应用的真实源码完整讲清文档站的目录结构、内容源适配器、侧边栏分区机制、MDX 渲染管线以及 llms.txt / llms-full.txt 等面向搜索引擎与 LLM 的可检索输出实现读完你既能本地跑起文档站也能理解一个生产级 Fumadocs 站点的关键配置。快速上手本地运行文档站文档站包名为documenso/docsREADME 给出的唯一启动命令就是从 monorepo 根目录执行# From the monorepo root npm run dev --filterdocumenso/docs--filter是 npm workspaces 语法只启动该子包对应的next dev。查看 apps/docs/package.json 可以确认各脚本的底层行为脚本实际执行说明devnext dev开发模式buildnext build静态构建配合generateStaticParams预渲染全部文档页startnext start启动生产构建postinstallfumadocs-mdx安装后生成 MDX 类型定义types:checkfumadocs-mdx next typegen tsc --noEmit先重新生成 MDX 类型再生成 Next.js 路由类型最后做类型检查值得注意的是postinstall钩子每次npm install后都会自动运行fumadocs-mdx代码生成器扫描 MDX 内容并产出页面类型定义这也是PageProps/docs/[[...slug]]这类精确路由类型可用的前提。依赖侧的核心是三个 Fumadocs 包fumadocs-core、fumadocs-mdx、fumadocs-ui均为 16.x 版本线再配合 Next.js 16、React 19 与 Tailwind CSS 4见 apps/docs/package.json。站点结构总览README 列出了文档站的三大结构支柱逐一对照仓库即可验证content/docs/全部文档页面以 MDX 组织。该目录目前包含 143 个.mdx页面与 30 个meta.jsonFumadocs 的目录元数据文件用于自定义侧边栏分组、排序与图标lib/source.ts内容源适配器是整站读取内容的唯一入口实际位于 apps/docs/src/lib/source.tslib/layout.shared.tsx共享布局配置实际位于 apps/docs/src/lib/layout.shared.tsx。围绕这三者src/app/下按 Next.js App Router 组织了完整的渲染层apps/docs/src/app/ ├── (home)/ # 文档站首页 ├── docs/[[...slug]]/ # 文档页面catch-all 路由 ├── llms.txt/ # 全站页面索引LLM 入口 ├── llms-full.txt/ # 全站完整 Markdown 文本 ├── llms.mdx/docs/ # 单页原始 Markdown 端点 ├── og/docs/[...slug]/ # 每页 OG 分享图动态生成 └── api/search/ # 搜索 API其中docs/[[...slug]]/page.tsx是文档页核心通过source.getPage(params.slug)按 slug 取页取不到即notFound()并用generateStaticParams()让构建期预渲染全部页面见 apps/docs/src/app/docs/[[...slug]]/page.tsx。页面头部还挂了两个 LLM 相关组件——LLMCopyButton与ViewOptions前者生成${page.url}.mdx地址供一键复制/下载 Markdown后者拼出源码编辑链接指向contentPath: apps/docs/content/docs的对应 mdx 文件见 page.tsx。内容收集配置source.config.tsFumadocs 的内容收集逻辑定义在 apps/docs/source.config.ts这是fumadocs-mdx代码生成器的入口配置import { remarkMdxMermaid } from fumadocs-core/mdx-plugins; import { defineConfig, defineDocs, frontmatterSchema, metaSchema } from fumadocs-mdx/config; export const docs defineDocs({ dir: content/docs, // MDX 内容根目录 docs: { schema: frontmatterSchema, // frontmatter 字段校验 postprocess: { includeProcessedMarkdown: true, // 保留处理后的 Markdown 文本 }, }, meta: { schema: metaSchema, // meta.json 结构校验 }, }); export default defineConfig({ mdxOptions: { remarkPlugins: [remarkMdxMermaid], // MDX 内支持 Mermaid 流程图 }, });两个关键细节postprocess.includeProcessedMarkdown: truesource.config.ts#L10-L12会让每页额外保留一份“处理后的 Markdown”副本这正是后文 llms.txt 系列端点能吐出纯文本的基础而不仅仅是渲染后的 HTML。remarkMdxMermaid插件source.config.ts#L19-L23使 MDX 中可以直接写 Mermaid 图表代码块渲染时交给自定义组件处理下文 MDX 管线部分展开。frontmatter 与meta.json均使用 Fumadocs 内置 Zod schemafrontmatterSchema/metaSchema意味着title、description、toc等字段在代码生成阶段就被静态校验写错字段会在npm run types:check时报错。内容源适配器lib/source.tsapps/docs/src/lib/source.ts 是全站数据的单一出口export const source loader({ baseUrl: /docs, // 所有文档页挂载在 /docs 前缀下 source: docs.toFumadocsSource(), // 把收集的 MDX 数据源交给 loader plugins: [lucideIconsPlugin()], // 支持 frontmatter 中用字符串引用 lucide 图标 });baseUrl: /docs决定了 URL 形态content/docs/users/documents.mdx对应/docs/users/documents与首页根路径互不冲突lucideIconsPlugin允许在meta.json中直接写图标名而不必 import 组件。侧边栏分区过滤getFilteredPageTree文档站把内容分成三大根分区Users / Developers / Self-Hosting外加三个共享分区。source.ts用getFilteredPageTree实现了“进入某分区时侧边栏只显示该分区内容 共享资源”的逻辑source.ts#L13-L63// 所有主分区侧边栏都应出现的共享小节 const SHARED_SECTIONS [concepts, compliance, policies]; const SECTION_TITLES: Recordstring, string { users: User Guide, developers: Developer Guide, self-hosting: Self-Hosting Guide, };函数先按名字找到目标根文件夹再从整棵树中过滤出共享文件夹最终拼装成[主分区分隔条, ...主分区子节点, Resources 分隔条, ...共享文件夹]的新树。找不到目标文件夹时直接返回完整树兜底。调用侧在 apps/docs/src/app/docs/layout.tsx解析pathname第二段命中ROOT_SECTIONSusers / developers / self-hosting就用过滤树否则展示完整树同时侧边栏顶部渲染SectionSwitcher让用户在三大会话间快速切换const ROOT_SECTIONS [ { id: users, label: Users, subtitle: Send and sign documents, href: /docs/users }, { id: developers, label: Developers, subtitle: API and integrations, href: /docs/developers }, { id: self-hosting, label: Self-Hosting, subtitle: Deploy your own instance, href: /docs/self-hosting }, ];页面图片与 LLM 文本的两个辅助函数同一文件还提供两个被路由层复用的工具函数getPageImagesource.ts#L65-L72按页面 slug 拼出/og/docs/.../image.png供文档页的generateMetadata生成 OpenGraph / Twitter 卡片图动态路由实现在src/app/og/docs/[...slug]/route.tsxgetLLMTextsource.ts#L74-L80调用page.data.getText(processed)取出处理后的 Markdown再补一个# 标题首行——这正是 llms 端点的文本生产函数。MDX 渲染管线next.config.mjs顶部用createMDX()包裹整个 Next 配置启用fumadocs-mdx/next的编译集成next.config.mjs#L1-L3。页面渲染时MDX 组件由 apps/docs/src/mdx-components.tsx 统一提供export function getMDXComponents(components?: MDXComponents): any { return { ...defaultMdxComponents, // Fumadocs 内置组件Alert、Steps 等 ...TabsComponents, // 多语言代码 Tab Mermaid, // 配合 remarkMdxMermaid 插件渲染图表 EnvelopeWarning, // 文档专用的自定义警告块 ...components, }; }自定义的Mermaid组件src/components/mdx/mermaid.tsx让source.config.ts注册的remarkMdxMermaid插件真正落地MDX 中的 Mermaid 代码块被转成Mermaid组件再在浏览器端用 mermaid 库绘制这样文档可以内嵌流程图而不影响 SSR。EnvelopeWarning则是针对 Documenso 文档中“Envelope 相关功能”语义的专用警告组件。布局品牌则由 apps/docs/src/lib/layout.shared.tsx 的baseOptions()提供导航栏标题内嵌 Documenso 的 SVG logo并配置了仓库入口地址供 Fumadocs UI 的头部链接使用。面向 LLM 与 Agent 的可检索输出这是文档站最有工程价值的设计同一份 MDX 内容除 HTML 页面外还以纯文本形式暴露让搜索引擎爬虫和 LLM/Agent 能以最小上下文代价获取文档。llms.txt 与 llms-full.txtapps/docs/src/app/llms.txt/route.ts遍历source.getPages()逐页输出- 标题: 描述形式的索引清单是标准的 llms.txt 约定站点地图级摘要apps/docs/src/app/llms-full.txt/route.ts对每页并发调用getLLMText用空行拼接全站完整 Markdown输出全量纯文本。两者都声明revalidate false即每次请求实时生成保证与content/docs/的最新内容一致。单页 Markdown 端点与 URL 重写apps/docs/src/app/llms.mdx/docs/[[...slug]]/route.ts 按 slug 取单页、返回text/markdown响应。再配合next.config.mjs中的重写规则next.config.mjs#L8-L15async rewrites() { return [ { source: /docs/:path*.mdx, destination: /llms.mdx/docs/:path*, }, ]; },任何文档页 URL 加上.mdx后缀例如/docs/users/documents.mdx都会透明地重写到 Markdown 端点。页面顶部的LLMCopyButton正是利用这一点生成${page.url}.mdx链接读者或 Agent点击即可拿到当前页的原始 Markdown而不必解析 HTML。旧版站点路由迁移文档站经历过一次从“无 /docs 前缀”到“/docs 前缀”的站点改版next.config.mjs的redirects()保留了约 90 条永久重定向301规则以保住旧链接按模块分组注释例如{ source: /users/organisations/sso, destination: /docs/users/organisations/single-sign-on, permanent: true }, { source: /developers/self-hosting/how-to, destination: /docs/self-hosting/getting-started/quick-start, permanent: true }, { source: /developers/embedding/authoring/:path*, destination: /docs/developers/embedding/editor/:path*, permanent: true },可以看到迁移不只是机械加前缀还伴随信息架构重组如self-hosting从 developers 下提升为顶级分区、public-api改名为api、embedded-authoring并入embedding/editor。完整清单见 next.config.mjs#L16-L474这也是做文档站改版时值得参考的路由治理范本用静态声明式 redirect 表承接所有历史 URL。文档写作规范README 最后指向仓库根目录的写作规范文档 WRITING_STYLE.md其中定义了 Documenso 文档的语言风格与写作约定。为content/docs/贡献内容时新页面需要遵循该规范撰写 MDX 正文在meta.json中声明页面分组schema 由metaSchema校验frontmatter 提供title/description它们会直接成为 llms.txt 索引与 OG 元数据的来源。小结Documenso 文档站是一个小型但完整的生产级 Fumadocs 实践source.config.ts声明内容收集与 MDX 插件lib/source.ts作为全站数据出口并实现分区侧边栏与 LLM 文本函数src/app/层把内容编译为静态文档页、llms.txt 端点、OG 图路由与 Markdown 重写端点最后用一张声明式 redirect 表完成旧站 URL 治理。对想自建文档站的读者这套“MDX 单一数据源 多形态输出HTML / 纯文本索引 / 全量文本 / 单页 Markdown”的管线设计可以直接复用。【免费下载链接】documensoThe Open Source DocuSign Alternative.项目地址: https://gitcode.com/GitHub_Trending/do/documenso创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考