Markdown 语法与 Hugo Shortcodes 参考

Wed, 26 Aug 2026 00:00:00 +0000

自己写博客时常用的 Markdown 语法、emoji、数学公式和这个主题（hugo-theme-stack）自带的 shortcodes，合并成一篇方便随时查。

标题

<h1>—<h6> 对应一到六级标题：

# H1
## H2
### H3
#### H4
##### H5
###### H6

段落与换行

普通段落直接空一行分隔即可；行内换行用两个空格或 <br> 结尾。

引用（Blockquote）

不带署名：

> **Note** that you can use *Markdown syntax* within a blockquote.

Note that you can use Markdown syntax within a blockquote.

带署名（脚注语法）：

> Don't communicate by sharing memory, share memory by communicating.<br>
> — <cite>Rob Pike[^1]</cite>

[^1]: 出自 Rob Pike 在 Gopherfest 2015 的演讲。

Don’t communicate by sharing memory, share memory by communicating.
— Rob Pike¹

表格

Hugo 原生支持表格（非 CommonMark 核心语法）：

   Name | Age
--------|------
    Bob | 27
  Alice | 23

Name	Age
Bob	27
Alice	23

单元格内可以用行内语法：

Italics	Bold	Code
italics	bold	`code`

代码块

反引号 + 语言标识：

```html
<p>Test</p>
```

Hugo 内置高亮 shortcode（等价于反引号代码块，但走的是 Hugo 自己的高亮渲染）：

{{< highlight html >}}
<p>Test</p>
{{< /highlight >}}

diff 代码块：

```diff
[dependencies.bevy]
- features = ["dynamic"]
+ features = ["jpeg", "dynamic"]
```

列表

有序列表：

1. First item
2. Second item
3. Third item

无序列表 + 嵌套：

* Fruit
  * Apple
  * Orange
* Dairy
  * Milk
  * Cheese

行内元素 — abbr / sub / sup / kbd / mark

<abbr title="Graphics Interchange Format">GIF</abbr>
H<sub>2</sub>O
X<sup>n</sup> + Y<sup>n</sup> = Z<sup>n</sup>
Press <kbd>CTRL</kbd> + <kbd>ALT</kbd> + <kbd>Delete</kbd> to end the session.
Most <mark>salamanders</mark> are nocturnal.

GIF is a bitmap image format.

H₂O

Xⁿ + Yⁿ = Zⁿ

Press CTRL + ALT + Delete to end the session.

Most salamanders are nocturnal, and hunt for insects, worms, and other small creatures.

图片链接

[![Google](https://www.google.com/images/branding/googlelogo/1x/googlelogo_light_color_272x92dp.png)](https://google.com)

Emoji

在 hugo.yaml 里把 enableEmoji 设为 true 后，可以在正文里直接用 shorthand code：

🙈 :see_no_evil: 🙉 :hear_no_evil: 🙊 :speak_no_evil:

完整 shorthand code 表见 Emoji cheat sheet。渲染出来是 Unicode 字符，具体长什么样取决于浏览器/系统自带的 emoji 字体，想统一样式可以自己指定字体栈：

.emoji {
  font-family: Apple Color Emoji, Segoe UI Emoji, NotoColorEmoji, Segoe UI Symbol, Android Emoji, EmojiSymbols;
}

数学公式（KaTeX）

在文章 front matter 里加 math: true（或在 hugo.yaml 里全局开启），主题会加载 KaTeX 渲染公式。

行内公式： $\varphi = \dfrac{1+\sqrt5}{2}= 1.6180339887…$

块级公式：

$$
 \varphi = 1+\frac{1} {1+\frac{1} {1+\frac{1} {1+\cdots} } }
$$

支持的 TeX 函数列表见 Supported TeX Functions。

hugo-theme-stack 内置 Shortcodes

YouTube（隐私增强版）：

{{< youtube ZJthWmvUzzc >}}

X（Twitter）：

{{< x user="DesignReviewed" id="1085870671291310081" >}}

Vimeo：

{{< vimeo_simple 48912912 >}}

bilibili：

{{< bilibili av498363026 >}}

GitHub Gist（主题自带的 gist shortcode 已弃用，改用手动链接）：

[View GitHub Gist](https://gist.github.com/spf13/7896402)

GitLab Snippet：

{{< gitlab 2349278 >}}

引用块 shortcode（quote，比普通 blockquote 多了作者/来源）：

{{< quote author="A famous person" source="The book they wrote" url="https://en.wikipedia.org/wiki/Book" >}}
正文内容
{{< /quote >}}

这是一段示例引用文字，用来展示 quote shortcode 的实际渲染效果。
― A famous person, The book they wrote

出自 Rob Pike 在 Gopherfest 2015 的演讲。 ↩︎

Hugo on yanceyのBlog