内容组件 | 宏创网络

嵌入多媒体

Tue, 24 Oct 2023 00:00:00 +0000

面向技术内容创作者设计。你只需专注内容，底层的 Hugo Blox 会处理好其余部分。

可嵌入视频、播客、代码、LaTeX 公式，甚至用于自测的题目！

本页展示了可用的技术内容渲染示例。

视频

可以通过以下几种方式分享视频：

YouTube：

{{< youtube w7Ft2ymGmfc >}}

哔哩哔哩（Bilibili）：

{{< bilibili id="BV1WV4y1r7DF" >}}

本地视频文件

视频可放在 assets/media/ 媒体库，或放在中，然后用 video shortcode 嵌入：

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

播客 / 音频

把 MP3 文件放在页面文件夹或媒体库目录，然后用 audio shortcode 嵌入：

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

试试看：

自测题目

用 spoiler shortcode 折叠答案，实现简单有趣的自测：

{{< spoiler text="👉 点击查看答案" >}}
找到我啦！
{{< /spoiler >}}

渲染效果：

👉 点击查看答案

找到我啦 🎉

数学公式

支持 $\LaTeX$ 数学公式。可在 config/_default/params.yaml 中打开 math 选项。

行内或块级公式，分别用 {{< math >}}$...${{< /math >}} 或 {{< math >}}$$...$${{< /math >}} 包裹。

Note

我们用 math shortcode 包裹 LaTeX，防止 Hugo 把公式当成 Markdown 渲染。该提示框使用的是标准 Markdown 提示框语法！

块级公式示例：

{{< 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 >}}

渲染效果：

$$\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 >}}$\nabla F(\mathbf{x}_{n})${{< /math >}} 渲染为 $\nabla F(\mathbf{x}_{n})$ 。

多行公式（使用 \\ 换行）：

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

渲染效果：

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

代码

使用 Hugo 的 Markdown 语法高亮扩展，代码主题可在 config/_default/params.yaml 中选择。

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

渲染效果：

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

行内图标

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

渲染为

Python

觉得本页有帮助？欢迎分享 🙌

卡片

Mon, 01 Jan 0001 00:00:00 +0000

用于创建卡片的 Hugo 扩展。卡片可以是链接，也可以是纯文本。

用法

学习 Shortcode 一个没有图标和链接的卡片

渲染自：

{{< cards >}}
 {{< card url="../callout" title="提示框" icon="academic-cap" >}}
 {{< card url="" title="没有图标的卡片" >}}
{{< /cards >}}

选项

参数	说明
`icon`	图标名称。默认使用
`title`	卡片标题
`subtitle`	副标题（支持 Markdown）
`url`	链接地址

折叠面板

Mon, 01 Jan 0001 00:00:00 +0000

用于切换显示/隐藏可折叠内容的 Hugo shortcode。

示例

点击查看折叠内容

找到我啦！

支持 Markdown。

用法

{{< spoiler text="点击查看折叠内容" >}}

这里是折叠的内容。

支持 **Markdown**。

{{< /spoiler >}}

按钮

Mon, 01 Jan 0001 00:00:00 +0000

一个现代化、可自定义的按钮组件（shortcode）：支持渐变样式、图标与智能链接处理。

基本用法

联系我们

访问外部网站

上面按钮的写法：

{{< button url="/contact" >}}联系我们{{< /button >}}

{{< button url="https://example.com" new_tab="true" style="secondary" >}}访问外部网站{{< /button >}}

样式变体

主要（默认）

主要按钮

{{< button url="#" style="primary" >}}主要按钮{{< /button >}}

次要

次要按钮

{{< button url="#" style="secondary" >}}次要按钮{{< /button >}}

描边

描边按钮

{{< button url="#" style="outline" >}}描边按钮{{< /button >}}

幽灵

幽灵按钮

{{< button url="#" style="ghost" >}}幽灵按钮{{< /button >}}

尺寸

{{< button url="#" size="sm" >}}小按钮{{< /button >}}
{{< button url="#" size="md" >}}中按钮{{< /button >}}
{{< button url="#" size="lg" >}}大按钮{{< /button >}}
{{< button url="#" size="xl" >}}超大按钮{{< /button >}}

对齐

左（默认）

左对齐

居中

居中对齐

右

右对齐

{{< button url="#" align="left" >}}左对齐{{< /button >}}
{{< button url="#" align="center" >}}居中对齐{{< /button >}}
{{< button url="#" align="right" >}}右对齐{{< /button >}}

带图标

图标在文字前

下载

图标在文字后

继续

{{< button url="#" icon="arrow-down-tray" >}}下载{{< /button >}}
{{< button url="#" icon="arrow-right" icon_position="right" >}}继续{{< /button >}}

圆角

小圆角

中圆角（默认）

中圆角

大圆角

胶囊形

胶囊按钮

{{< button url="#" rounded="sm" >}}小圆角{{< /button >}}
{{< button url="#" rounded="md" >}}中圆角{{< /button >}}
{{< button url="#" rounded="lg" >}}大圆角{{< /button >}}
{{< button url="#" rounded="full" >}}胶囊按钮{{< /button >}}

进阶示例

行动号召按钮

立即开始

{{< button url="/signup" style="primary" size="lg" align="center" icon="rocket-launch" >}}立即开始{{< /button >}}

新标签打开外链

在 GitHub 查看

{{< button url="https://github.com/hugo-blox/kit" new_tab="true" style="outline" icon="arrow-top-right-on-square" icon_position="right" >}}在 GitHub 查看{{< /button >}}

下载按钮

下载 PDF

{{< button url="/files/document.pdf" style="secondary" icon="document-arrow-down" rounded="full" >}}下载 PDF{{< /button >}}

参数

参数	类型	默认值	说明
`url`	string	`#`	必填。按钮链接地址（站内或站外）
`text`	string	内部内容	按钮文字（会覆盖 shortcode 内部内容）
`new_tab`	boolean	`false`	是否在新标签页打开
`style`	string	`primary`	按钮样式：`primary`、`secondary`、`outline`、`ghost`
`size`	string	`md`	按钮尺寸：`sm`、`md`、`lg`、`xl`
`align`	string	`left`	对齐方式：`left`、`center`、`right`
`icon`	string	-	图标名（来自）
`icon_position`	string	`left`	图标位置：`left`、`right`
`rounded`	string	`md`	圆角：`sm`、`md`、`lg`、`xl`、`full`
`disabled`	boolean	`false`	是否禁用按钮

安全特性

按钮组件会自动处理外链安全：

外部链接会加上 rel="noreferrer"
新标签打开的外部链接会加上 rel="noopener noreferrer"
新标签打开的站内链接会加上 rel="noopener"

无障碍

按钮组件内置无障碍支持：

正确的 role="button" 属性
支持 aria-label
键盘聚焦指示
高对比度聚焦环
禁用状态处理

提示框

Mon, 01 Jan 0001 00:00:00 +0000

本站支持 GitHub 与 Obsidian 风格的 Markdown 提示框（callout），兼容性与可移植性都很好。

提示框适合用来突出重要的、相关的信息，例如说明、提示或警告。

用法

基础类型

支持 Obsidian 的：

信息与备注：

> [!NOTE]
> 这是一条备注，用于提示用户应知的重要信息。

Note

这是一条备注，用于提示用户应知的重要信息。

> [!INFO]
> 另一种信息提示框——样式与 NOTE 相同。

Info

另一种信息提示框——样式与 NOTE 相同。

> [!ABSTRACT]
> 用于摘要、总结或 TL;DR 内容。

Abstract

用于摘要、总结或 TL;DR 内容。

行动与任务：

> [!TODO]
> 这是待办事项。

Todo

这是待办事项。

> [!TIP]
> 一条能提升效率的小技巧！

Tip

一条能提升效率的小技巧！

> [!SUCCESS]
> 操作已成功完成。

Success

操作已成功完成。

提问与示例：

> [!QUESTION]
> 你怎么看这个方案？欢迎留言。

Question

你怎么看这个方案？欢迎留言。

> [!EXAMPLE]
> 这里给出该功能的一个实际示例。

Example

这里给出该功能的一个实际示例。

> [!QUOTE]
> “预测未来最好的方式就是创造未来。”——Alan Kay

Quote

“预测未来最好的方式就是创造未来。”——Alan Kay

警告与错误：

> [!WARNING]
> 注意！此操作可能带来意外后果。

Warning

注意！此操作可能带来意外后果。

> [!CAUTION]
> 危险！此操作不可逆，可能导致数据丢失。

Caution

危险！此操作不可逆，可能导致数据丢失。

> [!IMPORTANT]
> 这是用户必须了解才能继续的关键信息。

Important

这是用户必须了解才能继续的关键信息。

> [!DANGER]
> 极其危险——请务必小心！

Danger

极其危险——请务必小心！

> [!FAILURE]
> 操作失败。请检查配置后重试。

Failure

操作失败。请检查配置后重试。

> [!BUG]
> 已知问题：该功能在 Safari < 14 中不起作用。

Bug

已知问题：该功能在 Safari < 14 中不起作用。

自定义标题

可以为任意提示框自定义标题：

> [!WARNING]+ 自定义警告标题
> 这条警告使用了自定义标题，而不是默认的“Warning”。

自定义警告标题

这条警告使用了自定义标题，而不是默认的“Warning”。

旧语法（已弃用）

旧的 shortcode 语法仍可用，但会显示弃用警告：

{{< callout note >}}
仍然可用，但已弃用。请使用上面的 Markdown 语法！
{{< /callout >}}

CSS 自定义

提示框带有语义化 CSS 类与 data 属性，便于自定义。每个提示框包含：

基础类：.callout
类型属性：data-callout="note"
组件类：.callout-icon、.callout-title、.callout-content、.callout-body

自定义 CSS 示例（添加到 assets/css/custom.css）：

/* 自定义 NOTE 提示框 */
.callout[data-callout="note"] {
 border-left-width: 8px;
 box-shadow: 0 4px 6px -1px rgb(0 0 0 / 0.1);
}

/* 让 SUCCESS 提示框脉冲 */
.callout[data-callout="success"] {
 animation: pulse 2s infinite;
}

/* 自定义图标样式 */
.callout-icon svg {
 transition: transform 0.2s;
}

.callout:hover .callout-icon svg {
 transform: scale(1.1);
}

/* 深色模式覆盖 */
@media (prefers-color-scheme: dark) {
 .callout[data-callout="warning"] {
 background-color: rgb(92 25 2);
 border-color: rgb(245 158 11);
 }
}

新语法的优点

可移植：兼容 GitHub、Obsidian 等 Markdown 编辑器
标准：使用广泛采用的 Markdown 提示框语法
简洁：无需 Hugo 专有 shortcode
面向未来：受最新 Hugo 版本支持（0.132.0+）
可定制：语义化 CSS 类与 data 属性，便于设置样式
完整：支持全部 15+ 种 Obsidian 提示框类型
多语言：提示框标题会根据站点语言自动翻译（也可在语言包中自定义）

步骤

Mon, 01 Jan 0001 00:00:00 +0000

用于展示一系列步骤，例如教程中的操作流程。

示例

第一步

这里是第一步……

第二步

这里是第二步……

第三步

这里是第三步……

用法

在 steps shortcode 内部使用三级标题（###）表示每一步的标题：

{{% steps %}}

### 第一步

这里是第一步……

### 第二步

这里是第二步……

### 第三步

这里是第三步……

{{% /steps %}}

内容组件 | 宏创网络

嵌入多媒体

视频

播客 / 音频

自测题目

数学公式

代码

行内图标

觉得本页有帮助？欢迎分享 🙌

卡片

用法

选项

折叠面板

示例

用法

按钮

基本用法

样式变体

主要（默认）

次要

描边

幽灵

尺寸

小

中（默认）

大

超大

对齐

左（默认）

居中

右

带图标

图标在文字前

图标在文字后

圆角

小圆角

中圆角（默认）

大圆角

胶囊形

进阶示例

行动号召按钮

新标签打开外链

下载按钮

参数

安全特性

无障碍

提示框

用法

基础类型

自定义标题

旧语法（已弃用）

CSS 自定义

新语法的优点

步骤

示例

第一步

第二步

第三步

用法