用 Hugo Blox 与 Reveal.js 打造 Markdown 幻灯片:slides 内容类型与 front matter 全面指南

原创2026-09-23 12:50:081,653 阅读
文章标签:静态站点前端开发工具

用 Hugo Blox 与 Reveal.js 打造 Markdown 幻灯片:slides 内容类型与 front matter 全面指南

导读

本指南围绕 Hugo Blox Builder 中 slides 内容类型的创建、配置与渲染展开,核心载体是 slides 内容类型模板 与 blox-plugin-reveal 模块。在 Hugo Blox 生态中,你只需维护一个 Markdown 文件,用 --- 分隔每一页幻灯片,再配合 front matter 中的 slides 配置节,即可生成一套支持数学公式、语法高亮、Mermaid 图表、演讲者备注、分段动画与缩略菜单的 Reveal.js 演示文稿。读完本文,你将掌握:如何用 hugo new 快速创建幻灯片、如何逐项理解并调优 front matter 中的每个配置参数、如何利用自定义 shortcode 实现分片动画与备注,以及这些配置在底层源码中是如何被解析和生效的。


一、slides 内容类型是什么

slides 是 Hugo Blox Builder 预置的一种内容类型,专门用于渲染基于 Reveal.js 的演示文稿。其标准脚手架模板位于 modules/blox-bootstrap/archetypes/slides/index.md,当你执行 hugo new slides/my-deck/index.md 时,Hugo 会根据该 archetype 自动生成一个带完整 slides front matter 配置的 Markdown 文件。

这一能力由 blox-plugin-reveal 提供,该插件是 Hugo 与 Reveal.JS 之间的桥接层,其 README 中明确说明:它能让你"使用开放、面向未来的 Markdown 标准轻松创建、分享和演示幻灯片",并支持数学公式、语法高亮、图表、演讲者备注等多种能力。

1.1 安装方式

要使用幻灯片功能,需要先安装 blox-plugin-reveal 模块。根据其 README,在 config/_default/config.yaml 中声明模块导入:

module:
  imports:
    - path: github.com/HugoBlox/hugo-blox-builder/modules/blox-plugin-reveal

从模块的 config.yaml 可以看到,该模块仅挂载 assets 与 layouts 两个目录,并依赖 blox-core,本身不包含内容目录——这意味着幻灯片内容完全由站点自身的 content/slides/ 目录提供。

1.2 渲染管线概述

一份 slides/index.md 从 Markdown 到可演示的 HTML 需要经过两条主要链路:

  1. 页面渲染:content/slides/ 下的页面由 layouts/slides/baseof.html 定义 HTML 骨架,layouts/slides/single.html 与 layouts/slides/list.html 定义主体内容;list.html 通过 partial "slides" (union (slice .Page) .Pages) 将当前页面及其子页面合并传入。
  2. 幻灯片切分:layouts/partials/slides.html 遍历每个页面内容,按 <hr>(即 Markdown 中的 ---)分割,将每一段包裹进一个 <section>,对应一页幻灯片;随后 assets/js/wowchemy-slides.js 读取 front matter 中的 slides.reveal_options,完成驼峰命名转换后调用 Reveal.initialize()。

二、用 archetype 快速创建幻灯片

archetype 模板 是创建新幻灯片的起点,其中 title 字段使用 Hugo 模板语法 {{ replace .Name "-" " " | title }} 自动把文件名中的连字符替换为空格并转为标题格式,date 自动填充当前时间。

创建方式:

hugo new slides/my-talk/index.md

生成的文件默认内容如下(省略 front matter 注释):

---
title: "My Talk"
summary: ""
authors: []
tags: []
categories: []
date: 2026-09-23T07:37:54+08:00
slides:
  theme: black
  highlight_style: dracula
  diagram: true
  diagram_options:
    theme: base
  reveal_options:
    controls: true
    progress: true
    slide_number: c/t
    center: true
    rtl: false
    mouse_wheel: true
    transition: fade
    transitionSpeed: default
    background_transition: slide
    touch: true
    loop: false
    menu_enabled: true
---

# Title

Author Name

---

## Slide 2

...

正文部分的结构即"演示文稿骨架":# Title 与作者姓名组成第一页幻灯片,--- 之后的 ## Slide 2 及后续内容依次组成后续幻灯片。每一组被 --- 分隔的内容在渲染时对应一页。

注意:该 archetype 会随 Hugo 版本更新而演进,若希望模板行为可控,可将模板文件复制到站点自身的 archetypes/ 目录进行定制。


三、front matter 配置逐项解析

slides 配置节是整份幻灯片的"控制台",所有关键行为都由它决定。以下逐项说明,默认值依据 archetype 模板与实际源码推断得出。

3.1 主题与代码高亮

slides:
  # 幻灯片主题,可选值参见 Reveal.js 官方主题列表
  theme: black
  # 代码高亮风格;浅色用 github,深色用 dracula(默认)
  highlight_style: dracula
  • theme:决定整套幻灯片的视觉风格。加载逻辑在 baseof.html:$theme := $.Param "slides.theme" | default "black",然后从 CDN 加载 dist/theme/{theme}.min.css。Reveal.js 官方内置主题包括 black、white、league、sky、beige、simple、serif、night、moon、solarized 等。
  • highlight_style:控制代码块的语法高亮配色。源码 baseof.html 会尝试在 assets/css/libs/chroma/{style}.css 下寻找对应的 Chroma 主题样式表;找不到时直接抛出构建错误,提示用 hugo gen chromastyles 生成。当前仓库 assets/css/libs/chroma 预置了 dracula.css、github-dark.css、github-light.css 三个主题,分别对应深色、浅色与深色 GitHub 风格。因此若使用默认 dracula,可直接开箱即用;若自定义其他 Chroma 主题,需先按 Hugo 官方方式生成 CSS 并放入该目录。

3.2 Mermaid 图表

slides:
  diagram: true
  diagram_options:
    # Mermaid 图表主题可选:default、base、dark、neutral、forest
    theme: base
  • diagram:是否启用 Mermaid 图表(默认 false)。启用后,baseof.html 会按固定版本 mermaid@9.1.3 从 jsDelivr 加载 Mermaid,并带上 SRI 完整性校验。
  • diagram_options:传给 Mermaid 的初始化选项。在 wowchemy-slides.js 中,只有当 diagram 为真时才会 mermaid.initialize(mermaidOptions),并强制追加 startOnLoad: false,因为幻灯片中的图表需要懒渲染:脚本监听 Reveal 的 ready 与 slidechanged 事件,仅当某页幻灯片被激活时,才渲染其中尚未渲染的 .mermaid 元素(见 wowchemy-slides.js),避免一次性渲染全部图表拖慢启动。

3.3 Reveal.js 运行时选项

slides:
  reveal_options:
    controls: true       # 是否显示导航箭头
    progress: true       # 是否显示底部进度条
    slide_number: c/t    # true | false | h.v | h/v | c | c/t
    center: true         # 内容是否垂直居中
    rtl: false           # 是否从右到左排版(阿拉伯语等)
    mouse_wheel: true    # 是否允许鼠标滚轮翻页
    transition: fade     # none/fade/slide/convex/concave/zoom
    transitionSpeed: default  # default/fast/slow
    background_transition: slide  # none/fade/slide/convex/concave/zoom
    touch: true          # 是否支持触摸滑动
    loop: false          # 是否循环播放
    menu_enabled: true   # 是否启用缩略菜单插件

这一节与 Reveal.js 官方初始化选项一一对应,archetype 中的注释明确说明:选项名采用 Reveal.js 文档中选项的蛇形命名(snake case)形式。也就是说,Reveal.js 中的 slideNumber、mouseWheel、transitionSpeed、backgroundTransition、menu 等驼峰命名,在此处应写成 slide_number、mouse_wheel、transition_speed、background_transition。

底层的转换逻辑在 wowchemy-slides.js:脚本将 front matter 中的 slides.reveal_options 读出后,先经 toCamelCase() 把 snake_case 递归转换为 camelCase,再传给 Reveal.initialize(pluginOptions)。这保证了蛇形命名最终以 Reveal.js 期望的驼峰形式生效。

各选项含义:

  • controls / progress / center / touch / loop:布尔开关,分别控制导航控件、进度条、垂直居中、触摸与循环。
  • slide_number:页码显示格式,c/t 表示"当前页/总页数",h.v 显示层级坐标,c 只显示当前页,false 关闭。
  • rtl:从右到左模式,适合希伯来语、阿拉伯语等内容。
  • mouse_wheel:滚轮翻页,配合 transition 可营造"滚动式演示"体验。
  • transition 与 background_transition:幻灯片与背景的切换动画,可选 none、fade、slide、convex、concave、zoom。
  • transitionSpeed:动画速度,注意它本身是驼峰命名(archetype 中即如此),可选 default、fast、slow。
  • menu_enabled:Hugo Blox 对 reveal.js-menu 插件的开关。默认启用,baseof.html 会从 CDN 加载 reveal.js-menu@2.1.0 的脚本与样式;JS 侧则在 wowchemy-slides.js 中,仅在未显式设置时默认置为 true,启用后把 RevealMenu 加入插件列表,演示时可通过菜单快速跳转页面。

3.4 插件组合

无论 front matter 如何配置,wowchemy-slides.js 固定启用五个核心插件:

var enabledPlugins = [RevealMarkdown, RevealSearch, RevealNotes, RevealMath.KaTeX, RevealZoom];

对应 baseof.html 中加载的 markdown、notes、search、math、zoom 五个官方插件,分别提供 Markdown 解析、演讲者备注(按 S 键打开)、内容搜索(按 Ctrl/Cmd + F)、KaTeX 数学公式渲染与局部缩放(点击/聚焦后缩放)。menu_enabled 开启时再追加 RevealMenu。


四、幻灯片正文的写作规范

4.1 用 --- 分隔页面

正文部分以 Markdown 书写,---(渲染为 HTML 的 <hr>)是页面分隔符。切分逻辑在 layouts/partials/slides.html:模板按 <hr> 将整篇内容 split 成多段,每段包进一个 <section>。同时模板会检查该段是否包含 data-noprocess 标记——如果由自定义 slide shortcode 生成了 <section>,则不再重复包裹,避免产生嵌套错误。

一个最小示例:

---
title: "Demo"
slides:
  theme: black
---

# 第一页

- 要点 A
- 要点 B

---

## 第二页

这里放第二页内容。

提示:由于分割基于 <hr>,正文中若使用脚注等会生成 <hr> 的语法需谨慎,Goldmark 渲染器下 --- 即水平线,保持"一页一组、--- 分隔"的规律即可。Blox 的 hugo.yaml 采用 Goldmark 渲染器并开启 unsafe: true,因此正文中也可直接嵌入原始 HTML。

4.2 每个页面的 HTML 结构

baseof.html 为整个演示文稿提供 <html> 骨架,加载了主题 CSS、Chroma 高亮样式、Reveal.js 及其插件,最后通过 js.Build 编译 wowchemy-slides.js 并注入 slides 参数。如果你需要为所有幻灯片追加自定义样式,可在站点 assets/css/reveal_custom.css 提供文件,baseof.html 会自动检测并合并压缩引入。


五、进阶:三个实用 shortcode

blox-plugin-reveal 提供三个 shortcode,让单页幻灯片内部具备更强的表现力,源码分别位于 shortcodes 目录。

5.1 {{< slide >}}:细粒度控制单页属性

slide.html 会生成一个带 data-noprocess data-shortcode-slide 属性的 <section>,并把传入的每个参数转换为 data-* 属性(id、class 除外)。因此你可以在页内直接声明 Reveal.js 的 section 级特性,例如:

{{< slide background-color="#0f4c81" transition="zoom" id="intro" class="center" >}}

# 带背景色的标题页

{{< /slide >}}

渲染结果为:

<section data-noprocess data-shortcode-slide data-background-color="#0f4c81" data-transition="zoom" id="intro" class="center"> ... </section>

由于该 <section> 已自带 data-noprocess,slides.html 不会对它再包一层 <section>,避免结构错乱。background-color、background-image、transition、data-state 等属性均可通过这种方式配置。

5.2 {{< fragment >}}:分段动画

fragment.html 将内容包进 <span class="fragment ...">,实现"逐条出现"的动画:

## 三段式结论

{{< fragment >}}第一点先出现{{< /fragment >}}

{{< fragment class="fade-in" weight="2" >}}第二点随后出现{{< /fragment >}}
  • class 追加额外 CSS 类(如 fade-in、highlight-red);
  • weight 设置 data-fragment-index,控制多条碎片之间的出现顺序。

5.3 {{< speaker_note >}}:演讲者备注

speaker_note.html 生成 <aside class="notes">,其中的内容只在按 S 键弹出的演讲者视图(RevealNotes 插件)中可见:

{{< speaker_note >}}
这里提醒自己:先讲背景,再讲方案,最后给 Demo。
{{< /speaker_note >}}

六、从内容到演示:一次完整的运行路径

将以上内容串起来,一份幻灯片从创建到演示的完整路径如下:

  1. 创建:hugo new slides/my-talk/index.md,基于 archetype 生成带默认配置的文件。
  2. 写作:按需修改 slides.theme、highlight_style、diagram、reveal_options,用 --- 分页,嵌入图表、公式、shortcode。
  3. 构建:Hugo 依据 slides/single.html 与 slides/list.html 输出页面;baseof.html 完成资源加载。
  4. 切分:slides.html 按 <hr> 将内容切分为多个 <section>。
  5. 初始化:wowchemy-slides.js 把 front matter 配置转为驼峰命名,装配插件,调用 Reveal.initialize(),并在 ready/slidechanged 时懒渲染 Mermaid 图表。
  6. 演示:浏览器打开页面,按 S 打开备注,Ctrl/Cmd + F 搜索,Alt + 点击实现缩放,通过菜单插件快速跳转。

七、常见问题与排查建议

  • 自定义高亮主题报错:若 highlight_style 指向的 Chroma 主题 CSS 不存在,构建会失败并提示 Hugo Chroma themes xxx.css not found in css/libs/chroma/(见 baseof.html)。解决方法:使用 hugo gen chromastyles 生成对应 CSS 放入站点 assets/css/libs/chroma/ 目录,或直接使用仓库预置的 dracula / github-light / github-dark 三者之一。
  • Mermaid 图表不显示:确认 diagram: true 已开启,且图表代码放在 ```mermaid 代码块中;渲染依赖当前页处于激活状态(懒渲染机制),翻页后会自动出现。
  • --- 被当成页面分隔符:正文如需真实水平线,注意它会被视为新页面的开始,请改用其他排版方式。
  • 自定义主题文件:需要给所有页面追加样式时,在站点 assets/css/reveal_custom.css 中书写即可,无需改动插件源码。

八、参考资源

登录后查看全文
kit