Nhost 集成指南深入解析 html-to-markdown v2 的 Go 转换器架构、插件机制与 CLI 实战【免费下载链接】nhostThe Open Source Firebase Alternative with GraphQL.项目地址: https://gitcode.com/GitHub_Trending/nh/nhost本文以 Nhost 仓库中 vendored 的github.com/JohannesKaufmann/html-to-markdown/v2版本 v2.5.0见 go.mod为主体系统讲解这套 Go 语言 HTML 转 Markdown 方案的核心 API、可定制选项、插件机制、CLI 用法与底层实现原理。读完本文你将掌握如何用ConvertString一行完成转换、如何用converter.NewConverter组装自定义渲染流水线、如何通过TagType与RendererFor精确控制每个 HTML 标签的输出行为以及如何编写和注册自己的转换逻辑并了解它在 Nhost 的 AI WebFetch 工具中把网页正文转成 LLM 友好 Markdown 的真实落地方式。一、核心能力一览开箱即用的转换覆盖度该库的目标是把 HTML乃至完整网页转换为干净、可读的 Markdown。官方文档列出的能力覆盖了日常写作中最常见的格式化场景粗体与斜体支持bold/italic甚至能在单个英文单词内部正确插入定界符例如unbelievable中间的粗体不会破坏词内结构有序/无序列表完整支持嵌套层级引用块块引用内部可包含其他元素且支持引用嵌套行内代码与代码块正确处理反引号与多行代码块保留代码结构链接与图片正确处理多行链接文本并在需要时为空白行添加转义智能转义Smart Escaping只在必要时转义特殊字符避免意外触发 Markdown 渲染详见 ESCAPING.md移除/保留 HTML可选择剥离或保留特定 HTML 标签完全掌控输出插件体系易于用插件扩展或自行编写自定义插件表格插件支持对齐alignment、rowspan与colspan的表格转换。这些能力分别由base与commonmark两个内置插件承载。其中base负责与 Markdown 语法无关的通用行为移除节点、空白折叠等commonmark负责按 CommonMark Spec 输出语法这一分工也是理解后续所有自定义机制的基础。二、Golang 库快速上手2.1 安装go get -u github.com/JohannesKaufmann/html-to-markdown/v2如需锁定特定提交可在模块路径后追加/v2commithash。在 Nhost 仓库中该依赖以v2.5.0版本固化在 go.mod 中属于正式发布的稳定版本。2.2 最小示例ConvertStringpackage main import ( fmt log htmltomarkdown github.com/JohannesKaufmann/html-to-markdown/v2 ) func main() { input : strongBold Text/strong markdown, err : htmltomarkdown.ConvertString(input) if err ! nil { log.Fatal(err) } fmt.Println(markdown) // Output: **Bold Text** }2.3 更多入口ConvertReader 与 ConvertNode除字符串入口外包级 API 还提供了另外两个入口实现在 convert.goConvertReader(r io.Reader, opts ...)从任意io.Reader读取 HTML 并返回[]byteConvertNode(doc *html.Node, opts ...)如果你已经用golang.org/x/net/html的html.Parse()解析过页面可以直接把解析出的*html.Node传给转换器避免重复解析。从源码看这三个函数都是同一套逻辑的薄封装它们内部都先构造一个挂载了base.NewBasePlugin()与commonmark.NewCommonmarkPlugin()的Converter再调用conv.ConvertString / ConvertReader / ConvertNode。因此它们的默认行为完全一致你可以按输入形态自由选择。2.4 相对链接转绝对链接WithDomain网页中的图片、链接常常是相对路径如/assets/image.png。通过converter.WithDomain可以把它们统一转为绝对链接package main import ( fmt log htmltomarkdown github.com/JohannesKaufmann/html-to-markdown/v2 github.com/JohannesKaufmann/html-to-markdown/v2/converter ) func main() { input : img src/assets/image.png / markdown, err : htmltomarkdown.ConvertString( input, converter.WithDomain(https://example.com), ) if err ! nil { log.Fatal(err) } fmt.Println(markdown) // Output:  }WithDomain的实现位于 converter/convert.go它把 domain 注入转换上下文底层由AssembleAbsoluteURL负责拼接。拼接逻辑converter/url.go有几处值得注意的细节对#单独处理避免空 fragment 被url.Parse误解把链接中的换行、制表符分别替换为%0A、%09提高解析成功率保留查询参数的原始顺序仅做编码并把替换为%20避免mailto:等场景中空格被错误编码遇到data:URI如内联 base64 图片时不拼接域名。这些细节保证了整站抓取转 Markdown场景下的链接可用性。三、从默认包装器到完全可定制converter 与插件组装官方文档明确说明ConvertString()只是converter.NewConverter()base插件 commonmark插件的小型包装。当需要更多控制权时可以直接组装package main import ( fmt log github.com/JohannesKaufmann/html-to-markdown/v2/converter github.com/JohannesKaufmann/html-to-markdown/v2/plugin/base github.com/JohannesKaufmann/html-to-markdown/v2/plugin/commonmark ) func main() { input : strongBold Text/strong conv : converter.NewConverter( converter.WithPlugins( base.NewBasePlugin(), commonmark.NewCommonmarkPlugin( commonmark.WithStrongDelimiter(__), // ...additional configurations for the plugin ), // ...additional plugins (e.g. table) ), ) markdown, err : conv.ConvertString(input) if err ! nil { log.Fatal(err) } fmt.Println(markdown) // Output: __Bold Text__ }注意直接使用NewConverter时务必同时注册base与commonmark两个插件。这一点不只是文档建议——converter/convert.go 中定义了两个显式错误未注册任何 render handler 时报errNoRenderHandlers提示你是否忘了注册 commonmark 和 base 插件注册了commonmark但缺少base时报errBasePluginMissing。转换前会主动校验并返回错误而不是静默产出错误结果。3.1 commonmark 插件配置项详解commonmark插件通过WithXxx选项函数配置输出风格其配置结构体与默认值定义在 options.go默认值填充逻辑在fillInDefaultConfig中可配置项如下选项函数控制内容允许取值默认值WithEmDelimiter斜体定界符_或**在词内表现更佳v2 新默认WithStrongDelimiter粗体定界符**或__**WithHorizontalRule水平分割线任意 Thematic break* * *WithBulletListMarker无序列表符号-、或*-WithCodeBlockFence围栏代码块定界符或~~~WithHeadingStyle标题风格atx或setextatxWithListEndComment列表结束注释布尔值开启WithLinkEmptyHrefBehavior空href链接的处理render渲染为[text]()或skip降级为纯文本renderWithLinkEmptyContentBehavior无内容链接的处理render渲染为[](/page)或skip输出空串render源码注释还预留了CodeBlockStyleindented/fenced、LineBreakStyle、WithLinkStyleinlined/referenced_index/referenced_short等未完成项说明库仍在持续演进中。从实现看NewCommonmarkPlugin会先应用所有选项再调用fillInDefaultConfig补齐默认值最后在Init阶段commonmark.go执行配置校验并注册EscapedChar、一系列UnEscaper、渲染器与文本转换器。3.2 转义模式WithEscapeModeconverter.WithEscapeMode(mode)控制转义的严格程度定义在 converter/converter.gosmart默认只在可能产生歧义的位置加反斜杠转义disabled完全不转义。详见下文转义原理一节中的对比示例。四、Collapse 与 Tag Type精确控制每个标签的行为转换过程中空白折叠collapse依赖每个节点的标签类型块级/行内判断。官方文档指出如果你在使用 Web Components / 自定义元素务必通过TagType或RendererFor注册其类型否则折叠逻辑无法正确处理它们。4.1 三种 TagType 与优先级register.TagType(name, type, priority)为标签注册类型类型定义在 converter/register.goTagTypeBlock块级元素折叠时按块处理前后留空行TagTypeInline行内元素TagTypeRemove在 Pre-Render 阶段直接删除该节点。未注册的标签会回退到dom.NameIsBlockNode / NameIsInlineNode的内置判断register.go。base插件在初始化时已注册了一批默认移除的标签plugin/base/base.go#comment、head、script、style、link、meta、iframe、noscript、input、textarea。这也是为什么转换整站 HTML 时这些噪音元素会自动消失。4.2 预置渲染器base插件提供三个预置渲染器plugin/base/renderers.goRenderAsHTML把节点含子节点整体按 HTML 原样输出块级标签前后补空行RenderAsHTMLWrapper节点本身输出为 HTML 外壳子节点按 Markdown 渲染RenderAsPlaintextWrapper保留子节点的 Markdown 渲染仅处理外层换行。4.3 组合示例官方文档给出的组合示例正好对应其tag_type_renderer截图中的三种场景conv.Register.TagType(nav, converter.TagTypeRemove, converter.PriorityStandard) conv.Register.RendererFor(b, converter.TagTypeInline, base.RenderAsHTML, converter.PriorityEarly) conv.Register.RendererFor(article, converter.TagTypeBlock, base.RenderAsHTMLWrapper, converter.PriorityStandard)把nav整体从输出中移除把b声明为行内元素并按 HTML 原样保留PriorityEarly让它抢先于 commonmark 的粗体渲染器执行把article声明为块级元素输出article外壳、内部转 Markdown。RendererFor是TagTypeRenderer的便捷包装register.go先注册标签类型再注册一个仅当节点名匹配时才调用目标渲染函数否则返回RenderTryNext交给下一个处理器的渲染器。4.4 优先级系统所有注册项都带优先级整数常量定义在 converter/prioritized.go常量值含义PriorityEarly100尽早执行想更早可继续减PriorityStandard500无特殊顺序要求PriorityLate1000尽量靠后执行想更晚可继续加注册的处理函数会按优先级升序排序后依次调用prioritizedSlice.Sort()。例如base插件把节点移除注册为PriorityEarly、把空白折叠注册为PriorityLate确保折叠在其他函数之后执行commonmark 插件把列表结束注释处理注册为PriorityLate100保证在折叠与移除之后运行。这也是覆盖默认行为的入口——例如想保留style标签只需用更高的优先级如PriorityEarly重新注册它。五、插件机制扩展转换能力5.1 Plugin 接口与生命周期插件只需要实现一个极简接口converter/plugin.gotype Plugin interface { Name() string // 插件公开名称如 strikethrough Init(conv *Converter) error // 校验参数并注册规则 }WithPlugins(plugins ...Plugin)逐个调用Register.Plugin(plugin)先记录插件名再执行Init若Init返回错误如配置校验失败错误会被暂存并在首次执行ConvertNode时返回converter/convert.go。base与commonmark两个插件的Init实现base.go、commonmark.go就是按这个模式注册各自规则的范本。5.2 已发布插件一览仓库plugin目录plugin下目前已实现的插件名称状态说明Base已实现通用基础功能节点移除、空白折叠、文本转义等Commonmark已实现按 CommonMark Spec 输出 MarkdownStrikethrough已实现把strike、s、del转为~~语法Table已实现按 GitHub Flavored Markdown 规范输出表格支持对齐、rowspan、colspanGitHubFlavored规划中—TaskListItems规划中—VimeoEmbed / YoutubeEmbed规划中—ConfluenceCodeBlock / ConfluenceAttachments规划中—官方文档同时说明v1 中尚有一部分插件未移植到 v2规划项会陆续补齐。5.3 编写自定义逻辑的两条路径官方推荐的自定义流程分两步编写逻辑并注册先写自己的转换逻辑通过RegisterAPI 挂到转换器上可选打包成插件发布如果逻辑对他人也有价值可打包成插件并发布参考 WRITING_PLUGINS.md注意该文档当前仍是 TODO 占位状态具体规范以Plugin接口与Init注册模式为准。5.4 Register 注册 API 全景Converter.Register暴露的注册入口全部实现在 converter/register.go按转换流水线阶段划分注册方法签名作用PreRendererfunc(ctx Context, doc *html.Node)渲染前对整棵 DOM 树做预处理移除、折叠、打标记等Rendererfunc(ctx Context, w Writer, n *html.Node) RenderStatus渲染单个节点返回RenderTryNext交给下一个处理器RenderSuccess表示完成PostRendererfunc(ctx Context, content []byte) []byte渲染完成后对整段输出做后处理修剪空白、还原转义等TextTransformerfunc(ctx Context, content string) string转换纯文本节点内容HTML 实体替换、转义等EscapedCharfunc(chars ...rune)声明需要转义的字符集合UnEscaperfunc(chars []byte, index int) int在安全场景下撤销多余的转义TagTypefunc(tagName string, tagType tagType, priority int)注册标签的块/行内/移除类型所有注册内部都通过sync.RWMutex保护读取端getXxxHandlers会先拷贝再排序保证并发安全详见下文 FAQ。六、CLI命令行上的 HTML 转 Markdown使用 Golang 库可获得最大的定制能力而 CLI 是最快的上手方式——它也构建在同一个转换器之上。6.1 安装方式官方支持四种途径Homebrew Tapbrew install JohannesKaufmann/tap/html2markdownDebian官方发布deb安装包按云仓库的 Setup Instructions 配置软件源后安装预编译二进制从 releases 页面下载 Linux/macOS/Windows 预编译产物解压后把可执行文件放到系统 PATH如/usr/local/binGo 安装go install github.com/JohannesKaufmann/html-to-markdown/v2/cli/html2markdownlatest会下载源码并编译到 Go 二进制目录通常为$GOPATH/bin。此外发布版本的二进制由 GoReleaser 自动构建并挂载到每个 release本地也可用go build ./cli/html2markdown自行编译。6.2 版本检查html2markdown --version注意务必确认--version输出2.X.X因为 v1 与 v2 各自对应不同的 CLI 程序。6.3 基本用法管道输入是最常用的形态$ echo strongimportant/strong | html2markdown **important**配合curl抓取整页$ curl --no-progress-meter http://example.com | html2markdown # Example Domain This domain is for use in illustrative examples in documents. You may use this domain in literature without prior coordination or asking for permission. [More information...](https://www.iana.org/domains/example)文件批量转换支持通配符$ html2markdown --input file.html --output file.md $ html2markdown --input src/*.html --output dist/6.4 常用选项--help可查看全部配置官方文档示例的常用选项包括--domainhttps://example.com把相对链接转为绝对链接--exclude-selector.ad排除classad的元素--include-selectorarticle只保留article元素参与转换--plugin-strikethrough、--plugin-table启用对应插件。官方同时说明CLI 尚未支持全部库选项定制能力会随时间逐步补全。七、转义Escaping原理7.1 为什么需要转义Markdown 中某些字符有特殊含义例如-可表示列表、强调与分割线。反斜杠\用来转义这些字符使其按字面渲染。转义并非多余比如下面的 HTML 转出的 Markdown 中Paragraph 1下方只有一个-会被 Markdown 解析器误认为setext 二级标题h2Paragraph 1/h2 pParagraph 2/p看似普通的输出-单独一行其实有歧义。一个恰到好处的反斜杠可以消除它Paragraph 1 \- Paragraph 27.2 两种转义模式对比WithEscapeMode(smart)默认与WithEscapeMode(disabled)对同一输入产生不同结果完整示例见 ESCAPING.md内容输入pfake **bold** and real strongbold/strong/psmart 输出fake \*\*bold\*\* and real **bold**smart 渲染fake **bold** 与 realbold正确区分disabled 输出fake **bold** and real **bold**disabled 渲染真假粗体无法区分两处都渲染为粗体smart模式会为歧义字符添加反斜杠输出稍显杂乱但渲染正确disabled模式完全不做转义可能导致意外渲染。因此生产环境建议保持默认的 smart 模式若遇到转义异常的内容可临时禁用并反馈问题。7.3 转义字符集合从 commonmark.go 可以看到commonmark插件注册的转义字符覆盖了 Markdown 的全部语法符号\ * _ - . | $ # [ ] ( ) ! ~ 同时它注册了一整套UnEscaperIsItalicOrBold、IsBlockQuote、IsAtxHeader、IsSetextHeader、IsDivider、IsOrderedList、IsUnorderedList、IsImageOrLink、IsFencedCode、IsInlineCode、IsBackslash在确认上下文安全时撤销多余转义这正是smart的实现机制。八、转换流水线的源码级剖析8.1 三阶段模型ConvertNode的核心流程converter/convert.go是一个清晰的先处理、再渲染、后修饰三段式流水线Pre-Render预处理按优先级依次执行所有PreRenderer对整棵 DOM 树做修改——base插件在此阶段移除废弃节点preRenderRemove、合并相邻文本节点、折叠空白preRenderCollapsecommonmark插件在此阶段为列表添加结束注释标记Render渲染从根节点开始递归渲染结果写入bytes.BufferPost-Render后处理按优先级依次执行所有PostRenderer对完整输出做收尾——base插件的postRenderTrimContent修剪首尾空白与多余换行postRenderUnescapeContent撤销安全场景下的多余转义commonmark插件的handlePostRenderCodeBlockNewline用真实换行替换代码块内部的占位标记。8.2 节点渲染决策链handleRenderNodeconverter/render.go对每个节点按三步决策#text文本节点直接走文本转换管线依次经过所有TextTransformer如 HTML 实体替换、转义遍历所有Renderer按优先级调用返回RenderSuccess即停止返回RenderTryNext则交给下一个处理器兜底逻辑块级节点前后补空行然后递归渲染子节点render.go。RenderStatus只有RenderTryNext与RenderSuccess两个取值status.go这让自定义渲染器可以尝试-回退地链式协作。commonmark 的各类渲染器标题、粗体斜体、链接图片、列表、引用、代码等都以这个模式实现例如 render_heading.go 会根据HeadingStyle生成 ATX#前缀或 setext/-下划线标题并处理行内换行、行尾#转义等边界render_bold_italic.go 则负责在词内正确插入粗体/斜体定界符。8.3 空白折叠的实现来源空白折叠算法collapse/collapse.go是从 JavaScript 生态的 turndown 库移植而来turndown 又改编自 collapse-white-space移植到 Go 时用自定义代码替代了正则以提升性能。其核心逻辑是把任意空白序列统一为单个空格根据块级/行内/void/preformatted 节点决定前后空格去留最终把 DOM 中的冗余文本节点清理干净。文件头部的版权注释如实记录了这条移植链这对评估该算法的成熟度是有价值的背景信息。8.4 内部标记机制渲染过程中库会用一些不可见字符作为内部占位标记marker/marker.goMarkerEscaping使用贝尔字符\a7标记需要转义的位置MarkerCodeBlockNewline使用私有区字符\uF002暂时代替代码块内的换行防止换行在中间处理阶段被破坏最后在 Post-Render 阶段统一还原。九、在 Nhost 仓库中的实际应用这套库在 Nhost 中并非孤立依赖而是真实服务于 AI 能力链路。Nhost 的 AI Agent 提供web_fetch工具用于抓取网页并把内容以 Markdown 形式返回给 LLM其实现位于 services/ai/agents/tool/webfetch.go依赖声明github.com/JohannesKaufmann/html-to-markdown/v2 v2.5.0go.mod导入别名md抓取环节使用带 SSRF 防护的 transport、30 秒超时、最多 5 次重定向、1 MB 响应体上限webfetch.go转换环节仅当响应Content-Type为text/html或application/xhtml时调用md.ConvertString(string(body))webfetch.go一次调用即完成整页 HTML 到 Markdown 的转换输出防护转换结果会被截断到 256 KBtruncateOutput避免病态页面深层嵌套 HTML、密集转义序列产出远超源体积的 Markdown 撑爆 LLM 上下文窗口并在截断处追加...[truncated]标记。这是ConvertString 默认插件组合在真实产品中的典型用法只需一行 API 调用即可把任意网页正文变成干净的、可供 LLM 直接阅读的 Markdown。十、FAQ 与最佳实践10.1 如何扩展自定义逻辑编写自己的逻辑后用Register注册即可不满意库的默认行为用PriorityEarly数值更小让自定义逻辑先于默认规则执行若逻辑对他人有价值可打包成插件发布。10.2 遇到 Bug 如何反馈官方强烈建议提交 issue 时务必附上触发问题的 HTML 片段。没有可复现的 HTML 片段很难定位和修复转换问题。10.3 安全注意事项该库产出的是人类可读、可人工修改的 Markdown不做任何内容净化。当你把 Markdown 转回 HTML 渲染例如用 goldmark、blackfriday时必须警惕恶意内容注入在浏览器中展示之前请先用 bluemonday 之类的 HTML 净化器过滤。安全漏洞报告途径见 SECURITY.md。10.4 goroutine 并发安全Converter可以安全地被多个 goroutine 共享使用。从 converter/converter.go 可以看到Converter内部持有sync.RWMutex所有注册与读取路径Register、getXxxHandlers、getTagType、checkIsEscapedChar、错误状态读写均受其保护读取端还通过拷贝 排序避免数据竞争。官方文档确认存在对应的并发行为测试。10.5 转义与反斜杠Markdown 中某些字符如*具有特殊含义反斜杠\用来转义它们。转义后的字符在最终渲染中不会显示反斜杠这是完全安全的。相关原理可继续阅读 ESCAPING.md。10.6 贡献与测试仓库内置大量Golden File 测试贡献者可以放心实验把你遇到问题的 HTML 片段加入testdata目录下的.in.html文件运行go test -update观察哪些.out.md文件发生变化修改内部逻辑后再次运行go test -update对比影响。提交 PR 前务必运行这些测试并把结果文件一并纳入版本控制。官方同时强调出于向后兼容考虑外部 API 不应随意变更。10.7 许可证除特别说明外项目采用 MIT 许可证授权全文见 LICENSE。结语从ConvertString的一行调用到converter.NewConverter的插件组装再到TagType/RendererFor/优先级体系对每个标签的精细控制html-to-markdown v2 提供了一条从开箱即用到完全自定义的平滑路径CLI 则让非 Go 场景也能直接复用同一套转换引擎。理解其Pre-Render → Render → Post-Render的流水线模型与基于优先级的插件协作机制是掌握这套库的关键。Nhost 的 AI WebFetch 工具展示了它在真实产品中的价值——把网页抓取与 LLM 阅读之间的格式鸿沟用一次 API 调用轻松填平。【免费下载链接】nhostThe Open Source Firebase Alternative with GraphQL.项目地址: https://gitcode.com/GitHub_Trending/nh/nhost创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考