Hugo 学习区：内容与模板入门 on 向叔记事簿

先把内容当成一棵树

Mon, 01 Jan 0001 00:00:00 +0000

博客的默认单位是一篇文章：写完、发布、归档，读者通常从最新一篇往回看。课程不是这样。课程的第一章即使一年没更新，也依然应该排在读者面前；中间插入一节补充内容，也不该打乱原有的阅读路径。

因此，学习区先用目录声明“这是谁的一部分”，再用 weight 声明“它应该排在第几位”。例如：

content/learning/hugo-learning-path/
├── _index.md
├── 01-content-tree/
│   └── index.md
└── 02-reading-template/
    └── index.md

顶层 hugo-learning-path 是一个集合，它的 _index.md 说明这门课解决什么问题。每个章节目录中的 index.md 是可独立阅读的页面；如果一部分内容下面还会继续长出小节，就把该层写成 _index.md，让它既能写导言，也能容纳子章节。

weight 不需要连续。先写 10、20、30，以后要在前两章之间补一节时，用 15 即可。这样，文件夹名字帮助人理解结构，weight 则成为模板可稳定读取的阅读顺序。

日期仍有价值，但它只回答“这页最后更新是什么时候”，不再替读者决定“我下一步该读什么”。这是学习内容和日常博客最重要的分界线。

Mon, 01 Jan 0001 00:00:00 +0000

内容有了顺序，还需要把顺序交给读者。否则三篇文章只是放在同一个目录里，读者仍然要靠猜测决定下一篇。

学习区的页面壳做了三件小事：左侧目录树告诉读者整门课的形状；面包屑标示当前位置；页面底部给出上一章和下一章。它们都来自同一份目录与 weight，不需要在正文里手动维护链接。

这也是为什么课程不应直接套用博客文章页。博客文章页会强调作者、发布日期、相关文章和评论；学习页面更关心“我现在在哪一节”“本节属于什么集合”“读完之后去哪一节”。两种内容都能使用相同的 Markdown、代码高亮和数学公式，但阅读上下文不同。

在这个站点里，章节树会递归读取集合下的 section 与页面：section 显示为“部分”，叶子页面显示为“章节”。前后导航只扁平化叶子章节，所以“第二部分”的导言不会挤进读者的连续阅读路线。

当内容规模还只有三章时，这些设计看起来略显克制；但它避免了以后从三篇扩展到三十篇时，重新整理链接、搬迁 URL 和修改分类页的成本。

Mon, 01 Jan 0001 00:00:00 +0000

如果课程章节仍然出现在博客首页、年度归档和日常订阅里，它在读者眼中还是博客的一部分。真正的独立需要把“哪里能发现它”也设计清楚。

本站把 post、notes 保留为博客流的主内容；学习区不加入 mainSections。因此，首页的最近更新、归档和博客搜索不会自动吸入课程章节。学习区自己的根页则生成独立搜索索引，只搜索课程中的叶子章节。

首页仍然可以给学习内容一个轻量入口：展示集合卡片，而不是展示某一章。卡片只说这门课叫什么、处于什么状态、已经有几章，点击后进入课程首页。这样首页保留了“我正在长期整理什么”的信息，又不会把一节技术课伪装成当天发布的博客文章。

最后一步是构建。模板和样式的错误往往不会出现在 Markdown 文件里，而会在 Hugo 渲染时暴露。修改学习区后至少运行：

python -m unittest tests.test_learning_section
hugo --renderToMemory --panicOnWarning

前者保护内容边界和模板契约，后者编译实际页面、SCSS、脚本和输出格式。只有两者都通过，新的章节才算真正进入站点。