开发
查看 Markdown

维护网站元数据与 Markdown 导出

修改网站内容、新增页面或更换部署地址时,按本页步骤更新对外信息。Fumadocs 网站为 GitHub Pages 构建 HTML、元数据和 Markdown 文件,部署后由静态托管服务提供这些文件。

修改页面标题和摘要

编辑 docs/en/ 和 docs/zh/ 中的源 Markdown。产品文档、开发指南和 RFC 各自使用文件开头的 front matter。博客文章按博客发布指南同步修改中英文。构建会把源文件复制到 website/content/,内容修改应落在原文件中。

摘要应帮助读者判断是否需要打开这页:

页面类型摘要应说明什么
入门教程跟随教程能完成什么
操作指南或迁移指南要完成的任务、影响适用性的前提和预期结果
参考文档可以查询哪些接口、字段或规则
原理说明回答什么问题、解释哪些设计取舍
RFC提议的设计及其范围
博客文章正文讨论的问题或论点

使用正文中的术语,保留影响安全和兼容性的前提,并区分设计提案与已发布能力。搜索摘要应概括页面内容,避免堆砌产品关键词。

独立页面的标题和摘要在路由文件的 pageMetadata 调用中修改。站点简介位于 website/src/lib/metadata.ts。博客文章使用文章摘要,作者页说明该作者发表的文章,归档页标明发表年份,分页标题包含页码。

将新路由接入搜索和 Markdown 入口

调用 pageMetadata 时填写页面路径和语言,只为实际存在的对应页面提供语言关联。文档路由通过 contentMetadata 查找对应译文。英文首页的 canonical 为 /,访问 /en/ 时也使用它;其他页面的 canonical 以 / 结尾。

在 website/src/app/sitemap.ts 中登记独立页面。文档、博客、Python 和 HTTP API 参考通过各自的内容源进入站点地图。站点地图排除重复英文首页、旧重定向和未发布的博客。只有记录中存在发布或更新日期时才填写 lastmod,重新构建不能说明内容何时更新。website/src/app/robots.ts 声明站点地图地址并允许抓取。

文档和已发布博客也会进入 Markdown 导出。HTML 元数据链接到对应 Markdown,页面操作支持复制和打开。Python 与 HTTP API 参考提供 HTML 页面和站点地图条目,不属于 Markdown 内容集合。

修改分享图和结构化数据

在 website/src/app/og.png/route.tsx 中修改默认分享图。构建使用已有品牌 Logo 生成 1200 × 630 的 PNG。文案应简短,便于在链接预览中阅读。单页分享图通过 pageMetadata 设置,已发布博客使用文章封面。站点图标位于 website/public/icon.svg。

文章的 BlogPosting JSON-LD 应与可见页面使用相同事实,包括标题、摘要、作者主页、封面、发布日期和更新日期。文档和博客文章还提供面包屑 JSON-LD。Fumadocs 搜索索引中的 structuredData 用于站内搜索的标题和正文索引,与 JSON-LD 分别维护。

使用部署地址构建

将 NEXT_PUBLIC_SITE_URL 设为站点源地址,将 NEXT_PUBLIC_BASE_PATH 设为部署子路径;部署在根目录时,base path 留空。生成绝对 URL 时会使用这两个值。采用子路径部署时,还需在托管服务中配置源站根目录的 robots.txt,让爬虫可以找到站点地图。

在仓库根目录构建并检查类型:

make docs-build
pnpm --dir website types:check

构建会检查本地链接和静态导出。在 website/out/ 中核对产物:

产物核对内容
页面 HTML标题、摘要、canonical、已有译文、分享元数据和 JSON-LD
sitemap.xml 与 robots.txt部署地址和公开页面范围
og.png 与 icon.svg图片可打开,文案完整可读
llms.txt 与 llms-full.txt默认英文索引和全文
en/llms.txt、zh/llms.txt 及各自的 llms-full.txt索引和全文使用对应语言
{lang}/llms.mdx/{section}/{slug}/content.md页面内容及其 HTML 来源链接

Markdown 的 section 为 docs、development、rfcs 或 blog,概览页省略 {slug}。website/src/lib/llms.ts 通过 Fumadocs loader 合并文档与已发布博客,官方 llms() API 从页面树生成索引,并通过 getText('processed') 生成单页和全文。URL helper 与 content.md 路由采用 Fumadocs LLM 集成中的做法。

静态托管直接提供导出的 Markdown 文件。Next.js rewrite 和 Accept 请求头协商需要服务端,本站不启用这些功能。相对文档链接通过 Fumadocs 内容源解析为绝对 Markdown 地址,保留查询参数和锚点;以 / 开头的链接和图片使用部署地址。代码示例和 Markdown 源文件保持原样。添加页面标题与来源 URL 前,会移除正文已有的开头标题。MDX 组件按 Fumadocs 默认行为保留 JSX,不另行转换为自定义文本格式。

源文件直接使用 UTF-8 文字。路由声明 UTF-8 内容类型,静态托管也需为 .txt 和 .md 文件返回带 UTF-8 charset 的响应头。排查乱码时,检查预览或部署环境的实际响应头。导出文件便于工具读取文档,搜索引擎自行决定是否收录或引用。

核对的构建应使用发布环境的变量。准备好发布时,再通过网站部署工作流部署这些文件。

On this page