企业官网建设流程全解析

• 前端

本指南以hugo-theme-academic-cv（基于 HugoBlox Kit 构建的学术主页模板）为背景，系统讲解如何在课程教学页面中嵌入视频（YouTube / Bilibili / 本地视频文件）、播客音频、可折叠答案、LaTeX 数学公式、代码高亮与行内图标等富媒体内容。读完本文，你将掌握cite、youtube、bilibili、video、audio、spoiler、math、icon等 shortcode 的完整写法与参数，并能在不编写任何 HTML 的情况下，用纯 Markdown + YAML 构建出可直接上线授课的课程页面。

文章背景与适用场景

HugoBlox Kit 的设计目标，是让技术内容创作者获得"无缝体验"：你只需专注于内容本身，而模板（本仓库即其 Academic CV 模板）负责渲染。在content/blog/teach-courses/index.md中，官方示范了如何在课程页面中嵌入视频、播客、代码、LaTeX 数学，甚至用折叠块来"考学生"。这份文档是教学类页面最直接的写作范本，配套的content/courses/hugo-blox/guide/formatting/目录则提供了更完整的 shortcode 参考（media、toggle、callout、button、cards、steps 等）。

本文按原文档骨架逐节展开，并结合仓库内的 params.yaml 配置、hugo.yaml 配置、go.mod（声明了github.com/HugoBlox/kit/modules/blox等模块依赖）以及 package.json（内含dev/build/pagefind脚本）补充实现细节与实操提示，帮助你"知其然，也知其所以然"。

一、引用文献：cite shortcode

在课程页面上引用出版物时，可使用citeshortcode，从content/publications/下的任意页面拉取引用信息：

{{< cite page="/publications/preprint" view="citation" >}}

也可以省略view参数，使用默认视图：

{{< cite page="/publications/conference-paper" >}}

page参数指向出版物页面在内容树中的路径（以/开头）。以仓库中的 content/publications/conference-paper/index.md 为例，其 front matter 中声明了publication_types: ['paper-conference']、peer_reviewed: true、open_access: true、license: CC-BY-4.0以及 DOI 等标准标识符；content/publications/preprint/index.md 则展示了 preprint 类型（publication_types: ["article"]、peer_reviewed: false）与 arXiv ID 的写法。这些结构化字段正是 cite shortcode 生成规范引用条目的数据来源。

提示：全局引用样式由 config/_default/params.yaml 中的hugoblox.content.citations.style控制（可选apa/mla/chicago/ieee，默认apa）。如果你想统一换用 IEEE 或 Chicago 风格，改这一处即可。

二、嵌入视频：youtube / bilibili / video 三种方式

课程教学最常用的是视频。HugoBlox 提供三种方式，按内容来源选择：

2.1 YouTube

直接给出视频 ID 即可：

{{< youtube D2vj0WcvH5c >}}

渲染效果即在页面内嵌一个可播放的 YouTube 播放器。

2.2 Bilibili

面向国内学生的课堂，可嵌入 Bilibili 视频：

{{< bilibili BV1WV4y1r7DF >}}

注意：原文档（content/blog/teach-courses/index.md）与配套课程文档 content/courses/hugo-blox/guide/formatting/media.md 在 Bilibili 写法上略有差异——前者为位置参数{{< bilibili BV1WV4y1r7DF >}}，后者为具名参数{{< bilibili id="BV1WV4y1r7DF" >}}。两者都接受 BVID，建议在写作时保持一种写法全站统一。

2.3 本地视频文件（video shortcode）

视频文件有两种存放位置：

• 放在assets/media/媒体库（可跨页面复用）；
• 放在页面自身的文件夹（Hugo Page Bundle）内，例如content/blog/teach-courses/my_video.mp4。

然后使用videoshortcode 嵌入：

{{< video src="my_video.mp4" controls="yes" >}}

src指向视频文件名，controls="yes"显示播放控制条。将视频文件放在页面 Bundle 内，能保证页面自包含，便于整体迁移与版本管理。

三、嵌入播客 / 音乐：audio shortcode

把 MP3 文件放进页面文件夹或assets/media/媒体库，然后用audioshortcode 嵌入音频：

{{< audio src="ambient-piano.mp3" >}}

仓库中就有现成示例：content/blog/teach-courses/目录下存放了 ambient-piano.mp3，content/courses/hugo-blox/guide/formatting/下也有同名音频文件。这让读者（学生）可以直接在页面上试听，无需下载。

建议：播客 / 音乐文件体积通常较大，建议压缩后再放入仓库，并在 front matter 中通过cover、image配置配图，让页面更美观。

四、考学生：spoiler 折叠答案

用spoilershortcode 实现"点击查看答案"式的自测交互：

{{</* spoiler text="👉 Click to view the solution" */>}} You found me! {{</* /spoiler */>}}

渲染为一个可折叠的块，点击标题即可展开内容。配套文档 content/courses/hugo-blox/guide/formatting/toggle.md 明确说明：折叠内容内部支持 Markdown 渲染，因此答案里可以继续写代码块、列表甚至数学公式，例如：

{{</* spoiler text="Click to view the spoiler" */>}} This is the content of the details. Markdown is **supported**. ```python print("hello") ``` {{</* /spoiler */>}}

这让它非常适合做课堂小测、作业提示或"先思考再看答案"的练习设计。

五、LaTeX 数学公式：math 支持

HugoBlox Kit 支持$...$（行内）与$$...$$（块级）两种 LaTeX 数学写法，并提供了 Markdown 扩展。启用分两步：

5.1 启用数学渲染

• 单页启用：在页面 front matter 中设置math: true。本文原文档 content/blog/teach-courses/index.md 正是这样做的（front matter 首部即math: true）。
• 全站启用：在 config/_default/params.yaml 中打开：

features: math: enable: true

注意：以当前仓库实际配置为准——params.yaml 中对应开关位于hugoblox.content.math.enable（默认false，见 config/_default/params.yaml），全局启用时需将该值设为true。两种写法一脉相承，目的是让 Hugo 将$...$/$$...$$交给数学引擎而不是当作 Markdown 处理。

5.2 行内与块级公式

行内公式用单个美元符包裹：

$\nabla F(\mathbf{x}_{n})$

块级公式用双美元符包裹，例如原文档中的拟牛顿步长公式：

$$ \gamma_{n} = \frac{ \left | \left (\mathbf x_{n} - \mathbf x_{n-1} \right )^T \left [\nabla F (\mathbf x_{n}) - \nabla F (\mathbf x_{n-1}) \right ] \right |}{\left \|\nabla F(\mathbf{x}_{n}) - \nabla F(\mathbf{x}_{n-1}) \right \|^2} $$

5.3 多行公式（cases / 换行）

使用 LaTeX 行分隔符\\编写多行公式，例如分段函数：

$$ f(k;p_{0}^{*}) = \begin{cases}p_{0}^{*} & \text{if }k=1, \\ 1-p_{0}^{*} & \text{if }k=0.\end{cases} $$

5.4 兼容写法：math shortcode 包裹

配套课程文档 content/courses/hugo-blox/guide/formatting/media.md 给出了一种更稳妥的写法——用mathshortcode 包裹公式，防止 Hugo 把数学内容误渲染为 Markdown：

{{</* math */>}}$\nabla F(\mathbf{x}_{n})${{</* /math */>}}

{{</* math */>}} $$ \gamma_{n} = \frac{ \left | \left (\mathbf x_{n} - \mathbf x_{n-1} \right )^T \left [\nabla F (\mathbf x_{n}) - \nabla F (\mathbf x_{n-1}) \right ] \right |}{\left \|\nabla F(\mathbf{x}_{n}) - \nabla F(\mathbf{x}_{n-1}) \right \|^2} $$ {{</* /math */>}}

取舍建议：普通公式直接写$...$/$$...$$即可；当公式与 Markdown 语法（如下划线、星号）易冲突时，优先使用mathshortcode 包裹，保证渲染稳定。

六、代码高亮：Markdown 代码块

HugoBlox Kit 直接利用 Hugo 的 Markdown 代码高亮扩展。用带语言标识的围栏代码块即可：

```python import pandas as pd data = pd.read_csv("data.csv") data.head() ```

渲染后自动高亮。代码高亮主题在 config/_default/params.yaml 中配置（对应 Hugo 的markup.highlight设置，config/_default/hugo.yaml 中已显式声明markup: { _merge: deep, highlight: { lineNos: false } }，即默认不显示行号）。如需行号，可调整 highlight 配置。

实战提示：教学页中的示例代码建议与仓库 content/blog/data-visualization/ 的示范一致——先用 Pandas 读取results.csv之类的真实数据文件，再配合tableshortcode（{{< table path="results.csv" header="true" caption="..." >}}）在页面上直接渲染数据表，学生可边读代码边看结果。

七、行内图标：icon shortcode

在文字中插入图标，提升视觉层次：

{{</* icon name="python" */>}} Python

渲染为"Python"字样前带一个 Python 图标。icon的name取自主题内置的图标集（如技术品牌图标、Hero Icons 等）。类似的图标能力在 button shortcode 文档 中也有体现（icon、icon_position参数）。

八、将"授课页面"落地的完整步骤

结合 content/courses/hugo-blox/getting-started.md 与 package.json，一次典型的教学页面发布流程如下：

1. 建站：从 HugoBlox 模板（本仓库即 Academic CV 模板）创建新站点；
2. 配置：在 config/_default/params.yaml 中设置站点名称、描述、菜单；如需全站数学渲染，打开hugoblox.content.math.enable: true；
3. 写内容：在content/blog/（或content/courses/）下新建页面文件夹，写入带 front matter 的index.md，按上文各节插入 shortcode；
4. 本地预览：运行pnpm dev（即hugo server --disableFastRender），实时查看渲染效果；
5. 构建：运行pnpm build（hugo --minify && pnpm run pagefind），生成静态站点并建立站内搜索索引；
6. 发布：提交到 Git 仓库后，由部署平台（netlify.toml 或 hugoblox.yaml 中的deploy.host配置，如github-pages）自动构建上线。

小结

围绕 content/blog/teach-courses/index.md 这份范本，我们完整覆盖了教学页面的全部核心能力：cite引用文献、youtube/bilibili/video嵌入视频、audio嵌入播客、spoiler折叠答案、math渲染 LaTeX 公式（含行内 / 块级 / 多行 cases）、Markdown 代码高亮以及icon行内图标。每一类 shortcode 都可在纯 Markdown 中直接书写，渲染交由 HugoBlox Kit（模板依赖见 go.mod）完成。

对教师 / 研究者而言，这意味着你可以在不依赖任何视频平台、不写一行 HTML 的前提下，把课件、讲义、例题与自测练习组织成一个自包含、可离线构建、可长期维护的课程站点。下一步，建议你直接仿照本仓库 content/courses/hugo-blox/guide/formatting/ 下的 media、toggle、callout、button 等文档，为你的课程页面补充更丰富的交互组件。

• 前端