Go Goldmark 怎么遍历 AST 提取标题目录

我最近给 Markdown 文档加目录时，最初想直接按行找 #，但很快遇到两个问题：链接、强调等行内语法会混进标题文本，Setext 标题也不适合靠前缀判断。更稳妥的做法是让 Goldmark 先把文档解析成 AST，再用 ast.Walk 找到 *ast.Heading，从标题节点的子节点还原可展示文字。

官方地址：https://github.com/yuin/goldmark/

在 Goldmark v1 中，目录提取的关键是保留原始 source []byte，深度优先遍历 AST，只在进入 *ast.Heading 时读取级别和文本子节点，最后把它们整理成目录项。

Goldmark 的 AST 到底保留了什么

Goldmark 的解析结果不是一串已经拼好的标题字符串，而是一棵带层级的节点树。根节点是 Document，标题是 Heading，标题里的普通文字、强调文字或链接文字还会继续作为子节点存在。因此目录代码应该消费这棵树，而不是重新猜测 Markdown 的原始写法。

这篇示例使用 Goldmark v1 的模块路径。官方仓库目前同时说明了 v1 与 v2 的差异：v2 采用新的 github.com/yuin/goldmark/v2 模块和分离的 parser、renderer API；如果项目仍使用 goldmark.New()，请先按 v1 示例接入，迁移时再单独调整 API。

先把 Markdown 解析成可遍历的文档树

解析入口只有三件事：准备 source、创建 Goldmark 实例、把 source 交给 Parser。Parser 读取的是 text.Reader，而后续读取文本节点时仍然需要同一份 source。

package main

import (
    "bytes"
    "fmt"

    "github.com/yuin/goldmark"
    "github.com/yuin/goldmark/ast"
    "github.com/yuin/goldmark/text"
)

func main() {
    source := []byte("# 发布说明\n\n## 变化\n\n- 支持目录提取\n")

    // Parser 会把 Markdown 转成 Document 根节点及其子节点。
    document := goldmark.New().Parser().Parse(text.NewReader(source))

    // 先确认 AST 已经建立，后续 Walk 才有稳定的遍历入口。
    if document == nil {
        panic("Markdown AST 为空")
    }

    var buf bytes.Buffer
    _ = buf
    fmt.Println(document.Kind(), ast.KindDocument)
}

这里的 source 不应该在解析后丢弃。Goldmark 的部分文本节点通过 source 取得实际字节，后面的标题文本提取会复用它。生产代码里也不需要把 AST 转成 HTML 再反向解析，那样会丢掉 Markdown 节点层级。

用 ast.Walk 只捕获标题节点

ast.Walk 按深度优先顺序访问节点，回调的 entering 在进入节点时为 true，离开节点时为 false。目录只需要在进入 Heading 时处理一次；如果在离开时再追加，就容易把嵌套文本的处理时机和标题顺序混在一起。

type TOCItem struct {
    Level  int
    Text   string
    Anchor string
}

func collectHeadings(source []byte, document ast.Node) ([]TOCItem, error) {
    items := make([]TOCItem, 0, 8)

    err := ast.Walk(document, func(node ast.Node, entering bool) (ast.WalkStatus, error) {
        // 离开节点时不重复追加；标题顺序由 AST 的深度优先访问自然保证。
        if !entering {
            return ast.WalkContinue, nil
        }

        heading, ok := node.(*ast.Heading)
        if !ok {
            return ast.WalkContinue, nil
        }

        // 标题文字由子节点组成，先集中读取，再生成目录锚点。
        textValue := headingText(source, heading)
        if textValue == "" {
            return ast.WalkSkipChildren, nil
        }

        items = append(items, TOCItem{
            Level:  heading.Level,
            Text:   textValue,
            Anchor: makeAnchor(textValue),
        })

        // 已在 headingText 中读取标题子树，外层不必再次深入该标题。
        return ast.WalkSkipChildren, nil
    })
    return items, err
}

返回 ast.WalkSkipChildren 是这个实现的一个小取舍：标题的文本已经由内部函数递归收集，外层 Walk 不再进入同一组子节点。若你的回调还要同时统计图片、链接或自定义节点，就应保留 ast.WalkContinue，避免过早跳过。

把标题里的行内节点还原为纯文本

标题可能写成 ## Go 中的 **AST** 目录，也可能包含链接。目录通常只需要用户看到的文字，所以可以递归访问标题子树，只把 *ast.Text 写入缓冲区。这个策略不会把 Markdown 标记本身带进目录。

func headingText(source []byte, heading *ast.Heading) string {
    var buf bytes.Buffer

    // 标题内部可能有 Emphasis、Link 等容器，Walk 能递归到最底层文本节点。
    _ = ast.Walk(heading, func(node ast.Node, entering bool) (ast.WalkStatus, error) {
        if !entering {
            return ast.WalkContinue, nil
        }

        textNode, ok := node.(*ast.Text)
        if !ok {
            return ast.WalkContinue, nil
        }

        // Text.Text 使用解析时的 source 还原文字，而不是读取 Markdown 标记。
        buf.Write(textNode.Text(source))
        return ast.WalkSkipChildren, nil
    })

    return strings.TrimSpace(buf.String())
}

上面的函数需要在文件导入区加入 strings。真实项目还可以按需要补充代码跨度、软换行或自定义节点的处理规则；重点是先明确目录要的是“展示文本”还是“原始 Markdown”。如果要保留原始写法，就不应把所有节点都压成纯文本。

生成目录字段，并处理重复标题

标题级别来自 heading.Level，文本来自递归读取。锚点则是渲染策略，不属于 Goldmark AST 本身。简单项目可以把中文文本转成 URL 编码或使用自有哈希；不要假设自己生成的锚点一定和某个 Markdown 渲染器完全一致。

func makeAnchor(value string) string {
    // 示例只保留字母、数字和连字符，中文标题交给调用方决定是否编码。
    value = strings.ToLower(strings.TrimSpace(value))
    value = strings.Join(strings.Fields(value), "-")
    if value == "" {
        return "section"
    }
    return value
}

func main() {
    source := []byte("# 发布说明\n\n## **变化**\n\n### 变化\n")
    document := goldmark.New().Parser().Parse(text.NewReader(source))

    items, err := collectHeadings(source, document)
    if err != nil {
        // Walk 的错误必须向上返回，不能悄悄发布不完整的目录。
        panic(err)
    }

    for _, item := range items {
        fmt.Printf("%d | %s | #%s\n", item.Level, item.Text, item.Anchor)
    }
}

这段示例展示的是最小目录结构，不是完整的站点 slug 方案。若同一文档里有两个相同标题，应在输出阶段维护一个计数表，为第二个标题追加后缀，或者使用稳定的节点序号；否则目录链接可能指向同一个位置。

把遍历边界和目录结果分开

实际接入文章系统时，我会把“AST 读取”和“目录呈现”拆成两层。前者只负责输出 level、text、anchor，后者再根据层级构造嵌套列表、侧栏或折叠目录。这样既能复用同一份目录数据，也能避免在 Walk 回调里拼 HTML。

v1 和 v2 什么时候要分开处理

如果现有项目导入的是 github.com/yuin/goldmark，本文的 goldmark.New()、Parser().Parse() 和 v1 的 AST 类型可以直接作为思路。官方仓库同时说明，v2 的模块路径是 github.com/yuin/goldmark/v2，解析器和 HTML 渲染器也拆成了不同包；升级时不要只改 import 字符串，还要按 v2 的构造方式调整解析入口。

目录提取的核心没有变：找到 Heading、读取子节点、将结构映射为自己的 TOC 数据。但具体类型签名、文本值类型和构造函数会随模块版本变化，因此应以项目实际依赖的 API 文档为准。

常见问题

为什么不直接用正则匹配 Markdown 标题？

正则很难同时处理 Setext 标题、转义符、链接和行内格式。只要文档允许这些语法，使用 AST 可以让标题级别和文本边界交给解析器。

ast.Walk 的顺序能用于目录排序吗？

可以。它按文档树的深度优先顺序访问节点，标题追加到切片时自然保持出现顺序，不需要再按行号排序。

标题锚点是否应该由 Goldmark 生成？

Goldmark 负责解析 AST，锚点通常由渲染器或站点层决定。若目录要和 HTML 的 id 精确对应，应该让生成 HTML 和目录的代码共享同一套 slug 规则。

小结

用 Goldmark 提取目录可以压缩成一条清晰的链路：保留 source，解析得到 Document，用 ast.Walk 找到 *ast.Heading，递归读取标题文本，再把级别、文本和锚点交给呈现层。这个做法比重新扫描 Markdown 更能覆盖真实文档的行内语法，也为后续自定义节点留下了扩展空间。