Go Goldmark 怎么给 Markdown 渲染开启表格扩展

如果 Markdown 里写了下面这种表格，Goldmark 却把它当成普通段落，通常不是表格语法写错，而是没有把表格扩展接到渲染器上。Goldmark 默认以 CommonMark 为基础，表格属于内置扩展能力，需要显式注册。

官方地址：https://github.com/yuin/goldmark/

在 Goldmark v1 中，最小配置是 goldmark.New(goldmark.WithExtensions(extension.Table))。它会让解析器识别 GFM 表格，并让 HTML 渲染器输出对应的 table 结构；如果还需要删除线、任务列表和自动链接，再改用 extension.GFM。

为什么只写表格语法还不够

Markdown 表格至少包含表头行、分隔行和数据行，例如：

| 服务 | 延迟 |
| :--- | ---: |
| api | 18ms |
| worker | 42ms |

这段文本能否变成 HTML 表格，取决于解析阶段是否安装 Table parser；解析出了表格节点之后，渲染阶段还要有对应的 Table HTML renderer。Goldmark 把这两部分打包在同一个扩展里，所以调用方不需要自己改 AST 或手写渲染器。

这里有一个容易混淆的点：extension.Table 是 Goldmark 的扩展对象，不是一个只负责把字符串替换成 HTML 的工具。它同时参与“认出表格”和“渲染表格”这两个边界，因此只导入包而不传入 WithExtensions，不会改变默认解析行为。

Goldmark v1 开启 Table 的最小写法

如果项目使用的是 v1 module path，可以把表格扩展放进 goldmark.New 的选项中：

package main

import (
	"bytes"
	"fmt"

	"github.com/yuin/goldmark"
	"github.com/yuin/goldmark/extension"
)

func main() {
	// 输入包含表头、分隔线和两条数据记录，冒号表示列对齐意图。
	source := []byte("| 服务 | 延迟 |\n| :--- | ---: |\n| api | 18ms |\n| worker | 42ms |\n")

	// Table 同时提供表格解析器和 HTML 表格渲染器。
	markdown := goldmark.New(
		goldmark.WithExtensions(extension.Table),
	)

	var output bytes.Buffer
	if err := markdown.Convert(source, &output); err != nil {
		// Convert 失败时不要继续使用不完整的 HTML。
		panic(fmt.Errorf("convert markdown: %w", err))
	}

	// 这里只展示渲染结果的承载方式，页面样式应由业务 CSS 决定。
	fmt.Print(output.String())
}

关键不在于把 extension.Table 放在某个特定文件里，而在于它必须进入实际负责转换的那个 Goldmark 实例。项目里如果有多个 goldmark.Markdown 对象，给其中一个实例配置扩展，不会影响其他实例。

Table 和 GFM 应该怎么选

只需要表格时，使用 extension.Table 更容易表达依赖边界；如果 Markdown 输入还会出现 GitHub 风格的删除线、自动链接或任务列表，可以直接注册 extension.GFM。官方扩展文档把 GFM 定义为一个聚合扩展，它会包含 Table、Strikethrough、Linkify 和 TaskList。

// 只启用表格，避免额外改变其他 Markdown 语义。
tableOnly := goldmark.New(
	goldmark.WithExtensions(extension.Table),
)

// 输入来自 GitHub 风格 Markdown 时，一次启用一组相关扩展。
gfmMarkdown := goldmark.New(
	goldmark.WithExtensions(extension.GFM),
)

选择时可以按下面的边界判断：

表格对齐为什么看起来没有生效

表格分隔线中的冒号表达的是 Markdown 表格的对齐意图，例如 :--- 表示左对齐，---: 表示右对齐，:---: 表示居中。Goldmark 的表格扩展负责把这个信息带到 HTML 输出，但最终页面是否明显变化，还取决于浏览器对生成属性的处理和站点 CSS。

因此排查时要分开看两层：

• 如果输出根本没有 、 或 ，先检查 extension.Table 是否传入了真正执行转换的实例。
  如果 HTML 已经有表格，但视觉上没有左右对齐，检查站点 CSS 是否覆盖了表头、单元格或表格布局规则。
  如果只想改 HTML 对齐属性的生成方式，应阅读当前版本 extension 包中的 Table 配置，而不是在正文 Markdown 里反复增加空格。

  不要用“在每列内容前后补空格”代替扩展配置。那只能改变源文本的观感，不能可靠地告诉解析器这是一个表格，也不能稳定表达列对齐。

  Goldmark v2 项目不能直接复制这段代码

  官方仓库当前同时说明了 v1 与 v2 的差异。v2 的 module path 是 github.com/yuin/goldmark/v2，顶层的 goldmark.Markdown、goldmark.New 和 goldmark.Convert 已移除，解析器与 HTML renderer 被拆成独立对象。也就是说，v1 文章中的 import 和初始化方式不能直接粘贴到 v2 项目。

  import (
  	"bytes"
  
  	"github.com/yuin/goldmark/v2/parser"
  	"github.com/yuin/goldmark/v2/renderer/html"
  )
  
  func renderV2(source []byte) (string, error) {
  	// v2 把解析器和 HTML 渲染器拆开，扩展也要按对应接口配置。
  	parserInstance := parser.New()
  	renderer := html.New()
  	document := parserInstance.Parse(source)
  
  	var output bytes.Buffer
  	if err := renderer.Render(&output, source, document); err != nil {
  		// 返回错误而不是把半成品当成最终页面。
  		return "", err
  	}
  	return output.String(), nil
  }

  上面的 v2 片段只用来说明 API 形态差异，不能把它当成 v1 的表格配置替代品。迁移时要根据项目依赖的 v2 扩展接口，分别给 parser 和 renderer 加入支持表格的扩展；如果第三方扩展还不支持 v2，也要先确认兼容范围。

  扩展不生效时按这张清单排查

  1. 确认 module path。看 go.mod 使用的是 github.com/yuin/goldmark 还是 github.com/yuin/goldmark/v2，不要混用两代 API。
  2. 确认实例。查找最终调用 Convert 或 renderer 的对象，确保扩展注册在同一个转换链路上。
  3. 确认输入形状。表头、分隔线和数据行需要保持表格结构；把分隔线改成普通文本，解析器就没有表格节点可生成。
  4. 确认 CSS 边界。有 table 标签但没有预期视觉效果时，问题已经从 Markdown 解析转移到了页面样式。
  5. 确认扩展范围。需要任务列表或删除线时，不要只加 Table 后再猜测其他语法为什么没有改变。

  结论与延伸问题

  Go Goldmark 开启 Markdown 表格的核心只有一处：在 v1 的 Goldmark 实例上使用 goldmark.WithExtensions(extension.Table)。Table 负责最小表格能力，GFM 负责一组相关语法；对齐显示还要经过 HTML 输出和站点 CSS 两层。项目升级到 v2 时，先处理 module path 以及 parser/renderer 拆分，再重新接入对应扩展。

  只想保留表格，为什么不直接用 GFM？

  可以用，但它会同时打开其他 GFM 语义。如果输入来自不完全受控的文档，使用 Table 单扩展通常更容易预测。

  表格扩展需要自己注册 HTML 标签吗？

  不需要。内置 Table 扩展已经包含与表格节点对应的 HTML 渲染能力，业务只需要把扩展交给实际使用的 Goldmark 实例。

  HTML 有 table 但列没有居中，说明扩展失败了吗？

  不一定。先确认 HTML 中的对齐信息，再检查页面 CSS；解析成功和浏览器最终呈现是两个不同层次的问题。