文档站内容、构建与发布排错

区分内容、构建输出与基路径

需能阅读 YAML 与 Markdown 相对链接。两页文档站示例固定 MkDocs 1.6.1，使用 pages/ 存源码、output/ 存构建结果，并演示 /handbook/ 子路径；先对照 mkdocs.yml、页面链接和 README，再判断导航与输出地址。 示例未在本轮执行。

静态站点 构建链

静态站点构建链把内容、模板和配置转换为HTML及资源文件。源码目录与输出目录要分开，输出可重新生成；把构建成功当作发布成功会遗漏托管路径和缓存问题。

静态站点 内容模型

静态站点内容模型区分文章元数据、正文与导航。日期是发布语义而非文件修改时间，草稿是否进入输出由生成器规则决定；不把历史主题的frontmatter字段当作所有站点通用标准。

静态站点 基路径

静态站点基路径决定子目录托管下资源地址。例如站点位于/handbook/时根相对/assets会跳出子目录；使用生成器支持的相对链接和site_url，避免本地可读但部署后资源404。

依据与适用范围

• 本课官方依据，资料核对日2026-10-17。

以上依据用于解释本文列明的规则；示例未执行，不代表产品全部能力或跨平台验证。历史资料的版本、账号与界面位置需按目标环境确认。

配置导航、依赖与发布资料

MkDocs nav 配置

MkDocs的nav配置指定页面树及显示标题，路径相对docs_dir。文件存在不等于进入导航，导航引用不存在文件也会失败；本例明确两页顺序，不自动把全部草稿收录。

静态站点 依赖声明

静态站点依赖声明应固定选定生成器和主题，升级时一起核对插件。示例选择MkDocs1.6.1作为教学版本而不称最新，标准主题避免隐藏主题下载；本轮不安装依赖。

静态站点 发布资料

静态站点发布资料至少包含构建输入、输出路径和托管前缀。发布需要额外授权与账号，本课只列读者自跑命令，不调用托管平台或启动预览；上传目录不能误指向含源码秘密的根目录。

排查主题迁移、断链与缓存

静态站点 历史主题

静态站点历史主题的字段、短代码和评论服务属于特定版本契约。旧Hugo Jane与Jekyll模板可帮助理解文章结构，迁移时需逐项找对应能力，不把主题配置直接塞入MkDocs。

静态站点 链接失效

静态站点链接失效要区分源码路径不存在、输出扩展变化、大小写差异和基路径错误。Windows本地文件能打开不证明大小写敏感托管环境可达；修正文链接而非只在构建输出补文件。

静态站点 缓存

静态站点缓存会让读者看到旧HTML与新资源混搭。带内容摘要的资源名能降低错配，入口HTML需要合适的更新策略；本例不配置CDN，不能从静态配置宣称线上刷新已生效。