用 Hugo Blox Academic CV 主题搭建课程中心:landing 页面、collection 聚合与课程内容组织

原创2026-10-13 07:31:381,443 阅读
文章标签:前端CMS

用 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 主题中搭建课程中心的完整路径是:

  1. 在 content/courses/_index.md 用 type: landing + cascade 声明课程区并批量注入 docs 布局与面包屑;
  2. 用 block: collection 按 tag: Course、kinds: [section] 自动聚合所有课程首页为卡片网格;
  3. 在 config/_default/menus.yaml 添加 Courses 菜单项暴露入口;
  4. 为每门课程新建目录:_index.md 打上 Course 标签、weight 控制排序,正文使用 steps/callout/button/cards/spoiler/media 短代码编写教程;
  5. 按 hugoblox.yaml 的版本约束在 Netlify 等平台自动构建,配合 Pagefind 让课程内容可被站内搜索。

由于数据(content 目录的 Markdown)与样式(landing 页的 design 段)完全分离,这套方案对个人学术主页、在线课程站点同样适用:只需更换 content/courses/ 下的课程内容与 filters.tag,即可在不触碰任何模板代码的前提下获得一套完整的课程中心。

登录后查看全文
hugo-theme-academic-cv