用 Hugo Blox Academic CV 主题搭建课程中心:landing 页面、collection 聚合与课程内容组织
用 Hugo Blox Academic CV 主题搭建课程中心:landing 页面、collection 聚合与课程内容组织
导读
本文以仓库中的课程中心入口 content/courses/_index.md 为绝对主线,完整拆解在 Hugo Blox Academic CV 主题下搭建「课程中心」的完整方案:从 type: landing 页面骨架、cascade 批量参数注入,到 collection 区块按标签自动聚合课程、再到课程页面的内容组织与格式化短代码实战。读完本文,你将能够从零复制这套配置,在几分钟内构建一个带面包屑导航、自动侧边栏、支持 Markdown 呼应与可折叠教程的课程模块。
一、课程中心的入口:一份 landing 页面配置读懂全部逻辑
仓库中的课程中心由单个 Markdown 文件驱动,content/courses/_index.md 全文如下:
---
title: Courses
summary: My courses
type: landing
cascade:
- target:
path: '{/courses/*/**}'
type: docs
params:
show_breadcrumb: true
sections:
- block: collection
id: courses
content:
title: Courses
filters:
tag: Course
kinds:
- section
design:
view: article-grid
show_read_time: false
show_date: false
show_read_more: false
columns: 1
---
这份配置虽短,却同时完成了三件事:声明页面类型、批量下发子页面参数、声明首页聚合区块。下面逐项拆解。
1.1 type: landing:把页面变成「区块组装器」
type: landing 告诉 Hugo Blox 引擎:本页不是普通文章,而是由 sections 列表中的若干「区块(block)」组装而成的落地页。每个区块由 block 字段指定类型,配合 content 与 design 两个子段分别定义数据来源和视觉样式。
区块渲染能力并非由本站点代码提供,而是来自外部模块:在 config/_default/module.yaml 中可以看到站点导入了 github.com/HugoBlox/kit/modules/blox,这正是 collection、cards 等所有 block/shortcode 的实现来源。本站的 layouts 目录下仅保留了一个自定义的 head-end 钩子(layouts/_partials/hooks/head-end/github-button.html),其余渲染逻辑全部由 Hugo 模块在构建期合入,这也是 landing 页能"零本地模板"直接运行的原因。
1.2 cascade:为整个课程目录批量注入参数
cascade:
- target:
path: '{/courses/*/**}'
type: docs
params:
show_breadcrumb: true
cascade 是 Hugo 的前置参数批量注入机制:任何匹配 target.path 的页面都会自动继承这里声明的 front matter。这里 {/courses/*/**} 匹配 courses/ 下的一层目录及其更深层的所有页面,例如 content/courses/hugo-blox/getting-started.md 和 content/courses/hugo-blox/guide/formatting/button.md 都会被覆盖:
type: docs:强制课程子页面使用文档布局,左侧侧边栏、右侧目录(TOC)自动生成;params.show_breadcrumb: true:在页面顶部显示「Courses / 课程名 / 子章节」式面包屑导航。
这一设计避免了在每个课程页面里手工重复书写同样的 front matter,新增任何课程目录都无需改动入口配置。
1.3 summary 的用途
summary: My courses 会作为该 section 页在列表、搜索索引和社交分享卡片中的摘要描述,替换后即可用于 SEO 展示。
二、collection 区块:按标签自动聚合课程内容
sections 中唯一的区块是 block: collection,这是 Hugo Blox 的"自动列表"区块,它扫描站点内容,将满足过滤条件的页面渲染成一个内容网格:
sections:
- block: collection
id: courses
content:
title: Courses
filters:
tag: Course
kinds:
- section
design:
view: article-grid
show_read_time: false
show_date: false
show_read_more: false
columns: 1
2.1 filters:如何选中"课程"
| 字段 | 取值 | 作用 |
|---|---|---|
tag |
Course |
只聚合 front matter tags 中带有 Course 的页面 |
kinds |
[section] |
只聚合 Hugo 的 section 类型页面(即各课程目录的 _index.md),而非具体文章 |
二者是"且"关系。以仓库为例,content/courses/hugo-blox/_index.md 的 front matter 中声明了 tags: [Hugo Blox, Course],且它正是 courses/hugo-blox/ 目录的 section 页面,因此会被自动聚合到课程中心列表;而该课程下的 getting-started.md 等普通页面虽然也受 cascade 影响,但 kinds: [section] 会将它们排除在列表之外。
2.2 design:列表的呈现方式
| 字段 | 本配置取值 | 含义 |
|---|---|---|
view |
article-grid |
以卡片网格呈现每个课程 |
columns |
1 |
每行显示 1 张卡片 |
show_read_time |
false |
隐藏阅读时长估算 |
show_date |
false |
隐藏发布日期 |
show_read_more |
false |
隐藏"阅读更多"入口 |
这套 design 参数与 content 分离,意味着你可以只改样式不动数据,例如把 columns 改为 2 或 3 即可在同一个聚合逻辑下切换多列布局。
三、把课程中心挂进站点导航
课程中心建好后,需要在导航栏暴露入口。仓库在 config/_default/menus.yaml 的 main 菜单中为它预留了位置:
main:
- name: Bio
url: /
weight: 10
...
- name: Courses
url: courses/
weight: 40
weight 决定菜单项顺序(数值越小越靠前),url: courses/ 指向课程中心的 landing 页面。main 菜单是否启用、以及其余菜单项(如 sidebar)的定义,均由 config/_default/params.yaml 与 config/_default/menus.yaml 协同控制。
进入任意课程页面后,文档布局还会自动完成两级导航:左侧边栏链接"由 content 目录结构自动生成",只需新建子文件夹即可嵌套页面;右侧目录则从 Markdown 标题自动提取,可在页面 front matter 中设置 toc: false 关闭。这两点在该仓库的 content/courses/hugo-blox/guide/configuration.md 中有明确说明。课程子页面的排序通过 front matter 的 weight 控制,例如 getting-started.md 声明 weight: 1、guide/_index.md 声明 weight: 2,从而保证"入门"排在"指南"之前。
四、课程内容如何组织:以 hugo-blox 课程为范例
聚合逻辑只负责"列出课程",每个课程的内容组织遵循标准的 Hugo 内容目录约定。仓库中 content/courses/hugo-blox/ 是一个完整的范例课程:
content/courses/hugo-blox/
├── _index.md # 课程首页(section 页面,带 Course 标签)
├── featured.jpg # 课程封面(被 article-grid 卡片引用)
├── getting-started.md # 入门章节(weight: 1)
├── guide/ # 指南目录(weight: 2)
│ ├── _index.md
│ ├── project-structure.md
│ ├── configuration.md
│ └── formatting/
│ ├── _index.md
│ ├── button.md
│ ├── callout.md
│ ├── cards.md
│ ├── steps.md
│ ├── toggle.md
│ └── media.md
└── reference/ # 参考目录
├── _index.md
├── customization.md
└── i18n.md
4.1 课程首页 _index.md 的 front matter
---
linkTitle: Hugo Blox
title: Learn Hugo Blox in 10 minutes!
date: 2025-09-24
type: docs
tags:
- Hugo Blox
- Course
content_meta:
content_type: 'Course'
difficulty: 'Beginner'
prerequisites: ['Markdown']
trending: false
---
值得注意的字段:
tags中的Course是课程中心聚合的"入列凭证"(对应filters.tag: Course);linkTitle用于侧边栏/面包屑中的短名称,title是完整标题;content_meta是可选的课程元数据(类型、难度、前置知识、是否热门),可被列表视图或搜索索引消费;type: docs本身在入口 cascade 中已统一注入,这里即便不写也会被覆盖。
4.2 入门章节:steps 短代码驱动的流程化教程
getting-started.md 展示了课程最常见的开场方式——用 {{% steps %}} 包裹三级标题,把"建站 → 配置 → 写内容 → 发布"编排成带编号的分步教程:
{{% steps %}}
### Create a site
...
### Configure your new site
...
### Add your content
...
### Publish your site
...
{{% /steps %}}
steps 短代码的语法细节记录在 content/courses/hugo-blox/guide/formatting/steps.md:只需在短代码内部使用 Markdown 三级标题 ### 作为步骤标题,其余正文自由书写,渲染时自动编号。该页末尾还用 cards 短代码把后续章节(项目结构、配置、内容创建)做成导航卡片,形成"学完本节下一步去哪"的闭环。
4.3 子章节与命名规范
- 目录即章节:
guide/、reference/各自有_index.md,构成侧边栏一级分组;guide/下声明sidebar.open: true使侧边栏默认展开; - 页面命名二选一:Hugo 允许
TITLE/index.md与TITLE.md两种写法(小写、连字符分隔),二者输出一致。文件夹写法的好处是封面图、音频等素材与页面自包含、便于整体迁移,本项目 formatting 目录即是这种写法; - 列表页必须
_index.md:Hugo 要求首页与归档/列表页带下划线前缀,课程中心入口与各课程首页都遵循该约定,详见 content/courses/hugo-blox/guide/project-structure.md; weight控制顺序:同一目录下按weight升序排列,未设置的按字母序,这是 getting-started.md(weight: 1)排在 guide(weight: 2)之前的原因。
五、课程页面可用的格式化短代码:编写实战
课程正文除了标准 Markdown,还可以使用仓库 content/courses/hugo-blox/guide/formatting 下完整收录的一组短代码,让教程具备按钮、提示框、卡片、折叠与多媒体能力。
5.1 Button:可定制按钮
{{< button url="/contact" >}}Contact Us{{< /button >}}
{{< button url="https://example.com" new_tab="true" style="secondary" >}}Visit External Site{{< /button >}}
支持的参数(完整说明见 button.md):
| 参数 | 类型 | 默认值 | 说明 |
|---|---|---|---|
url |
string | # |
必填,按钮目标地址(内部或外部链接) |
text |
string | 内部内容 | 按钮文案,可覆盖短代码内容 |
new_tab |
boolean | false |
是否新标签页打开 |
style |
string | primary |
样式:primary / secondary / outline / ghost |
size |
string | md |
尺寸:sm / md / lg / xl |
align |
string | left |
对齐:left / center / right |
icon |
string | - | 图标名称(来自 Hero Icons 图标集) |
icon_position |
string | left |
图标位置:left / right |
rounded |
string | md |
圆角:sm / md / lg / xl / full |
disabled |
boolean | false |
是否禁用 |
短代码还会自动处理外链安全属性:外部链接自动加 rel="noreferrer",新标签打开的外部链接加 rel="noopener noreferrer",新标签打开的内部链接加 rel="noopener";同时内置 role="button"、aria-label 与键盘焦点指示等无障碍特性。
5.2 Callout:GitHub/Obsidian 风格提示框
课程写作中常用的提示、警告、重要说明,直接用标准 Markdown 引用语法加类型标签即可,无需短代码:
> [!NOTE]
> This is a note callout with important information that users should know.
> [!WARNING]
> Be careful! This action might have unexpected consequences.
> [!TIP]
> Here's a helpful tip to make your workflow more efficient!
Hugo Blox 支持全部 15+ 种 Obsidian callout 类型,仓库 callout.md 中收录了信息类(NOTE/INFO/ABSTRACT)、行为类(TODO/TIP/SUCCESS)、提问交互类(QUESTION/EXAMPLE/QUOTE)与告警类(WARNING/CAUTION/IMPORTANT/DANGER/FAILURE/BUG)的完整示例。还支持自定义标题:
> [!WARNING]+ Custom Warning Title
> This warning has a custom title instead of just "Warning".
该语法的优势是内容可移植:在 GitHub、Obsidian 等工具中同样成立;渲染时生成语义化的 .callout 类与 data-callout="note" 数据属性,可通过自定义 CSS 精准定制样式。原有的 {{< callout note >}} 旧短代码仍可用但已标记为弃用。文档中提到该特性要求 Hugo 0.132.0 以上版本,本仓库在 hugoblox.yaml 与 netlify.toml 中均将 Hugo 版本固定为 0.162.0,满足前提。
5.3 Cards / Steps / Spoiler:结构化内容三板斧
卡片式导航(cards.md):
{{< cards >}}
{{< card url="../callout" title="Callout" icon="academic-cap" >}}
{{< card url="" title="A card without an icon" >}}
{{< /cards >}}
card 支持 icon(默认 Hero Icons 图标集)、title、subtitle(支持 Markdown)与 url 四个参数。分步教程用 steps,折叠内容用 spoiler(toggle.md):
{{< spoiler text="Click to view the spoiler" >}}
This is the content of the details.
Markdown is **supported**.
{{< /spoiler >}}
这在"先让学生尝试、再点击查看解法"的自测场景中非常实用。
5.4 Media:视频、音频、数学与代码
media.md 是面向课程场景的多媒体手册:
- 视频:
{{< youtube w7Ft2ymGmfc >}}、{{< bilibili id="BV1WV4y1r7DF" >}}一键嵌入;本地视频文件放入页面文件夹或assets/media/媒体库后用{{< video src="my_video.mp4" controls="yes" >}}嵌入; - 音频/播客:将 MP3 放入页面文件夹后
{{< audio src="ambient-piano.mp3" >}}即可。仓库中 content/courses/hugo-blox/guide/formatting/ambient-piano.mp3 正是"页面文件夹内素材"的实证——因为 media.md 与音频文件同目录,属于同一个 page bundle; - LaTeX 数学:先在 config/_default/params.yaml 的
content.math.enable打开开关,再用{{< math >}}$$...$${{< /math >}}包裹块级公式、{{< math >}}$...${{< /math >}}包裹行内公式,可避免 Hugo 把数学符号当作 Markdown 处理; - 代码高亮:代码主题同样在
params.yaml中选择,正文直接书写围栏代码块即可:import pandas as pd data = pd.read_csv("data.csv") data.head() - 行内图标:
{{< icon name="python" >}}可在行内渲染图标。
六、站点级配置支撑
课程中心只是整个站点的内容切片,其运行依赖 config/_default/ 目录下五份配置文件(在 content/courses/hugo-blox/guide/project-structure.md 中也有系统说明):
| 文件 | 职责 |
|---|---|
| hugo.yaml | Hugo 基础配置:站点标题/URL、默认语言(defaultContentLanguage: en)、分页大小、图片处理(resampleFilter: lanczos、quality: 90)、taxonomies(author/tag/publication_type)与输出格式(首页输出 HTML, RSS, headers, redirects, backlinks) |
| module.yaml | 引入 Hugo 模块(netlify 集成、blox 区块引擎、slides 幻灯片)并声明资源挂载 |
| params.yaml | Hugo Blox 站点选项:品牌身份、主题色、数学/目录/阅读时长开关、SEO、搜索、评论、分析、多语言切换等 |
| menus.yaml | 导航菜单定义(含前述 Courses 入口) |
| languages.yaml | 站点语言;文件内置了中文示例:取消 zh 区块注释并配置 contentDir: content/zh、locale: zh-Hans 即可启用多语言,同时将英文内容移入 content/en/ |
与课程直接相关的开关集中在 params.yaml 的 content 段:math.enable 控制 LaTeX 数学渲染、toc.enable 控制右侧目录、reading_time.enable 控制阅读时长显示(课程中心列表页通过 design.show_read_time: false 单独关闭了该项)。
七、构建与发布
课程内容写好后的发布链路由 netlify.toml、package.json 与 hugoblox.yaml 协作完成:
- 构建命令(netlify.toml):
pnpm install→hugo --gc --minify -b $URL→pnpm run pagefind,构建产物输出到public/; - Pagefind 全文索引:
package.json中的pagefind脚本在构建后对public目录建立静态搜索索引,课程页面的 Markdown 内容会被收录进站内搜索; - 本地开发:
package.json提供了pnpm dev(等价于hugo server --disableFastRender)与pnpm build两个脚本; - 版本约束:hugoblox.yaml 与 netlify.toml 均将 Hugo 固定为 0.162.0,Go 版本为 1.21.5,Node 为 22,go.mod 锁定三个 Hugo 模块的精确版本,保证课程所用短代码与模块特性行为一致。
八、小结:这套方案的可复用路径
回顾整条链路,在 Hugo Blox Academic CV 主题中搭建课程中心的完整路径是:
- 在 content/courses/_index.md 用
type: landing+cascade声明课程区并批量注入docs布局与面包屑; - 用
block: collection按tag: Course、kinds: [section]自动聚合所有课程首页为卡片网格; - 在 config/_default/menus.yaml 添加
Courses菜单项暴露入口; - 为每门课程新建目录:
_index.md打上Course标签、weight控制排序,正文使用steps/callout/button/cards/spoiler/media短代码编写教程; - 按 hugoblox.yaml 的版本约束在 Netlify 等平台自动构建,配合 Pagefind 让课程内容可被站内搜索。
由于数据(content 目录的 Markdown)与样式(landing 页的 design 段)完全分离,这套方案对个人学术主页、在线课程站点同样适用:只需更换 content/courses/ 下的课程内容与 filters.tag,即可在不触碰任何模板代码的前提下获得一套完整的课程中心。