Tinycast 文档网站实现：Next.js 与 Fumadocs 加 llms.md 的完整做法

Tinycast 文档网站实现Next.js 与 Fumadocs 加 llms.md 的完整做法【免费下载链接】tinycastTinycast — a tiny, fully native macOS launcher, hotkeys, and clipboard history.项目地址: https://gitcode.com/GitHub_Trending/ti/tinycastTinycast 是一款小型、全原生的 macOS 启动器Launcher、热键与剪贴板历史工具而它的文档网站是一个值得参考的工程范例用Next.js 16 Fumadocs构建静态文档站并通过llms.txt与llms.md路由让 AI 助手能直接读懂每一篇文档最终零服务器部署到 Cloudflare。本文完整拆解这套文档站的做法适合想给自己的项目搭建 AI 友好文档站的新手。技术栈总览Next.js Fumadocs 的最小组合整个网站位于 website/ 目录核心依赖在 website/package.json 中一目了然依赖作用nextApp Router 框架负责页面、路由与静态导出fumadocs-core/fumadocs-ui文档数据源模型与现成的文档 UI侧边栏、目录、搜索fumadocs-mdxMDX 编译器把content/docs目录变成可查询的页面树tailwindcssv4样式系统wranglerCloudflare Pages 部署工具可以看到没有任何 CMS、数据库或数据库驱动的路由——全部内容都是 Markdown 文件构建时一次性生成 HTML。文档内容组织fumadocs-mdx 的三件套第一步定义文档目录。website/source.config.ts 只做两件事defineDocs({ dir: content/docs })声明 Markdown 文档的存放目录通过defineConfig注入rehypePlugins与代码高亮配置。这里有两个很实用的细节rehype-raw的坑Fumadocs 会向 AST 注入 MDX 节点rehype-raw默认拒绝处理它们必须显式传入passThrough: MDX_NODES白名单否则快捷键表里的kbd标签会被静默吞掉按需引入高亮语法rehypeCodeOptions.langs只声明了[bash, json, markdown]避免把用不到的语法包打进构建产物且高亮在构建期完成、浏览器端零成本。第二步管理页面顺序。website/content/docs/meta.json 用数组顺序声明侧边栏导航index → install → permissions → palette → launcher → features → ai → extensions → reference。第三步生成数据源。website/src/lib/source.ts 用loader({ baseUrl: /docs, source: docs.toFumadocsSource() })把文档目录变成运行时可查询的source对象侧边栏、sitemap、llms.txt 全部复用它。llms.md 实现把原始 Markdown 喂给 AI这是本仓库最有意思的部分——网站为 AI Agent 提供了两层机器可读接口1.llms.txt全站文档索引website/src/app/llms.txt/route.ts 在构建时遍历source.getPages()把 37 个页面按章节Launcher、Features、AI、Reference……分组生成一份text/plain索引每一行是页面标题 链接 一句话描述AI 只需一次请求就能了解整站结构。2.llms.md/docs/[slug]/index.md单页原始 Markdownwebsite/src/app/llms.md/docs/[...slug]/route.ts 为每个页面输出一份纯 Markdown 文件Content-Type: text/markdown配合 website/src/lib/get-llm-text.ts 剥掉 frontmatter、补上标题与描述得到 AI 可直接消费的正文。一个巧妙的工程决策在 website/src/lib/source.ts 的注释里静态导出中既是文件又是目录的路径会冲突例如/docs/launcher既要当文件夹又要当页面所以给所有页面的 Markdown 统一命名为叶子文件index.md从根本上消灭这类冲突。generateStaticParams()则在导出时为每个页面预生成对应的.md文件——线上没有任何运行时请求。这套机制同时服务于人类的Copy Markdown按钮一份代码、两种读者。静态导出与部署无 Node 进程的文档站website/next.config.mjs 是理解部署形态的关键output: export纯静态导出Cloudflare 直接托管文件背后没有 Node 进程images: { unoptimized: true }图片优化 API 需要服务端导出场景下必须关闭trailingSlash: true生成/docs/palette/index.html这是静态主机唯一能正确服务的形态reactCompiler: true启用 React Compiler 自动记忆化。部署只需一条命令pnpm deploy即wrangler deploy配置见 website/wrangler.jsonc截图类媒体由 Scripts/upload-website-media.sh 单独上传。SEO 细节元数据、sitemap 与结构化数据website/src/app/layout.tsx 集中处理了分享与搜索引擎元数据标题模板%s — Tinycast所有子页自动带上品牌后缀Open Graph / Twitter Card统一使用 1200×630 的og.png分享卡片结构化数据内嵌schema.org/SoftwareApplication的 JSON-LD声明应用类别、操作系统与免费许可自托管字体next/font在构建时下载 Geist 与 Instrument Serif 并生成度量匹配的 fallback无第三方请求、无布局偏移layout shift。而 website/src/app/sitemap.ts 直接从文档树生成——新增一篇文档sitemap 自动多一条无需维护两份清单。文档布局 website/src/app/docs/layout.tsx 则用 Fumadocs 的DocsLayout一行代码获得带侧边栏、主题切换与社交链接的完整文档框架。快速上手五步复刻这套文档站初始化next16fumadocs-mdxfumadocs-corefumadocs-ui文档写入content/docs/在source.config.ts中defineDocs并加入rehype-raw记得passThrough白名单用loader({ baseUrl: /docs })生成source所有动态功能导航、sitemap、llms.txt都从它取数添加llms.txt索引路由 每页index.md路由全部标记force-staticnext.config.mjs开启output: exportwrangler deploy上线。总结这套做法好在哪纯静态构建期生成一切托管零成本无服务端运维一份内容三个出口人看的 HTML、人复制的 Markdown、AI 读的llms.md/llms.txt全部来自同一目录的同一批文件约定优于配置新增文档后导航、sitemap、AI 索引全部自动生效细节克制按需的代码高亮语言、自托管字体、统一叶子文件名都是小决定换大省心的典型案例。如果你正在为开源项目搭建文档站website/ 目录就是一个可直接对读的完整参考实现。【免费下载链接】tinycastTinycast — a tiny, fully native macOS launcher, hotkeys, and clipboard history.项目地址: https://gitcode.com/GitHub_Trending/ti/tinycast创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考