一、合并必要的配置
单独拆成 config/_default/markup.toml，用 _merge="deep" 合并，不和菜单混在同一个文件，结构干净。
1
2
3
| # config/_default/markup.toml
[markup]
_merge = "deep"
|
二、完整代码
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
| # config/_default/markup.toml
[markup]
_merge = "deep"
defaultMarkdownHandler = "goldmark"
# ========== 代码高亮 ==========
[markup.highlight]
codeFences = true
noClasses = false
anchorLineNos = false
guessSyntax = true
lineNos = true
lineNumbersInTable = true
# ========== Goldmark Markdown 解析核心配置 ==========
[markup.goldmark]
# 允许原始HTML（FixIt很多卡片、提示块、图标依赖这个）
unsafe = true
[markup.goldmark.extensions]
definitionList = true # 定义列表
footnote = true # 脚注 ^[xxx]
linkify = true # 自动把纯文本网址转成超链接
strikethrough = true # 删除线 ~~文字~~
table = true # Markdown表格
taskList = true # 任务清单 - [ ] 任务
typographer = true # 智能标点：直引号变弯引号、短横线/长横线自动转换
linkifyProtocol = 'https'
[markup.goldmark.parser]
autoIdentifiers = true # 标题自动生成id（目录、锚点跳转依赖）
# 开启 markdown 属性语法 {#id .class}，给块元素加class/id，FixIt提示块有用
[markup.goldmark.parser.attribute]
block = true
title = true
[markup.goldmark.renderer]
hardWraps = false # false：换行需要两个空格；true：回车直接换行（类似语雀/Notion）
unsafe = true # 配合外层，允许渲染HTML
xhtml = false
# ========== 目录 TOC 配置（FixIt 侧边/文章目录） ==========
[markup.tableOfContents]
startLevel = 2
endLevel = 4
ordered = false
|
三、逐段重点解释
1. unsafe = true（两个地方都有）
⚠️ FixIt 必开！ 开启之后 Markdown 里面可以直接写原生 HTML，FixIt 的提示块、badge、内嵌图标、折叠块这些扩展语法全都依赖它。 如果改成 false，文章里的 HTML 会原样输出，不会渲染。
2. extensions 扩展对照表
表格
| 参数 | 语法示例 | 作用 |
|---|
| definitionList | 名词: 解释 | 定义列表 |
| footnote | 注释^[这是脚注内容] | 文末自动生成脚注 |
| linkify | shturl.cc/FGy3y | 纯网址自动变成可点击链接 |
| strikethrough | ~~删除文字~~ | 删除线 |
| table | ` | 表头 |
| taskList | - [ ] 待办 | 复选任务列表 |
| typographer | << >> -- --- | 智能美化标点 |
3. parser.attribute
开启后，你可以给标题 / 代码块 / 段落加 class，示例：
FixIt 的提示、警告块语法就靠这个能力。
4. renderer.hardWraps
false（推荐，上面配置）：标准 Markdown，单独一个回车只是软换行，两个空格 + 回车才换行；true：Notion / 飞书风格，敲回车立刻换行，很多新手喜欢，但不符合标准 md。
5. tableOfContents 目录
startLevel=2：从 h2(##) 开始抓取目录，不抓取 h1（文章标题）
endLevel=4：最多抓到 h4(####)，h5/h6 不进目录，避免目录太长杂乱
ordered=false：目录是无序列表，不是数字有序列表，FixIt 默认样式适配这个
最终
1
2
3
4
5
6
7
8
| # config/_default/markup.toml
[markup]
_merge = "deep"
[markup.highlight]
codeFences = true
lineNos = true
lineNumbersInTable = true
noClasses = false
|