这是一份语法自检页：把 Markdown（Hugo Goldmark + LoveIt 扩展）和主题的扩展能力逐项列出来，用来确认「源码怎么写 → 页面上长什么样」。

一、标题层级 H1–H6

下面六级标题是真实渲染，同时会按层级出现在右侧目录里（H1 会进目录，因为本页 startLevel 从 2 起算，H1 反而不进）。

H1 一级标题

H2 二级标题

H3 三级标题

H4 四级标题

H5 五级标题

H6 六级标题

说明：正文里用 # 写 H1 是可以的，但通常留空，因为页面标题本身已经是 H1。中文标题的锚点 id 会保留中文，例如本节是 #一标题层级-h1h6。

二、段落、换行与分隔线

这是一个普通段落。段落内的单个换行不会产生 <br>，只会在源码里换行，渲染后仍是一行。

这一行和第二行之间只有一个换行。

这一行结尾有两个空格（硬换行），
所以这里会真正断行。

这一行结尾用反斜杠，
也会断行。

也可以用 <br> 强制换行：第一段
第二段。

下面是三个连字符构成的分隔线：

下面是 <hr> 标签：

三、文字样式

未启用的扩展写法（Goldmark 默认不带，写出来就是原样文本）：==高亮== 显示为 ==高亮==，H~2~O 显示为 H~2~O。

四、链接

行内链接：Hugo 官网。

带 title 的链接：LoveIt 主题，鼠标悬停能看到提示。

引用式链接：Goldenmark 文档，定义写在文末。

自动链接（尖括号）：https://gohugo.io/。

裸链接（linkify 开启，会自动变成链接）：https://gohugo.io/

站内链接（相对路径，会走主题的 render-link 钩子）：返回工具列表。

页内锚点：跳到第九节表格。

邮件链接：mailto:someone@example.com。

主题行为：外链会自动加 target="_blank" 和外链图标；站内链接不加。上面前两个链接应该能看到右上角的小箭头。

五、图片

图片统一用站内绝对路径引用（/images/post/20171220/文件名）。

5.1 基本图片（无标题）

5.2 带标题的图片（会变成 figure + figcaption）

注意：Markdown 的图片「标题」在 LoveIt 里不是 title 提示，而是图注。写法是 ![alt](src "图注")。

5.3 矢量图 SVG

踩坑记录（重要）：本文最初是 page bundle 结构（20171220/index.md + 同目录图片），SVG 放在文章目录里会让构建直接失败。LoveIt 的 plugin/img.html 会对页面资源调用 .Width，而 Hugo 的 .Width 只支持位图：

error calling Width: this method is only available for raster images

现在统一改成 static/images/post/20171220/ + 绝对路径，模板查不到页面资源、不会去取宽高，SVG 自然没问题，也和仓库里其它文章的图片组织方式一致了。

5.4 透明通道 PNG

5.5 棋盘格（检查缩放与边框）

5.6 图片 shortcode（可指定宽高与说明）

关于外链图片：博客页只下发了 COOP、没有 COEP，所以技术上可以贴外链图；但本文 2017 年的旧版就是反例——5 张图全在 zybuluo.com 上，图床一下线就只剩破图图标。图片统一放 static/images/post/<id>/，它会跟仓库一起备份、一起发布。

六、列表

6.1 无序列表

• 第一项
• 第二项
  • 嵌套一项
  • 嵌套二项
    • 三级嵌套
• 第三项

6.2 有序列表

1. 第一步
2. 第二步
3. 第三步

6.3 有序列表指定起始序号

3. 从 3 开始
4. 然后是 4
5. 然后是 5

6.4 混合嵌套

1. 顶层有序
   • 里面无序
   • 还是无序
     1. 再套有序
     2. 再套有序
2. 回到顶层

6.5 任务列表

• 已完成的事项
• 另一个已完成
• 未完成的事项
  • 子任务已完成
  • 子任务未完成

6.6 定义列表

Goldmark

一个用 Go 写的 Markdown 解析器，Hugo 从 0.60 起默认使用它。

LoveIt

当前站点使用的 Hugo 主题。

支持 admonition、mermaid、echarts 等扩展。

6.7 列表里放代码和引用

1. 第一步，执行命令：

   1	hugo --environment gitee

2. 第二步，看输出：

   注意退出码，别只看最后一行日志。

七、引用

单层引用：

这是一段引用。引用里可以放加粗、行内代码 和链接。

嵌套引用：

第一层

第二层

第三层

引用里放列表和代码：

引用中的列表：

• 项目 A
• 项目 B

引用中的代码：

1	console.log('blockquote + code');

八、代码

8.1 行内代码

用 npm install 安装依赖，配置文件在 config/_default/config.toml。

8.2 围栏代码块（带语言高亮）

1
2
3
4
5

public class Hello {
    public static void main(String[] args) {
        System.out.println("Hello, Markdown");
    }
}

1
2

const add = (a, b) => a + b;
console.log(add(1, 2)); // 3

1
2
3
4
5

def fib(n: int) -> int:
    a, b = 0, 1
    for _ in range(n):
        a, b = b, a + b
    return a

1
2
3
4
5
6
7

package main

import "fmt"

func main() {
    fmt.Println("Hello, Go")
}

1
2

gzip -9 -n -k static/tools/ocr/vendor/ppocr/guten-ocr.js
curl -sI https://100180.xyz/tools/ocr/ | grep -i content-type

1
2
3
4
5

SELECT id, title, created_at
FROM posts
WHERE status = 'published'
ORDER BY created_at DESC
LIMIT 10;

1
2
3
4
5
6

markup:
  goldmark:
    renderer:
      unsafe: true
  highlight:
    lineNos: true

1
2
3
4
5

{
  "name": "20171220",
  "enable": true,
  "count": 3
}

1
2
3

<div class="admonition note">
  <p>raw HTML block</p>
</div>

1
2
3

.admonition.note {
  border-left: 4px solid #448aff;
}

1
2

- lineNumbersInTable = false
+ lineNumbersInTable = true

8.3 指定高亮行

写法是在语言后面加参数：{hl_lines=[2,"5-6"]}。

1
2
3
4
5
6
7
8

public class Highlight {
    private static final String MARK = "第 2 行高亮";
    public static void main(String[] args) {
        // 第 4 行普通
        System.out.println("第 5 行");
        System.out.println("第 6 行");
    }
}

8.4 关闭行号

echo "这一块没有行号"
echo "适合单行命令"

8.5 无语言围栏

1
2

纯文本块，不套语法高亮。
第二行。

8.6 超长代码的折叠效果

params.page.code.maxShownLines = 50，所以下面这块会被折叠，需要点展开。

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55

# 共 55 行，超过 maxShownLines=50，应当折叠
echo "第 01 行 · 用来验证折叠阈值"
echo "第 02 行 · 用来验证折叠阈值"
echo "第 03 行 · 用来验证折叠阈值"
echo "第 04 行 · 用来验证折叠阈值"
echo "第 05 行 · 用来验证折叠阈值"
echo "第 06 行 · 用来验证折叠阈值"
echo "第 07 行 · 用来验证折叠阈值"
echo "第 08 行 · 用来验证折叠阈值"
echo "第 09 行 · 用来验证折叠阈值"
echo "第 10 行 · 用来验证折叠阈值"
echo "第 11 行 · 用来验证折叠阈值"
echo "第 12 行 · 用来验证折叠阈值"
echo "第 13 行 · 用来验证折叠阈值"
echo "第 14 行 · 用来验证折叠阈值"
echo "第 15 行 · 用来验证折叠阈值"
echo "第 16 行 · 用来验证折叠阈值"
echo "第 17 行 · 用来验证折叠阈值"
echo "第 18 行 · 用来验证折叠阈值"
echo "第 19 行 · 用来验证折叠阈值"
echo "第 20 行 · 用来验证折叠阈值"
echo "第 21 行 · 用来验证折叠阈值"
echo "第 22 行 · 用来验证折叠阈值"
echo "第 23 行 · 用来验证折叠阈值"
echo "第 24 行 · 用来验证折叠阈值"
echo "第 25 行 · 用来验证折叠阈值"
echo "第 26 行 · 用来验证折叠阈值"
echo "第 27 行 · 用来验证折叠阈值"
echo "第 28 行 · 用来验证折叠阈值"
echo "第 29 行 · 用来验证折叠阈值"
echo "第 30 行 · 用来验证折叠阈值"
echo "第 31 行 · 用来验证折叠阈值"
echo "第 32 行 · 用来验证折叠阈值"
echo "第 33 行 · 用来验证折叠阈值"
echo "第 34 行 · 用来验证折叠阈值"
echo "第 35 行 · 用来验证折叠阈值"
echo "第 36 行 · 用来验证折叠阈值"
echo "第 37 行 · 用来验证折叠阈值"
echo "第 38 行 · 用来验证折叠阈值"
echo "第 39 行 · 用来验证折叠阈值"
echo "第 40 行 · 用来验证折叠阈值"
echo "第 41 行 · 用来验证折叠阈值"
echo "第 42 行 · 用来验证折叠阈值"
echo "第 43 行 · 用来验证折叠阈值"
echo "第 44 行 · 用来验证折叠阈值"
echo "第 45 行 · 用来验证折叠阈值"
echo "第 46 行 · 用来验证折叠阈值"
echo "第 47 行 · 用来验证折叠阈值"
echo "第 48 行 · 用来验证折叠阈值"
echo "第 49 行 · 用来验证折叠阈值"
echo "第 50 行 · 用来验证折叠阈值"
echo "第 51 行 · 用来验证折叠阈值"
echo "第 52 行 · 用来验证折叠阈值"
echo "第 53 行 · 用来验证折叠阈值"
echo "第 54 行 · 用来验证折叠阈值"

九、表格

9.1 基本表格与对齐

9.2 宽表格（检查是否横向滚动）

十、脚注

Hugo 的 footnote 扩展已开启，写法是 [^1]，定义放在文末¹。同一个脚注可以被多次引用²，也可以指向更长的说明³。

这也是检查脚注回链（↩）是否正常的好机会¹。

十一、原生 HTML 块

unsafe = true，所以可以直接写 HTML。

带内联样式的段落（不推荐在正文大量使用，但确实生效）。

十二、admonition（12 种类型）

十三、其他 shortcode

13.1 mermaid 流程图

13.2 echarts 图表

13.3 typeit 打字机

13.4 link 与 version

LoveIt 版本徽章：，以及旧版本样式：

13.5 style 自定义样式

这段文字用原生 HTML 的 style 属性上色。

重要（这个坑会让整站构建失败）：主题自带的 {{< style "color:#e83e8c;" >}}...{{< /style >}} 在本仓库用不了。 它会把样式塞进 styleArr，再交给 assets.html 用 ToCSS 编译成临时 .scss，而 hugo_bin/hugo 是非 extended 版，只能报错：

TOCSS: failed to transform "/css/xxxxxx.scss": you need the extended version to build SCSS/SASS

所以正文里的自定义样式一律用原生 <span style="..."> / <div style="...">，不要用 style shortcode。

13.6 需要外部服务、本页未实际启用的（用法示例）

下面这些不是坏了，而是需要额外条件（B 站视频 id、Mapbox token、音乐服务器、外部头像），所以只列写法，不实际渲染。

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11

{{< bilibili BV1V4411J7N1 >}}

{{< mapbox lng="-122.40" lat="37.80" zoom="12" >}}

{{< music url="https://music.163.com/#/song?id=xxx" >}}

{{< person url="https://github.com/user" name="名字" text="一句话介绍" avatar="avatar.png" >}}

{{< raw >}}<div>原样输出，不走 Markdown 渲染</div>{{< /raw >}}

{{< script >}}console.log('页面加载后执行');{{< /script >}}

十四、数学公式（本页已启用）

这一页的 front matter 写了 math: true，所以本节的公式会由 KaTeX 真的排版出来。

14.1 行内公式

写法是 $...$：质能方程 $E = mc^2$，勾股定理 $a^2 + b^2 = c^2$，欧拉恒等式 $e^{i\pi} + 1 = 0$。

14.2 块级公式

$$ 单独占一行，中间可以随便换行：

14.3 多行对齐

aligned 环境里用 & 对齐、\\ 换行：

14.4 矩阵与行列式

14.5 求和、极限、希腊字母

14.6 化学式（mhchem 插件）

站点配置里 mhchem = true，所以 \ce{} 也能用：

14.7 复制公式

配置里 copyTex = true，鼠标划选公式后复制，剪贴板里拿到的是 LaTeX 源码而不是乱码字符。

14.8 启用方式与代价（重要）

这里和主题默认行为不一样，值得记一笔：

1. 主题原生只支持「全站开 + 单页关」。assets.html 里是 if eq $math true → 用 .Site.Params.page.math，也就是 front matter 写 math: true 只是「去读站点配置」，而站点配置 enable = false 时永远不加载。
2. 本站改成了「单页开」。项目里的 layouts/partials/assets.html 覆盖了主题同名文件，把上面那行改成：math: true 时强制 enable = true。站点配置继续保持 enable = false，所以只有本页会加载 KaTeX。
3. 代价：本页多出 KaTeX 的 CSS（23 KB）+ JS（273 KB）+ auto-render（3 KB）+ mhchem（34 KB），gzip 后约 100 KB 出头，其余页面不受影响。以后写新文章要用公式，front matter 加一行 math: true 就行。
4. Goldmark passthrough 已开启（markup.goldmark.extensions.passthrough），$...$ / $$...$$ / \(...\) / \[...\] 之间的内容会原样透传给 KaTeX，不再被 Markdown 解析。所以公式里的 _、*、\\ 都不用转义——这是最容易踩的坑：没有 passthrough 时，a_1 + a_2 里的下划线会被当成强调语法吃掉。

金额写法提醒：正文里成对出现的 $ 会被当成行内公式（比如「$5 到 $10」如果不用反斜杠转义，中间的文字会被当公式）。写金额时用 \$ 转义，或者放进反引号里。

十五、转义与特殊字符

转义星号：*这不是斜体*，转义反引号：`不是代码`，转义下划线：_不是斜体_。

HTML 实体：& → &，< → <，© → ©，  会产生一个不换行空格。

中文标点与 typographer（连写两个连字符、三个点和直引号会被转换）："–" 变成 –；"…" 变成 …；“引号” 会变成弯引号（具体看字体）。

Emoji（twemoji = false，所以直接用系统 emoji 字体）：🙂 🚀 ✅ ❌ 📄

十六、目录、锚点与源码链接

• 右侧目录：由 ## 到 ###### 生成，tocFolding: true 时可以折叠。本节标题就出现在里面。
• 锚点：点目录项跳到标题，URL 会带上 #xxx。中文标题的 id 保留中文，空格转成连字符，英文会转小写。
• 查看源码：linkToMarkdown = true，页面底部（或标题下方）会有「查看 Markdown 源码」的入口，指向本文件渲染出的 .md。
• 上一篇 / 下一篇：文章底部按日期自动生成。

十七、自检清单

对照下表逐项确认，哪一项不对就说明对应配置或主题行为有变化。