基础 Markdown 排版规范

标题层级

• 禁止使用一级标题 (#)：一级标题已由文章系统的 title 属性自动生成。

• 正文从二级标题 (##) 开始：根据内容逻辑，严禁跨层级使用标题（例如二级标题下直接接四级标题）。

• 空格要求：所有标题标记 # 与后面的文字之间必须保留一个空格。

段落与文本格式

• 中文排版：中文字符与英文单词、数字之间，建议保留一个半角空格（例如：“在 Hugo 中使用 Markdown”）。

• 段落换行：Markdown 段落之间需空一行。如果需要在段落内强制换行，请在行尾添加两个空格或使用 <br> 标签。

• 强调样式：

• 加粗：使用 文本，用于强调核心观点或专有名词。

• 斜体：使用 *文本*，中文排版中应减少斜体使用，通常仅用于英文专有名词或外来语。

列表与表格

• 无序/有序列表：列表标记与文字间须有一个空格。嵌套列表时，子列表需缩进 2 个或 4 个空格。

• 表格规范：表格前后需空一行，必须包含表头与分隔线。支持在表格内使用行内 Markdown 语法（如加粗、斜体、行内代码）。

代码块

• 必须指定语言：使用围栏式代码块（三个反引号）时，必须在开头明确标注语言（如 html, diff, python），以触发语法高亮。

• 行内代码：使用单反引号 code 包裹，用于提及命令、变量名、文件名等短文本。

行内 HTML 增强元素

当基础 Markdown 无法满足精细化排版时，可直接在正文中使用以下原生 HTML 标签：

• 按键提示：使用 <kbd>键名</kbd> 展示快捷键，如 CTRL + ALT。

• 文本高亮：使用 <mark>高亮文本</mark> 标记需要重点瞩目的词汇。

• 上下标：使用 <sub>下标</sub>（如 H2O）和 <sup>上标</sup>（如 Xn）。

• 首字母缩写：使用 <abbr title="完整解释">缩写</abbr> 提供悬停释义。

Hugo & Stack 主题特色语法

内置相册 (Image Gallery)

Stack 主题内置了对 Photoswipe 的支持，能够将多张图片自动根据宽高比拼合为精美的相册栅格。

• 语法规范：将多张图片写在同一行（或同一个段落内），并且图片之间必须保留两个半角空格。

• 示例代码：

1
2

![描述1](img1.jpg)  ![描述2](img2.jpg) 
![描述3](img3.jpg)  ![描述4](img4.jpg)

高级提示框 (Callouts / Alert Boxes)

通过在引用块（>）的首行使用特定标记，可以渲染出 5 种不同视觉样式的提示框：

• 注意 (Note)：突出显示快速浏览时需注意的信息。

1
2

> [!NOTE]
> 这是一个普通的注意信息。

• 提示 (Tip)：提供辅助完成任务的可选信息。

1
2

> [!TIP]
> 这是一个实用的操作小技巧。

• 重要 (Important)：用户成功所必需的关键信息。

1
2

> [!IMPORTANT]
> 核心步骤，请务必仔细确认。

• 警告 (Warning)：由于潜在风险而需要立即关注的关键内容。

1
2

> [!WARNING]
> 此操作可能会覆盖现有配置。

• 危险 (Caution)：某个操作可能带来的负面严重后果。

1
2

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

💡 进阶自定义：可以在方括号后面直接添加自定义标题，例如：> [!NOTE] 自定义标题文本。

数学公式 (KaTeX)

当文章的 Frontmatter 中开启了 math: true 时，可以使用 KaTeX 语法渲染高质量的数学公式。

• 行内公式：使用单个美元符号包裹，例如 $ \varphi = \dfrac{1+\sqrt5}{2} $。

• 块级公式：使用双美元符号包裹独立成行，例如 $$ f(a) = \frac{1}{2\pi i} \oint_\gamma \frac{f(z)}{z-a} dz $$。

Mermaid 文本图表

使用 ```mermaid 语言标识符可以直接通过代码渲染图表，图表会自动适配网站的明暗主题模式。

• 全局主题切换：支持流程图、时序图、类图、状态图、E-R图、甘特图、饼图、思维导图等。

• 局部主题覆盖：可通过图表顶部的 %%{init: {'theme': 'forest'}}%% 强制指定局部主题。

• 安全性警告：若要在节点内使用 HTML 标签（如换行符 <br/> 或加粗 <b>），需确保网站全局配置中 securityLevel 设为 loose。

自定义短代码 (Shortcodes) 规范

短代码是 Hugo 扩展 Markdown 的核心功能，主题提供了以下内置组件，请严格按照参数要求使用：

结构化引用 (quote)

相比于普通引用，quote 短代码可以优雅地渲染出作者、文献来源以及跳转链接。

• 语法：

1
2
3

{{< quote author="作者名称" source="文献或网站来源" url="URL链接" >}}
这里填写具体的引用文本内容。
{{< /quote >}}

多媒体嵌入

为了统一多媒体的自适应宽高比与暗色模式边框，请使用对应的专用短代码，严禁直接复制平台提供的 <iframe> 嵌入码：

• 自托管视频：{{< video src="视频的绝对或相对URL" >}}

• 哔哩哔哩 (Bilibili)：{{< bilibili "BV号或AV号" >}}

• YouTube：{{< youtube "视频唯一ID" >}}

• 腾讯视频：{{< tencent "视频唯一ID" >}}

站内跳转与资源引用规范

站内文章安全跳转

为了避免网站后期结构调整或 Slug 改变导致死链，必须使用 Hugo 的动态解析短代码。

• 标准写法：

1

请参考我们的 [Frontmatter指南]({{< ref "post/frontmatter-guide/index.zh.md" >}})。

注意：括号内必须提供相对于 content/ 目录的完整文件路径。

文章内资产引用 (Page Bundles)

所有的文章图片、附件必须存放在与文章 index.md 相同的文件夹下。

• 图片引用语法：

1

![图片描述](screenshot.png)

严禁使用电脑本地的绝对路径（如 D:/images/...）或者未托管的第三方外部图床链接。