如何在不安装数GB node_modules 的情况下构建简洁文档
当你启动一个新项目或在团队中维护一个库时，基础文档的问题不可避免地会出现。假设你不需要一个带有动态路由、响应式组件和数百兆依赖的巨型门户。你只是想写几个 Markdown 文件，按一下按钮，就能得到一个带有树形导航、搜索和移动端适配的简洁站点。
在这种情况下，Docusaurus 或 VuePress 是常见的选择。它们很好，但需要安装大量的 npm 包。如果你想避免在构建流程中使用 Node.js，并重视闪电般的生成速度，那么值得了解一下 Alexander Shpak 的 Hugo Book 主题。
这个主题是什么，适合谁使用
Hugo Book 是 Hugo 静态网站生成器的一个极简模板，样式如同普通书籍，带有侧边菜单。项目作者 Alexander Shpak 有一个明确的目标：创建一个快速运行且不会让用户花费数小时研究配置文件的简洁设计主题。
该仓库在 GitHub 上已积累超过 4,000 颗星，对于一个专门的 Hugo 主题来说相当可观。模板会自动识别标准 Markdown，并根据文件夹嵌套自动构建页面树形结构。
核心特性揭秘
与许多现代 Web 工具不同，Hugo Book 坚持严格的"精简饮食"。主要站点功能完全无需 JavaScript 即可运行。移动端菜单切换、展开嵌套部分和树形导航都通过纯 CSS 实现。
实用特性包括：
- 内置深色主题。它会自动适配操作系统的设置，但你也可以添加手动切换开关。
- 开箱即用的多语言支持。Hugo 可以管理不同语言的并行文件夹结构，主题也能正确渲染版本切换器。
- 便捷的内置短代码。对于样式化注释、警告、漂亮按钮和代码标签页，你无需自己发明变通方案。
- 内置搜索和评论功能。搜索可以通过内置的轻量级脚本（FlexSearch）或第三方服务实现。
最小干预原则
作者在项目理念中特别指出：主题不应干扰用户的布局或使配置过载。要启动一个站点，你基本上不需要在 config.toml 或 hugo.toml 中设置任何特定参数。模板会自动识别 Hugo 的标准内容结构。
如果你需要自定义样式，可以通过一个特殊的扩展文件用几行代码覆盖 CSS，而无需触碰主题的源代码。这样当主题在几个月后更新时，你就不会有维护的麻烦了。
快速开始
你需要安装 Hugo 的扩展版本（Hugo extended）0.158 或更高版本。设置过程只需两分钟。
最简单的方法是使用现成的入门仓库：
git clone https://github.com/alex-shpak/hugo-book-starter my-docs
cd my-docs
git submodule update --init --remote
hugo server --minify
启动本地服务器后，http://localhost:1313 会打开一个现成的文档站点。当你修改 Markdown 文件时，Hugo 几乎会即时在浏览器中更新页面。对于几百页的站点，构建时间通常不超过零点几秒。
用于文本布局的短代码
当你需要突出显示重要注释或创建多列布局时，标准 Markdown 可能过于受限。Hugo Book 有一套内置的短代码。
例如，hint 短代码用于创建美观的提示信息块：
{{< hint info >}}
Здесь можно написать полезную подсказку для читателя.
{{< /hint >}}
{{< hint warning >}}
А так оформляется предупреждение о возможных ошибках.
{{< /hint >}}
如果你需要展示不同操作系统或编程语言的代码示例，tabs 短代码会派上用场：
{{< tabs "unique-id" >}}
{{< tab "Linux" >}}
sudo apt install my-tool
{{< /tab >}}
{{< tab "macOS" >}}
brew install my-tool
{{< /tab >}}
{{< /tabs >}}
版本管理方式
该主题采用 MIT 许可证分发。作者使用增量版本号（如 v0.13.0、v0.14.0）。版本之间偶尔会出现破坏性变更，因此对于生产环境，最好锁定到特定的标签而不是停留在主分支。
适用场景
该主题非常适合以下场景：
- 开源库的技术文档
- 内部团队知识库或企业 Wiki
- 服务部署和 API 说明文档
- 个人技术博客或笔记集合
如果你需要大量交互性、文档中直接嵌入 3D 图形，或深度集成 React 组件，Hugo Book 可能不太适合。在这种情况下，你需要考虑 Docusaurus 或 Astro Starlight。但对于典型的文档任务，Hugo Book 的简洁性已经绰绰有余。
潜在陷阱
尽管有诸多优点，你仍需了解 Hugo 基础设施的细微之处。Hugo 底层的 Go HTML Templates 模板引擎有特定的语法。如果你想彻底重写页眉或页脚结构，就需要投入时间学习 Go 模板结构。
此外，本地搜索的搜索索引是在构建时生成的。对于拥有数万页的大型站点，搜索文件可能会变得很大，尽管对于典型的指南类文档来说这完全不是问题。
总结
Hugo Book 是一个没有不必要修饰的诚实工具。它完全兑现了承诺：将一堆包含 Markdown 的文件夹转换为一个快速、简洁且可读的站点。无需安装 npm 包，无需冗长的构建，无需复杂的配置。
相关项目