hexo 可构建企业级文档中心，关键在于将 source 视为内容仓库、themes 作为渲染层，重定义目录结构（如 source/docs/）、禁用博客功能、重写 permalink 为 docs/:path/、正确配置 url/root/relative_link 等核心参数，并用 http-server 替代 hexo server 进行真实路径预览。
Hexo 不是只适合写博客的玩具，它能撑起结构清晰、可维护性强的企业级文档中心——前提是绕开默认博客思维，把 source 当成内容源仓库，把 themes 当成渲染策略层，而不是套个主题就完事。
如何让 Hexo 生成的不是博客，而是文档中心
关键在目录结构和路由逻辑的重定义。默认的 source/_posts 是为时间线服务的，文档中心需要的是扁平化、分类明确、支持多级导航的组织方式。
- 把文档按模块拆进
source/docs/下，比如source/docs/getting-started/、source/docs/api-reference/，每个子目录放一个index.md作为入口页 - 禁用 Hexo 默认的归档、标签、分类页面：在
_config.yml中设archive: false、category: false、tag: false - 用
skip_render排除不需要被处理的资源，比如source/docs/assets/下的 PDF 或 SVG 原始文件，避免被误转成 HTML - 启用
hexo-generator-index插件并配置index_generator，让它把/docs/当首页，而不是/
为什么 permalink 必须重写，且不能用默认格式
默认 permalink: :year/:month/:day/:title/ 会把文档 URL 绑死在发布时间上，而文档更新频繁、版本迭代快，URL 应该稳定可预测。
Html To Pdf
下载
使用 Puppeteer + Chrome 将 HTML 渲染为中文 PDF，自动处理图表等待、Tab 展开、动画、测高、白边消除、防分页，适用于看板、报表、网页和交互图表转 PDF。
- 改成
permalink: docs/:path/，这样source/docs/guide/install.md就生成/docs/guide/install/ - 配合
page类型文章（在 front-matter 里写layout: page），避免被当成 post 加入时间线或 RSS - 如果需支持多语言路径，比如
/zh/docs/...，就得搭配hexo-generator-i18n插件，并在每篇文档 front-matter 中显式声明lang: zh
_config.yml 里哪些字段直接影响文档可访问性
不是所有配置项都只是“美化”用的，这几个一错，整个文档站就断链或白屏。
-
url必须填完整域名（如https://docs.example.com），否则生成的 CSS/JS 路径全错，尤其影响 CDN 部署场景 -
root要严格匹配实际部署路径：若托管在https://example.com/help/，则root: /help/（开头结尾都要斜杠） -
relative_link: false—— 文档内跳转必须用绝对路径，否则跨目录链接会失效 -
highlight: enable: false关掉默认代码高亮，换用prismjs或shiki插件，后者支持主题切换和语言别名（如```ts→ TypeScript）
本地预览时 hexo server 的局限与绕过方法
hexo server 模拟的是根路径 /，但企业文档常部署在子路径（如 /docs/），直接预览会漏掉大量 404。
- 别依赖
hexo server测路径，改用npx http-server public -p 8080启动一个真实静态服务器 - 启动前确保已执行
npx hexo generate，且public目录结构与最终上线一致 - 加
--cors参数（npx http-server public -p 8080 --cors），避免本地调试时因跨域无法加载 JSON Schema 或 API 示例数据 - 如果文档含
iframe嵌入外部 demo，记得在http-server启动时加--headers允许X-Frame-Options覆盖
真正难的不是生成 HTML，而是让每一条链接、每一个资源引用、每一次版本切换都不依赖人工检查——这要求从第一天就定好路径契约，而不是等上线前再批量替换 href。
前端入门到VUE实战笔记：立即使用
在学习笔记中，你将探索 前端 的入门与实战技巧！
