Hugo Blox Course 课程门户:基于 Portfolio 组件构建在线课程导航与筛选页面

原创2026-09-24 19:37:041,825 阅读
文章标签:静态站点前端开发工具

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 视图等能力,将其复用于博客归档、项目作品集等任意列表型页面。

登录后查看全文
kit