Hugo Blox Builder 在线课程 Book 布局实战:以 Plotly 数据可视化课为例
Hugo Blox Builder 在线课程 Book 布局实战:以 Plotly 数据可视化课为例
本篇技术指南以 starters-bootstrap/course 在线课程 Starter 中的 可视化课程页 为骨架,讲解如何用 Hugo Blox Builder 的 Book 布局编写一门结构完整的在线课程单元:从 front matter 元数据、时间投入标注,到 YouTube 视频嵌入、Plotly 数据可视化代码示例与可折叠测验(spoiler)的实现细节。读完本文,你将掌握课程页面的组织方式、底层短代码的渲染原理,以及如何把这些内容接入 Hugo 的模块体系并本地运行。
课程页在项目中的位置与作用
该文档位于在线课程 Starter 的 Robotics(机器人学)课程目录下:
- 课程目录 _index.md:课程主页,声明课程目标、讲师与 FAQ,并通过
{{< list_children >}}自动列出子课程; - Python basics(
weight: 20):Python 基础单元; - visualization.md(本文主角,
weight: 30):数据可视化单元,主题为 Plotly; - Statistics(
weight: 40):统计学单元。
三页通过 front matter 中的 weight 决定排序:Python → Visualization → Statistics,正好对应课程主页中"数据可视化用 Plotly、数据整理用 Pandas"的学习目标。weight 越小越靠前,weight: 30 使本页排在第二顺位。
Front matter:一页课程单元的元数据设计
课程页使用 type: book,让 Hugo 将该页面交给 Book 布局渲染。以可视化页为例,其 front matter 结构如下:
---
title: Visualization
date: '2021-01-01'
type: book
weight: 30
highlight: true
tags:
- Data Visualization
---
各字段含义与用法:
| 字段 | 值 | 作用 |
|---|---|---|
title |
Visualization | 页面标题,渲染为 Book 布局中的 <h1>(见 book_layout.html); |
date |
'2021-01-01' |
发布日期,用于站点的时间排序与"最后更新"信息展示; |
type |
book |
核心字段,指定布局为 Book(docs)布局,由 book/single.html 接管渲染; |
weight |
30 |
侧边栏章节排序权重,决定该页在课程导航中的位置; |
highlight |
true |
启用代码高亮,配合 params.yaml 中 features.syntax_highlighter 配置的主题(亮色 github-light、暗色 dracula); |
tags |
Data Visualization | 分类标签,会被 related 索引用于相关文章推荐(见 hugo.yaml)。 |
对比同目录的 stats.md 会发现其额外声明了 math: true 并启用 LaTeX 公式,而 python.md 则没有 highlight 与 tags。这说明 front matter 是按页按需开启能力的机制,可视化课因需要展示 Plotly 代码而开启高亮,统计学课因需要公式排版而开启数学支持。
课程单元的标准内容骨架:Learn + Quiz
可视化页正文遵循稳定的三段式结构,这也是在线课程 Starter 所有单元共用的模式:
{{< icon name="clock" pack="fas" >}} 1-2 hours per week, for 8 weeks
## Learn
{{< youtube hSPmj7mK6ng >}}
## Quiz
{{< spoiler text="When is a heatmap useful?" >}}
Lorem ipsum dolor sit amet, consectetur adipiscing elit.
{{< /spoiler >}}
时间投入标注:icon 短代码
{{< icon name="clock" pack="fas" >}} 渲染 Font Awesome 的时钟图标,其实现位于 icon.html:
name:图标名,如clock;pack:图标包,默认fas(Font Awesome Solid),也支持fab、far、fal,代码会将fa*前缀统一映射为fa-;padding_right默认1,防止压缩 HTML 时图标与文字粘连。
视频嵌入:youtube 短代码
{{< youtube hSPmj7mK6ng >}} 使用 Hugo 内置的 youtube 短代码,仅需传入视频 ID 即可生成响应式 iframe 嵌入。该短代码由 Hugo 核心提供,无需在模块中额外定义,课程作者只需在 hugo.yaml 配置的基础上直接书写即可。
可折叠测验:spoiler 短代码
Quiz 段落用 {{< spoiler text="..." >}}...{{< /spoiler >}} 实现"点击展开答案"的交互。其底层实现见 spoiler.html:
<details class="spoiler {{ .Get "class" }}" {{ with .Get "style" }}style="{{ . | safeCSS }}"{{ end }} id="{{$id}}">
<summary>{{ .Get "text" | markdownify | emojify }}</summary>
<p>{{ .Inner | markdownify | emojify }}</p>
</details>
关键点:
- 基于原生 HTML
<details>/<summary>实现,无需 JavaScript,天然支持无障碍访问; $id通过.Ordinal生成唯一的spoiler-N锚点 ID,同一页面多个测验互不冲突;- 摘要标题与正文都经过
markdownify(支持 Markdown 语法)与emojify(支持 emoji 短代码)处理,因此 spoiler 内部可以嵌套代码块、公式甚至其他短代码。
可视化页的第二个 spoiler 正是嵌套了 Python 代码块的典型用法——这也是 Quiz 段落能承载"写 Plotly 代码渲染柱状图"这类编程题的原因。
核心教学内容:用 Plotly Express 渲染柱状图
Quiz 中给出了可直接运行的 Plotly 代码示例:
import plotly.express as px
data_canada = px.data.gapminder().query("country == 'Canada'")
fig = px.bar(data_canada, x='year', y='pop')
fig.show()
逐行解读:
import plotly.express as px:Plotly Express 是 Plotly 的高级 API,用极简代码即可生成交互式图表;px.data.gapminder():加载内置的 gapminder 数据集(包含各国历年人口、GDP、预期寿命等字段),该函数会自动从 Plotly 自带的示例数据源获取并缓存;.query("country == 'Canada'"):使用 pandas 风格的字符串查询语法,筛选出加拿大一国的数据,得到year与pop(人口)两列;px.bar(data_canada, x='year', y='pop'):按年份为 x 轴、人口为 y 轴构建柱状图;fig.show():在浏览器或 notebook 环境中渲染出可缩放、可悬停查看数值的交互式图表。
如果把第 3 步的筛选去掉,直接对全量数据执行 px.bar(data, x='year', y='pop', color='country'),就能得到多国分组柱状图——这是从该示例延伸到"分组柱状图"教学的自然提问点。同时,可视化页 front matter 中 tags: Data Visualization 与 highlight: true 的组合,保证了该代码块在暗色 dracula / 亮色 github-light 主题下获得正确的语法着色,便于学习者直接阅读。
从页面到页面:Book 布局如何渲染课程单元
当 Hugo 遇到 type: book 的页面时,渲染链如下:
- book/single.html 作为模板入口;
- 调用 book_layout.html,输出三栏结构:左侧
docs-sidebar(课程章节导航)、中间正文区、右侧docs-toc(本页目录)。
book_layout.html 中与课程页直接相关的行为:
- 面包屑:
show_breadcrumb为 true 时渲染路径导航(该配置由 hugo.yaml 中的 cascade 对/course/**全局开启); - 目录(ToC):默认渲染,除非页面显式声明
toc: false,可视化页未声明因此自动获得右侧"On this page"目录; - 封面图:通过
get_featured_image查找同目录的featured.jpg并裁剪为1800x310 webp横幅(Robotics 课程目录下确实存在 featured.jpg); - 页脚组件:
tags.html渲染标签、"last updated" 时间、page_edit(配合editable: true提供编辑链接)以及上一页/下一页翻页器——weight: 20/30/40的排序直接影响翻页顺序。
把课程单元接入站点:配置三件套
要让可视化页在站点导航与模块体系中被正确加载,依赖以下配置:
- menus.yaml:导航菜单通过
PageRef: course/robotics/_index.md注册 "Robotics" 菜单项并挂在courses标识符下,与 "Data science" 并列; - module.yaml:导入
blox-bootstrap/v5与blox-plugin-netlify两个模块,前者提供 Book 布局与全部短代码(spoiler、icon 等),后者提供 Netlify 部署的 headers/redirects 支持; - hugo.yaml:
cascade对/course/**统一开启editable: true与show_breadcrumb: true,使每个课程单元页自动获得编辑入口与面包屑,无需逐页重复声明。
在本地运行该课程 Starter 的命令为(需已安装 Hugo Extended 与 Go):
cd starters-bootstrap/course
hugo server
浏览器打开 http://localhost:1313 后,通过导航进入 Robotics 课程,即可看到可视化单元:左侧侧边栏按 weight 顺序列出三个子单元,正文区依次呈现时间标注、视频、Quiz 折叠块与高亮后的 Plotly 代码。
小结
一个课程单元页 = front matter 声明能力(type: book、weight、highlight、math)+ 标准化的 Learn/Quiz 内容结构 + 一组底层短代码(icon、youtube、spoiler)+ Book 布局的自动渲染。以可视化课为例,spoiler 的 <details> 实现让"隐藏答案、点击展开"零依赖开箱即用,Plotly Express 示例则让测验题兼具教学价值与可运行性。这套模式可以完全复刻到数据科学课程的同名页面 visualization.md 以及任何自定义课程单元中——你只需要替换 front matter 的 weight、title 与正文内容,Hugo Blox Builder 会自动完成导航、目录、翻页与标签的组装。