mkdocs 专为项目文档设计，支持跨文档导航、全局搜索、多语言切换及 ci/cd 部署，而 markdown preview enhanced 仅限单文件预览，缺乏企业级文档必需的结构化能力与可发布性。
为什么不用 Markdown Preview Enhanced 直接预览，而要上 MkDocs
因为 Markdown Preview Enhanced 是单文件预览工具，不支持跨文档跳转、全局搜索、版本化导航栏、多语言切换或部署后端路由——这些是企业级文档必须的。MkDocs 本质是一个静态站点生成器，它把所有 .md 文件按 mkdocs.yml 定义的结构编译成带 JS 交互的 HTML 站点，天然适配团队协作和 CI/CD 流程。
常见错误现象：用 Markdown Preview Enhanced 写完几十页文档后，发现无法统一侧边栏、无法加搜索框、无法导出带目录的 PDF、也无法一键部署到内网服务器。
- 使用场景：中大型技术团队维护 API 文档、SDK 使用指南、内部 SOP 手册
- 性能影响：本地
mkdocs serve启动快（通常 .md 文件，文件数超 200 时建议启用watch模式而非反复重启服务 - 兼容性注意：MkDocs 默认解析 CommonMark，不支持
~~strikethrough~~或==highlight==这类扩展语法，需额外装插件如mkdocs-markdownextradata-plugin或改用mkdocs-material主题
mkdocs.yml 配置里最容易写错的三个字段
nav、plugins、theme 这三项一旦格式错位或缩进不对，mkdocs serve 就直接报 YAML error: mapping values are not allowed in this context，而不是告诉你哪一行错了。
实操建议：
-
nav必须是列表（不是字典），每个条目是标题: 文件路径或嵌套结构，路径必须以.md结尾且相对docs/目录，比如- 概述: index.md，不能写成- Overview: docs/index.md -
plugins是列表，但部分插件（如search）要求前置加载，顺序错会导致搜索失效；推荐固定写法：- search放第一，- mkdocs-minify-plugin放最后 -
theme若指定material，必须提前pip install mkdocs-material，否则mkdocs serve报Theme directory does not exist，而不是提示缺依赖
如何让本地写作环境同时支持实时预览 + MkDocs 构建
VSCode 原生预览（Ctrl+Shift+V）和 mkdocs serve 是两套渲染逻辑，样式、数学公式、流程图默认不一致。强行共用会导致「左边看着对，右边构建出来错」。
解决路径只有两条：
- 放弃原生预览，统一用
mkdocs serve：在 VSCode 中打开终端运行mkdocs serve -a 127.0.0.1:8000，然后用浏览器访问http://127.0.0.1:8000；每次保存.md文件，页面自动刷新（需确保livereload插件启用，默认开启） - 保留原生预览但对齐渲染效果：安装
Markdown Preview Enhanced，在设置中手动指定mathjax: true、mermaid: true，并加载与 MkDocs 主题同源的 CSS（例如从mkdocs-material的assets/stylesheets目录复制一份main.css到工作区，再通过插件配置css: ./main.css）
后者配置成本高，但适合高频单页写作；前者更稳定，适合结构化文档协作。
导出 PDF 时字体/中文/页眉页脚失效的根本原因
MkDocs 本身不导出 PDF，它只生成 HTML。所谓“导出 PDF”，实际是用 Puppeteer 或 wkhtmltopdf 抓取 HTML 后打印。因此所有样式失效问题，本质是浏览器渲染层缺失或 CSS 未生效。
关键排查点：
- 中文乱码：HTML 中未声明
<meta charset="utf-8">，或 CSS 里没指定font-family支持中文字体（如"Microsoft YaHei", "Noto Sans CJK SC", sans-serif） - 页眉页脚空白：Puppeteer 的
printToPDF默认关闭displayHeaderFooter，需在导出脚本里显式传参，例如：page.pdf({ displayHeaderFooter: true, headerTemplate: '<div style="font-size:10px">第 &P; 页</div>', ... }) - 目录不生成：HTML 里没有
<nav class="md-nav"></nav>结构，或 JS 未执行 toc 生成逻辑 —— 这说明你用的是精简版主题或禁用了toc插件
真正稳定的 PDF 输出方案，其实是用 Pandoc 直接处理原始 .md 文件（绕过 MkDocs 渲染），但会丢失主题样式和交互组件。两难选择，得看优先级。
