Go 文档渲染器怎样自定义包链接和符号链接

如果你用 go/doc/comment 把 Go 文档注释转成 HTML 或 Markdown，默认生成的包链接通常够用，但接入自己的文档站点后，包、类型、方法和当前包符号往往需要不同路由。结论很直接：只想统一文档根路径时设置 Printer.DocLinkBaseURL；需要按符号重写地址时设置 Printer.DocLinkURL；标题锚点则交给独立的 HeadingID。

不要在渲染后的 HTML 上二次替换链接字符串。让 DocLinkURL 直接根据 DocLink.ImportPath、Recv 和 Name 生成目标地址，HTML 与 Markdown 就能共享同一套路由规则。

先判断默认链接是否已经够用

comment.Printer 的文档链接来自解析后的 DocLink。它用三个字段描述目标：ImportPath 表示外部包，Recv 表示方法接收者，Name 表示包、常量、函数、类型、变量或方法名称。

当没有自定义回调时，DocLink.DefaultURL 会按以下规则构造地址：

排查时先看这三个字段，而不是先看输出格式。如果只是 baseURL 不符合你的站点入口，保留默认规则更稳；如果连方法路由、当前包锚点都要改变，再进入自定义回调。

用 DocLinkBaseURL 统一切换文档站点

DocLinkBaseURL 是最小改动方案。它只在 DocLinkURL 为空时参与默认 URL 计算，因此可以把默认的 pkg.go.dev 风格路径切换到自己的文档根目录，同时继续保留包链接和符号锚点的语义。

package main

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

func main() {
	var parser comment.Parser
	doc := parser.Parse("查看 [fmt]、[fmt.Println] 和 [Render]。")

	printer := comment.Printer{
		// 只替换默认文档根路径，包和符号的锚点仍由标准规则生成。
		DocLinkBaseURL: "https://docs.example.com/go/",
	}

	// HTML 与 Markdown 都会使用同一个 Printer 配置。
	fmt.Println(string(printer.HTML(doc)))
	fmt.Println(string(printer.Markdown(doc)))
}

这类配置适合“站点结构和 Go 文档默认结构一致”的情况。例如外部包链接仍然按包路径排列，类型和方法仍然使用锚点，只是根地址从默认值变成自己的域名。注意末尾斜杠会影响锚点前是否再插入一个斜杠，统一写法更容易维护。

用 DocLinkURL 处理自定义路由

如果你的站点把包首页放在 /packages/，把类型放在 /symbols/，把方法放在 /methods/，就应该直接实现 DocLinkURL。它接收一个 *comment.DocLink，返回空字符串时链接不会生成 href，因此回调必须明确返回可用地址或本地锚点。

package main

import (
	"net/url"
	"strings"

	"go/doc/comment"
)

func customDocLink(link *comment.DocLink) string {
	// 没有 ImportPath 代表当前包，必须保留本地锚点。
	if link.ImportPath == "" {
		if link.Recv != "" {
			return "#" + link.Recv + "." + link.Name
		}
		return "#" + link.Name
	}

	base := "https://docs.example.com"
	packageURL := strings.TrimSuffix(base, "/") + "/packages/" + link.ImportPath
	if link.Name == "" {
		// 只有包路径时指向包首页。
		return packageURL
	}
	if link.Recv != "" {
		// 接收者和方法名分别作为路由段，避免依赖锚点格式。
		return packageURL + "/methods/" + url.PathEscape(link.Recv) + "/" + url.PathEscape(link.Name)
	}
	// 外部包中的普通符号走独立的符号路由。
	return packageURL + "/symbols/" + url.PathEscape(link.Name)
}

func makePrinter() comment.Printer {
	return comment.Printer{
		// 回调优先级高于 DocLinkBaseURL，二者不必同时设置。
		DocLinkURL: customDocLink,
	}
}

这个回调的关键是先处理当前包，再处理外部包。当前包的 DocLink 没有 ImportPath，如果无条件拼接 /packages/，本来应该跳到当前页面锚点的链接就会被错误地变成外部路径。

把当前包链接、外部包链接和标题锚点分开

实际接入时最容易混淆的是三个层次：

• DocLinkBaseURL：只影响默认的文档链接根路径。
• DocLinkURL：决定每个包或符号最终使用什么 URL。
• HeadingID：决定 Markdown 或 HTML 标题的锚点 ID，与 DocLink 不是同一类链接。

如果标题需要稳定 ID，可以单独设置 HeadingID，不要在 DocLinkURL 里猜测标题文本。标题回调接收的是 *comment.Heading，文档链接回调接收的是 *comment.DocLink，让两个职责保持独立即可。

printer := comment.Printer{
	// 让所有标题使用站点约定的前缀，避免标题文本变化导致锚点漂移。
	HeadingID: func(h *comment.Heading) string {
		return "section-" + h.DefaultID()
	},
	// 符号链接仍按包路由处理，不和标题锚点共享逻辑。
	DocLinkURL: customDocLink,
}

出现链接不对时的处理顺序

先把问题按字段分层，通常不需要改解析器：

1. 如果所有外部链接只有域名或根路径不对，先检查 DocLinkBaseURL 是否带有期望的尾部斜杠。
2. 如果只有方法链接错误，打印或记录 ImportPath、Recv、Name，检查回调是否把方法当成普通符号。
3. 如果当前包链接跳到了包首页，检查 ImportPath == "" 分支是否返回了 #Name 或 #Recv.Name。
4. 如果 HTML 正常而 Markdown 不正常，确认两个输出是否使用了同一个 Printer，不要为不同格式复制两套路由判断。

回滚也很简单：删除 DocLinkURL，只保留经过确认的 DocLinkBaseURL，就能回到标准默认路由。等站点的包、符号和方法页面准备好后，再逐步打开自定义分支。

最后确认一份最小配置

如果你的目标只是把 Go 文档链接放到新域名，使用 DocLinkBaseURL；如果不同类型需要不同页面形态，使用 DocLinkURL，并始终保留当前包的本地锚点分支。HTML 和 Markdown 共享 Printer 配置，标题 ID 单独由 HeadingID 负责，职责边界就不会互相污染。

速查：统一根路径看 DocLinkBaseURL；精确路由看 DocLinkURL；当前包看空的 ImportPath；方法看非空的 Recv；标题锚点看 HeadingID。

相关问题

DocLinkBaseURL 和 DocLinkURL 能同时设置吗？可以，但只要 DocLinkURL 返回了地址，默认的 DocLinkBaseURL 就不会替它计算该链接。需要完全自定义路由时，通常只保留回调更清楚。

当前包的符号为什么没有 ImportPath？这是用于表达当前文档包内引用的状态，默认结果就是当前页面的本地锚点。

能不能只改 HTML 的链接而不改 Markdown？Printer 的链接回调由 HTML 和 Markdown 共用。如果两种格式必须不同，应在回调外增加输出格式上下文，或分别创建两个 Printer，但不要依赖输出后的字符串替换。