Hugo Blox Course 课程门户:基于 Portfolio 组件构建在线课程导航与筛选页面
Hugo Blox Course 课程门户:基于 Portfolio 组件构建在线课程导航与筛选页面
导读
本文以 Hugo Blox Builder 仓库中在线课程模板的首页区块 starters-bootstrap/course/content/home/courses.md 为蓝本,完整讲解如何用 Portfolio(作品集)组件在首页搭建一个带分类筛选按钮、瀑布流卡片视图的课程门户。读完本文,你将掌握 Portfolio 组件的全部 front matter 配置项(筛选条件、排序、按钮组、视图模式)及其背后的源码渲染原理,能够照搬到自己的课程站、博客或作品集页面中。
一、场景定位:课程首页的 "Explore top courses" 区块
在 starters-bootstrap/course 这一在线课程 Starter 中,首页是一个由多个 headless 区块按 weight 顺序拼接而成的组件页(widget page),其入口为 starters-bootstrap/course/content/home/index.md。而 courses.md 正是其中承担"课程列表展示"职能的区块,完整内容如下:
---
widget: portfolio
headless: true
weight: 30
title: Explore top courses
subtitle:
content:
filters:
folders:
- course
kinds:
- section
exclude_tags:
- preface
filter_default: 0
filter_button:
- name: All Courses
tag: '*'
- name: Previous
tag: previous
- name: Current
tag: current
design:
columns: '1'
view: masonry
flip_alt_rows: false
---
它完成了三件事:定位数据源(只取 content/course/ 下的 section 页面并排除 preface 标签)、提供筛选按钮(全部 / 往期 / 当前)、指定展示形态(单列布局 + 瀑布流卡片)。其余区块依次为 hero.md(weight 10,引导横幅)、features.md(weight 20,特性介绍)、people.md(weight 40,讲师团队),它们共同拼出课程站首页。
二、数据来源:filters 筛选体系
content.filters 决定了"页面要展示哪些课程内容",共四个维度:
| 配置项 | 示例值 | 作用 |
|---|---|---|
folders |
- course |
只收集位于 course section 下的页面(对应 where $query "Section" "in" .) |
kinds |
- section |
只保留 Kind 为 section 的页面(对应 where $query "Kind" "in" .) |
exclude_tags |
- preface |
从结果中剔除带 preface 标签的页面 |
tags |
可选 | 反向限定"只保留含某标签的页面"(源码中为 intersect 语义) |
对应实现位于 modules/blox-bootstrap/layouts/partials/blocks/v1/portfolio.html:先以 site.Pages 为全集,依次执行 Section 过滤、标签交集过滤、exclude_tags 差集过滤(symdiff)与 Kind 过滤,最后再按 sort_by(默认 Date)与 order 排序。
在本模板中,exclude_tags: preface 的用意是:content/course/_index.md 这个"课程总览页"带有 tags: [preface] 标签,它本身只是一个引导性入口,不应混入课程卡片列表;真正进入瀑布流的是两个课程目录 data-science 与 robotics(其 _index.md 分别带 current 与 previous 标签)。在 course/_index.md 中还可以看到 type: page 与 view: compact 的设置,说明总览页用的是紧凑列表视图,与首页卡片视图形成互补。
三、筛选按钮:filter_button 与 filter_default
content.filter_button 定义用户可见的筛选标签,每个按钮由 name(显示文本)与 tag(过滤规则)构成:
tag: '*'表示"不过滤",显示全部课程;tag: previous与tag: current分别对应课程目录_index.md中tags里的previous、current。
content.filter_default: 0 指定默认激活第 0 个按钮(即 All Courses)。从源码看,其解析逻辑为:取 filter_button 列表中索引为 filter_default 的项,若该项提供了 filter 字段则直接使用,否则把 tag 转换成 CSS 类名——* 或 . 开头原样保留,普通标签则转成 .js-id-<标签小写、空格转连字符> 的格式;同时每个页面的 tags 也会被转换成相同的 js-id-* 类名(见 portfolio.html 第 95 行),按钮点击与卡片筛选正是通过这套统一的类名体系在浏览器端由 Isotope 完成的。
需要留意两点:一是"仅当按钮数量大于 1 时才渲染按钮工具栏"(if gt (len $block.Params.content.filter_button) 1),因此至少要定义两个按钮才会显示筛选条;二是 tag 的值必须与课程目录 front matter 中的 tags 完全一致(大小写与连字符都会影响匹配),本示例中 data-science/_index.md 的 tags: [current] 对应按钮 Current,robotics/_index.md 的 tags: [previous] 对应按钮 Previous。
四、展示形态:design 区配置
design 区块控制区块的视觉呈现:
| 配置项 | 示例值 | 说明 |
|---|---|---|
columns |
'1' |
区块列数。源码中 '2' 时卡片区被限制在 col-lg-8 内,'1' 则独占整行,标题区居中 |
view |
masonry |
卡片视图模式,还有 compact、card、showcase、list、citation 等 |
flip_alt_rows |
false |
卡片行交替翻转(仅对两列布局有意义) |
view: masonry 会激活瀑布流布局与 Isotope 筛选容器(portfolio.html 第 65 行的容器 class 同时包含 isotope projects-container 与 js-layout-masonry)。卡片渲染由 modules/blox-bootstrap/layouts/partials/views/masonry.html 承担:它会优先取页面 summary 作为摘要,取 featured 特色图(如 starters-bootstrap/course/content/course/data-science/featured.jpg)并缩放到 550px 宽、非 GIF 自动转 WebP,输出为 card 卡片。若把 view 改成 compact,则会改用 views/compact.html 的紧凑列表样式(标题 + 摘要 + 150px 缩略图),适合信息密度更高的场景;render_view.html 中也会在视图文件缺失时回退到 compact。
五、课程内容页:与区块配套的内容组织
Portfolio 区块只是"容器",真正被它收集的课程目录需要按下面的结构组织(以 starters-bootstrap/course/content/course/data-science/ 为例):
_index.md:课程项目首页。front matter 中type: book启用 Book 布局(modules/blox-bootstrap/layouts/book/single.html即调用book_layout.html渲染三栏:左侧章节菜单、中间正文、右侧目录),tags: [current]供首页筛选,正文通过{{< list_children >}}列出子章节、{{< mention "admin" >}}关联讲师、{{< spoiler >}}折叠 FAQ、{{< cta cta_text="Begin the course" cta_link="python" >}}生成报名按钮;python.md/stats.md/visualization.md:具体课时页面,同样type: book,用weight控制章节顺序,可内嵌视频({{< youtube >}})、LaTeX 公式(math: true时生效)与测验(spoiler)。
其中 {{< list_children >}} 的源码在 modules/blox-bootstrap/layouts/shortcodes/list_children.html:只要当前页面存在子页面,就输出一个无序列表,每项以 LinkTitle(回退到文件名)为标题,并在 show_summary 未显式设为 false 时附带摘要,这与 Book 布局在正文为空时自动列出子页的行为一致。
讲师信息则由 content/authors/admin/_index.md 定义,其中 role: Python Instructor 与 user_groups: [Teachers] 会被首页 people.md 区块(widget: people)消费,而 {{< mention "admin" >}} 通过 site.GetPage "/authors/admin" 解析成讲师主页链接(见 modules/blox-bootstrap/layouts/shortcodes/mention.html)。
六、把区块接入首页与导航
courses.md 的 headless: true 使其成为"无独立 URL 的页面资源",由首页统一渲染。widget_page.html 会读取首页目录下所有 Params.active != false 的页面资源,按 weight 排序后逐个交给 parse_block_v1.html 解析为对应区块(widget: portfolio 被映射到 blocks/v1/portfolio.html),因此调整区块上下顺序只需改 weight,禁用区块可设 active: false。
要让课程区块在导航栏可见,还需在 starters-bootstrap/course/config/_default/menus.yaml 中登记:示例中主菜单的 Courses 项带 identifier: courses,其下挂两个子项 Data science 与 Robotics,分别用 PageRef 指向 course/data-science/_index.md 与 course/robotics/_index.md。这样首页卡片与顶部菜单指向的是同一批课程目录,URL 保持一致。
七、构建与本地预览
该 Starter 通过 Hugo Modules 引入构建模块,依赖声明在 starters-bootstrap/course/go.mod(blox-bootstrap/v5 v5.9.7 与 blox-plugin-netlify),模块导入配置在 config/_default/module.yaml。若需本地运行:
hugo mod get -u ./...
hugo server
站点级外观与功能在 starters-bootstrap/course/config/_default/params.yaml 中统一控制(如 appearance.font: minimal、features.math、search.provider: wowchemy),hugo.yaml 中则包含 cascade 区块,例如对 /course/** 路径自动开启 editable: true 与 show_breadcrumb: true,对 /post/** 自动开启相关文章推荐,这些默认值会自动应用到你新建的每个课程页面。
八、小结
courses.md 用不到二十行 front matter 就完成了课程门户的核心闭环:filters 圈定数据、filter_button 提供交互筛选、design.view: masonry 决定瀑布流卡片形态,再与 Book 布局课程页、讲师作者页和顶部菜单联动。参照 modules/blox-bootstrap/layouts/partials/blocks/v1/portfolio.html 及其配套视图模板,你可以继续扩展出按 tags 交集筛选、自定义排序(sort_by / order)、更换 card / showcase 视图等能力,将其复用于博客归档、项目作品集等任意列表型页面。