Go Goldmark 怎么为自定义节点实现 HTML 渲染

为 Go Goldmark 的自定义节点实现 HTML 渲染，需要给节点定义独立的 NodeKind，再实现 NodeRenderer.RegisterFuncs，把这个 Kind 绑定到渲染回调，最后通过 WithNodeRenderers 注册。节点保存业务含义，回调负责输出标签，不必重写整套 Markdown 转换逻辑。

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

本文代码固定使用 Goldmark v1.7.13，导入路径不带 /v2。官方仓库已经介绍 v2，两代接口不能混用；这里讨论的是 v1 自定义节点的注册式渲染方式，而非版本迁移。

让节点描述含义，让渲染器负责标签

设想文档系统需要显示一个构建状态徽标。业务数据只保存 Label，例如“build & reviewed”；展示层将它包装为固定 class 的 span。这样修改 HTML 样式时不需要修改业务节点的数据定义。

这个选择只适合“已有 AST 节点，需要另一种 HTML 表达”的问题。识别 Markdown 中的新标记属于解析器职责；已经有普通文本节点却只想改颜色，也不一定需要新增节点类型。

先给自定义节点一个稳定的Kind

Badge嵌入 ast.BaseInline，表示段落内的叶子节点；实现 Kind 和调试用的 Dump，并持有自己的 Label。v1 行内节点实现展示了 BaseInline 的职责。全局 KindBadge 是注册键，不要在 Kind() 方法里每次生成新的 Kind。

注册回调并完成最小HTML输出

NodeRenderer 接口要求 RegisterFuncs。回调收到写入器、原始 source、当前节点和 entering 标记，并返回 WalkStatus 与 error。下面是完整原创示例：手工插入 Badge，把“节点未被解析出来”和“节点没有渲染出来”拆成两个问题。

# 在独立示例目录初始化模块，并锁定本文使用的v1接口版本。
go mod init example.com/badge-render
go get github.com/yuin/goldmark@v1.7.13
# 将下面程序保存为main.go后运行。
go run .

package main

import (
    "bytes"
    "fmt"
    stdhtml "html"
    "log"
    "strings"

    "github.com/yuin/goldmark"
    "github.com/yuin/goldmark/ast"
    "github.com/yuin/goldmark/renderer"
    "github.com/yuin/goldmark/util"
)

// Kind只创建一次，节点与渲染回调必须共用它。
var KindBadge = ast.NewNodeKind("BuildBadge")

type Badge struct {
    ast.BaseInline
    Label string
}

func (n *Badge) Kind() ast.NodeKind { return KindBadge }

func (n *Badge) Dump(source []byte, level int) {
    // 调试输出不参与HTML渲染。
    fmt.Printf("%sBuildBadge: %q\n", strings.Repeat(" ", level), n.Label)
}

type badgeRenderer struct{}

func (r *badgeRenderer) RegisterFuncs(reg renderer.NodeRendererFuncRegisterer) {
    reg.Register(KindBadge, r.renderBadge)
}

func (r *badgeRenderer) renderBadge(
    w util.BufWriter, source []byte, node ast.Node, entering bool,
) (ast.WalkStatus, error) {
    if !entering {
        // 叶子节点已在进入时完整输出，离开时不再重复写入。
        return ast.WalkContinue, nil
    }
    badge := node.(*Badge)
    // Label只进入文本位置；标签与class固定，不接受外部HTML。
    markup := "" +
        stdhtml.EscapeString(badge.Label) + ""
    if _, err := w.WriteString(markup); err != nil {
        return ast.WalkStop, err
    }
    return ast.WalkContinue, nil
}

func main() {
    // 在首次Render之前注册；保留Goldmark的默认HTML渲染器。
    md := goldmark.New(goldmark.WithRendererOptions(
        renderer.WithNodeRenderers(util.Prioritized(&badgeRenderer{}, 100)),
    ))

    // 手工构造AST，隔离渲染问题；此示例不实现Markdown新语法。
    doc := ast.NewDocument()
    paragraph := ast.NewParagraph()
    doc.AppendChild(doc, paragraph)
    paragraph.AppendChild(paragraph, &Badge{Label: "build  & reviewed"})

    var out bytes.Buffer
    if err := md.Renderer().Render(&out, nil, doc); err != nil {
        log.Fatal(err)
    }
    fmt.Print(out.String())
}

根据代码设计，Label 中的尖括号和 & 应当被编码为文本实体，外层固定 span 由自定义回调负责，段落标签仍由默认 HTML 渲染器负责。这是预期行为说明，示例尚未在本文中执行，不是实测输出。

标准库 EscapeString适用于这里的 HTML 文本转义。它不是 URL 规则、CSS 规则或任意 HTML 清洗器；示例故意不允许 Label 拼接到标签名、class 或链接属性中。

不要用渲染器代替语法解析器

注册渲染器不会让 Convert 自动识别新的 Markdown 标记。若需要从文本创建 Badge，应由解析扩展或 AST 转换逻辑生成节点，再交给本回调。直接向 AST 插入节点是本文用来隔离职责的取舍，不是完整语法扩展。

本例 Badge 没有子节点，因此进入时写出完整 span，离开时不写。如果未来把 Badge 改成容器，进入时只写开始标签，离开时写结束标签，让子节点正常渲染；否则可能把内容输出两遍，或者破坏嵌套标签。

配置应在首次 Render 前完成。v1.7.13 渲染器实现在首次渲染时初始化注册表，不要把动态添加回调当成每次渲染前的常规操作。示例的优先级值用于渲染器注册配置，不是遍历步骤编号；新 Kind 不需要和默认节点抢占同一个处理函数。

用最小输入确认扩展的职责

接入时可由读者在自己的项目中分别准备空 Label、普通文字以及含尖括号和 & 的 Label，确认文本不变成标签、只输出一次且默认段落仍存在。再使用一个会返回错误的 writer，确认失败能传到 Render 调用方；不要因为页面看起来有徽标，就忽略写入失败。

必须实现Extender才能渲染吗？

不必。最小示例直接配置渲染选项即可。需要将解析器与渲染器封装为可复用扩展时，再考虑对应扩展入口。

自定义节点可以直接输出Label吗？

在这个文本位置应先转义。固定标签与不可信文本应分开持有，不要把节点值当作已经可信的HTML片段。

为什么Render传入nil作为source？

本例只使用自持有字符串的Badge，没有依赖原 Markdown 字节位置的文本节点。真实解析文档往往有 source 段引用，应传入对应原始字节，不能照搬nil。

这套分离模式的收益是只扩展一个语义节点，不接管无关 Markdown 元素；代价是节点构造、注册键与HTML回调必须保持一致。先证明这个小契约，再接入语法解析，问题会更容易定位。