Hugo 目录结构解析：docs 与 posts 的区别与最佳实践

🎯 学习目标

读完本文，你将了解：

1. Hugo 中 content/docs 和 content/posts 的核心区别是什么。
2. 为什么在物理上和逻辑上都需要将它们分开。
3. 在实际内容创作时，应该如何在这两个目录间做出选择。

在使用 Hugo（尤其是配合 LoveIt 主题）搭建静态网站时，content 目录下的 docs 和 posts 是两个最常用的内容分区（Sections）。许多初学者会疑惑：这两者到底有什么区别？能把它们混在一起吗？

简单来说：posts 是用来存放“博客文章”的，而 docs 是用来存放“纯净文档”的。 它们在语义定位、视觉呈现以及数据组织上都有着显著的差异。

1. 核心差异：页面视觉与功能的呈现

Hugo 的主题可以为不同的文件夹指定不同的模板（Layouts）。在 LoveIt 主题的源码中，这两个目录对应着完全不同的渲染文件，这直接决定了它们在浏览器中的长相。

posts 目录：丰富元数据的博客流

• 对应模板：layouts/posts/single.html
• 视觉呈现：当一篇文章放在 posts 目录下时，页面会自动生成大量的博客元素：
  • 作者信息、发布时间、更新时间
  • 字数统计、预计阅读时间
  • 分类（Categories）和标签（Tags）
  • 文章目录（TOC，通常在右侧浮动）
  • 底部的“社交分享”按钮和“上一篇/下一篇”导航

docs 目录：极简纯净的页面

• 对应模板：layouts/_default/single.html（在代码中被标记为 special page，即特殊单页）
• 视觉呈现：由于 LoveIt 没有专门为 docs 写复杂的专属模板，它会退化使用默认的单页模板。它的特点是极简：
  • 没有时间、作者、字数统计等任何元数据。
  • 没有标签和分类。
  • 没有分享按钮和上下文导航。
  • 整个页面只有：大标题 + 正文内容。

2. 为什么 docs 不也是 posts？

既然都是 Markdown 文件，为什么要拆分成两个目录呢？主要基于以下两点考量：

属性不同：时效性 vs 常青性

• posts 是具有时效性的（Chronological）。它适合用来发布教程、日记、新闻动态等。读者往往关心这篇文章是哪年哪月写的，以判断其技术是否过时。
• docs 是常青的（Evergreen）。它是基建类的说明文档（如项目架构、关于我、隐私政策等）。读者不需要关心它是哪天发布的，只需要关注内容本身是否准确。给《关于本站架构》标上“预计阅读 3 分钟”和“分享到微博”，会显得有些突兀。

信息流隔离：保持博客纯粹

通常博客的首页文章列表、RSS 订阅源默认会去抓取 posts 目录下的更新。如果把项目文档和博客混在一起，你的读者可能会在 RSS 里收到类似《如何编译本项目源码》这种系统说明文档的推送，这通常不是大众受众想看的。分开存放能保持博客信息流的纯粹。

3. posts 中可以有 docs 吗？

物理上可以，但逻辑上极其不推荐。

如果你在 posts 文件夹里建一个 docs 子文件夹（即 content/posts/docs/），Hugo 会将其视为嵌套分类（Nested Section）。这会导致：

1. 样式污染：这些文档会被强行套上博客文章的皮肤，带上发布时间、字数、分享按钮等，显得不够严肃和纯粹。
2. 管理混乱：它们依然会被混入你的博客主列表和标签云中，导致前端展示和后台管理时，“我的博文”和“项目文档”都混杂在一起，难以维护。

🏆 总结建议：如何做出选择？

在日常维护你的 Hugo 站点时，请遵循以下最佳实践：

• 👉 放进 posts/：平时写的技术文章、教程、生活随笔。只要是需要时间线、需要被读者订阅和分享的内容，统统放这里。
• 👉 放进 docs/：项目的系统说明、学习笔记大纲、关于我 (About)、隐私政策等。只要是长期固定、不需要时间戳和繁杂装饰的基建内容，统统放这里。

明确这两者的界限，既符合 Hugo 的架构设计理念，也能让你的站点结构最清晰、读者体验最好。