# Markdown解析 + 代码高亮 [Markup]


##  一、合并必要的配置

单独拆成 `config/_default/markup.toml`，用 `_merge="deep"` 合并，不和菜单混在同一个文件，结构干净。

```
# config/_default/markup.toml
[markup]
_merge = "deep"
```

## 二、完整代码

```
# 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          | `|表头|`              | Markdown 表格            |
| taskList       | `- [ ] 待办`          | 复选任务列表             |
| typographer    | `<< >> -- ---`        | 智能美化标点             |

### 3. parser.attribute

开启后，你可以给标题 / 代码块 / 段落加 class，示例：

```
## 标题 {#my-title .red}
```

FixIt 的提示、警告块语法就靠这个能力。

### 4. renderer.hardWraps

- `false`（推荐，上面配置）：标准 Markdown，单独一个回车只是软换行，**两个空格 + 回车**才换行；
- `true`：Notion / 飞书风格，敲回车立刻换行，很多新手喜欢，但不符合标准 md。

### 5. tableOfContents 目录

- `startLevel=2`：从 `h2(##)` 开始抓取目录，不抓取 h1（文章标题）

- `endLevel=4`：最多抓到 `h4(####)`，h5/h6 不进目录，避免目录太长杂乱

- `ordered=false`：目录是无序列表，不是数字有序列表，FixIt 默认样式适配这个

##  最终

```
# config/_default/markup.toml
[markup]
_merge = "deep"
[markup.highlight]
codeFences = true
lineNos = true
lineNumbersInTable = true
noClasses = false
```


---

> 作者: Anonymous  
> URL: https://www.1mt.run/posts/583bc6a/