Go comment.Heading.DefaultID 怎样生成文档标题锚点

Go 的 comment.Heading.DefaultID() 可以直接取得文档标题的默认锚点：ASCII 字母和数字保留，其他 rune 各自变成下划线，再加 hdr- 前缀。它不会为整页分配唯一编号；做目录时，应让目录链接和正文标题共用一份 ID 映射。

官方地址：https://pkg.go.dev/go/doc/comment

默认规则能保留什么

如果已经有一个 *comment.Heading，调用其方法即可；只想理解转换规则，也可以构造一个纯文本标题。下面是独立的最小示例。

package main

import (
    "fmt"
    "go/doc/comment"
)

func main() {
    // Plain表达标题正文，不需要写入HTML标签或注释前缀。
    h := &comment.Heading{Text: []comment.Text{comment.Plain("Cache Setup")}}
    fmt.Println(h.DefaultID())
}

按规则推导，Cache Setup 对应 hdr-Cache_Setup。字母大小写保持不变，所以不要在目录生成端额外转小写。这里的结果用于解释规则，不作为本地运行记录。

中文、符号和同名标题为什么会碰撞

“非 ASCII”不等于只有标点：中文字符同样属于替换范围。转换单位是 rune，而不是 UTF-8 字节。连续的替换字符也不能擅自合并，否则自己的目录算法就偏离了默认规则。

因此，既要考虑同名标题，也要考虑不同标题转换后的碰撞。DefaultID 只依赖当前标题，不知道页面中还有哪些标题。中文目录应保存原来的显示文字，并单独管理链接标识。

目录与正文共用页面级分配

Printer.HeadingID 是自定义锚点的接入点；不设置时采用默认方法，回调返回空字符串则省略 ID。下面的完整示例先收集标题，再用共享映射渲染目录和正文。目录暂以 ID 作为可见标签，方便看清绑定关系；产品中可将标签换成经过转义的标题纯文本。

package main

import (
    "fmt"
    "go/doc/comment"
    "html"
    "strings"
)

// render 同时返回目录和正文，让两者使用同一份标题映射。
func render(d *comment.Doc) (string, string) {
    ids := make(map[*comment.Heading]string)
    used := make(map[string]bool)
    var toc strings.Builder
    for _, block := range d.Content {
        h, ok := block.(*comment.Heading)
        if !ok {
            continue
        }
        // 分配完整候选ID，避免后缀与原本就带数字的标题撞名。
        base := h.DefaultID()
        id := base
        for suffix := 2; used[id]; suffix++ {
            id = fmt.Sprintf("%s-%d", base, suffix)
        }
        used[id] = true
        ids[h] = id
        fmt.Fprintf(&toc, "
%s
\n",
            html.EscapeString(id), html.EscapeString(id))
    }
    pr := comment.Printer{
        HeadingID: func(h *comment.Heading) string {
            return ids[h] // 返回已经分配的ID，不在回调中再次计数。
        },
    }
    return "
" + toc.String() + "
", string(pr.HTML(d))
}

func main() {
    // Parser接收已去掉注释标记的文本；两个同名标题故意用于演示碰撞。
    var parser comment.Parser
    doc := parser.Parse("# Cache Setup\n\n缓存设置说明。\n\n# Cache Setup\n\n另一处设置说明。\n")
    toc, body := render(doc)
    fmt.Print(toc, body)
}

页面已用集合 检查的是最终候选值，不只是某个基础标题出现了几次。标题映射 以当前文档中的 Heading 指针作键，供 Printer.HeadingID 和目录链接共同读取，避免渲染回调多调用一次就产生不同后缀。

页面集成时保留哪些约束

这个示例处理单份 Doc 的顶层标题。如果多个 Doc 拼到同一个 HTML 页面，应把已用集合扩展到整页，并预留外层模板已经使用的 ID。映射绑定的是这次解析出的对象；重新解析后应重新建立映射。

后缀策略能解决当前页面中的重复，但不保证改标题、插入同名章节之后旧书签仍然稳定。对外长期分享的文档，可由站点维护显式且稳定的章节标识，再由同一个回调供给正文与目录。这属于站点设计，不能说成 DefaultID 内置的持久链接能力。

手工拼 HTML 时要转义可见文字和属性值，不能直接把标题当成可信 HTML。使用 Printer 渲染正文，也不代表周边模板可以省略自己的转义。

相关问题

能直接给中文标题生成拼音吗？默认方法不负责拼音转换，需要应用另行制定 ID 策略。

只生成目录时再调用 DefaultID 可以吗？正文完全采用默认值且没有碰撞时可以；一旦做了后缀或自定义处理，就应读取与正文相同的映射。

需要重写整个文档解析器吗？不需要。保留 Parser 与 Printer，通过 HeadingID 定制锚点即可。

规则依据：Heading.DefaultID 文档、Printer 配置、HTML 渲染实现。