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() == "</p><h1>Hello</h1>\n"
- 输入必须是
[]byte，不是string（虽可方便转，但接口明确要求字节切片） - 输出写入
io.Writer，不能直接返回字符串——需自己用bytes.Buffer接住 - 默认不渲染 HTML 标签（如
<div>），若需支持，得显式启用 <code>goldmark.WithExtensions(goldmark.Extender)加extension.WithHTML()启用代码块语法高亮（需搭配 Chroma）
goldmark 本身不处理代码块高亮，只生成带
class="go"的<pre class="brush:php;toolbar:false;"><code></code> 结构。要真出颜色，得接 <code>chroma</code> 做渲染，并注册为 goldmark 的 renderer 扩展。</pre>常见错误：只加了
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></details>，或者用了 chroma 却没设 style 导致高亮失效。实际交付前，务必拿含表格、数学公式（需 KaTeX）、front matter 的真实文档跑一遍端到端流程。 - 先
