选用 goldmark 是因 blackfriday 已归档、不支持扩展语法且 xss 过滤粗，而 goldmark 活跃、接口清晰、默认 html 转义安全；需手动配置扩展、白名单 html 标签、校验属性、引入 css 与编码处理。
为什么不用 blackfriday 而选 goldmark
blackfriday 已归档，不再维护，新项目遇到扩展语法（如表格、脚注、数学公式）或安全问题（如 XSS 过滤粒度粗）时基本没法改。而 goldmark 是当前 Go 生态最活跃的 markdown 解析器，接口清晰、扩展机制明确，且默认开启 HTML 转义——这点对命令行工具或服务端渲染很关键。
实操建议：
立即学习“go语言免费学习笔记（深入）”；
- 用
goldmark.New()初始化解析器，别直接调goldmark.DefaultParser()，后者不带扩展，表格都渲染不出来 - 启用常用扩展：传入
goldmark.WithExtensions(&astextension.Extender{})（注意是astextension，不是extension） - 若需自定义渲染 HTML 标签（比如给
<code>加 class），得自己写html.Renderer实现，不能只靠配置
如何安全地允许部分 HTML 标签（比如 <iframe></iframe> 或 <video></video>）
默认情况下 goldmark 会丢弃所有原始 HTML，这是对的；但有些场景（如内部文档系统）确实要放行特定标签。强行开 WithUnsafe() 等于把 XSS 风险全交给上层处理，不推荐。
实操建议：
立即学习“go语言免费学习笔记（深入）”；
- 用
html.WithUnsafeRender()+ 自定义html.Renderer的RenderTag方法，在里面白名单过滤：只放行<iframe></iframe>、<video></video>、<source></source>等，其余一律返回 false - 对
<iframe src="..."></iframe>这类属性，必须校验协议（只允https://）、域名（可配正则）、长度（防超长 URL） - 别忘了禁用
onerror、onclick等事件属性——goldmark不自动过滤属性，得在RenderTag里手动剔除
goldmark 渲染后 CSS 样式丢失？检查这三处
很多人把 Markdown 渲染成 HTML 后发现代码块没高亮、表格没边框、标题没缩进，第一反应是“库没配好”，其实大概率是输出环节漏了。
实操建议：
立即学习“go语言免费学习笔记（深入）”；
- 代码块高亮依赖外部库（如
chroma），goldmark本身不带；需注册chroma.HighlightingRenderer，且确保chroma的Style被正确注入到html.Renderer - 表格、任务列表等样式需前端 CSS 支持；
goldmark只生成语义化 HTML（如<table class="markdown-table">），你得自己写或引入对应 CSS <li>如果用 <code>html.WithHardWraps()，换行符会转成<br>，但某些 CSS 重置会清掉<br>的 margin，导致段落粘连——检查浏览器开发者工具里是否真有<br>节点 - 读文件前先用
filepath.Abs()规范路径，避免相对路径跨目录出错 - 检测文件编码：用
golang.org/x/text/encoding包探测，GBK 检出后转 UTF-8 再喂给goldmark；别依赖os.ReadFile原样读 - 输出 HTML 文件时，记得在
插入<meta charset="UTF-8">，否则浏览器可能按系统默认编码解析，中文变乱码
命令行工具中怎么处理文件路径和编码
windows 用户常遇到中文路径报 open xxx: The system cannot find the file specified，linux/macos 用户可能栽在 GBK 编码的旧文档上——goldmark 只吃 UTF-8，不自动转码。
实操建议：
立即学习“go语言免费学习笔记（深入）”；
真正麻烦的是混合编码的存量文档和 Windows 下的长路径限制，这些没法靠一个库解决，得在入口层兜底。