Go语言需用goldmark解析Markdown为HTML，它支持CommonMark和GFM，默认禁用raw HTML；启用HTML需WithExtensions(extension.WithHTML())，代码高亮需集成Chroma；相对路径需自定义处理器处理。
Go 语言里没有内置 Markdown 解析器，直接用 html/template 或 text/template 渲染原始 Markdown 字符串，只会输出原样文本——不会转成 HTML。 必须借助第三方库，最常用、最稳的是 goldmark；blackfriday 已归档不维护，markdown（by gomarkdown）功能弱且扩展性差，不推荐新项目使用。
用 goldmark 解析 Markdown 到 HTML（基础用法）
goldmark 是目前 Go 生态中事实标准的 Markdown 解析器，支持 CommonMark、GitHub Flavored Markdown（GFM），可插拔扩展。它不自动转义 HTML 标签，但默认禁用 raw HTML——这点和很多用户直觉相反，容易导致“代码块没高亮”“图片不显示”等问题。
基础转换只需几行：
import (
"bytes"
"github.com/yuin/goldmark"
)
<p>md := goldmark.New()
var buf bytes.Buffer
if err := md.Convert([]byte("# Hello"), &buf); err != nil {
panic(err)
}
// buf.String() == "<h1>Hello</h1>\n"
- 输入必须是
[]byte，不是string（虽可方便转，但接口明确要求字节切片） - 输出写入
io.Writer，不能直接返回字符串——需自己用bytes.Buffer接住 - 默认不渲染 HTML 标签（如
<div>），若需支持，得显式启用goldmark.WithExtensions(goldmark.Extender)加extension.WithHTML()
启用代码块语法高亮（需搭配 Chroma）
goldmark 本身不处理代码块高亮，只生成带 class="go" 的 <pre><code> 结构。要真出颜色，得接 chroma 做渲染，并注册为 goldmark 的 renderer 扩展。
立即学习“go语言免费学习笔记（深入）”；
常见错误：只加了 extension.WithHighlighting() 却没配 chroma.Highlighter，结果代码块仍是纯文本。
- 先
go get github.com/alecthomas/chroma/v2 - 创建
chroma.Highlighter实例（推荐chameleon或githubstyle） - 用
goldmark.WithRendererOptions(renderer.WithHighlighting(highlighter))构建 goldmark 实例 - 注意：chroma v2 的 API 和 v1 不兼容，别混用 import 路径
处理相对路径链接与图片（如本地文档引用）
goldmark 默认把 [link](./file.md) 或  当作普通 URL 输出，不会自动补前缀或重写路径。网页里直接打开 HTML 会 404。
解决方式不是改 Markdown 源，而是实现自定义 AST walker 或用 parser.WithLinkProcessor + renderer.WithNodeRenderers 拦截节点：
- 对
ast.KindLink和ast.KindImage节点，在渲染前检查Destination是否以.或/开头 - 按目标文档所在目录（需传入 base path）拼出绝对路径，再写回节点
- 更轻量做法：用正则预处理原始 Markdown 字符串，但会破坏 AST 精确性，不推荐用于复杂文档
- 若最终部署到子路径（如
/docs/），还需在生成 HTML 时注入<base href="/docs/">
goldmark 配置项多、扩展点细，但灵活性也意味着容易漏掉关键环节——比如忘了开 HTML 支持就往里塞 <details>，或者用了 chroma 却没设 style 导致高亮失效。实际交付前，务必拿含表格、数学公式（需 KaTeX）、front matter 的真实文档跑一遍端到端流程。
