Go Goldmark 软换行与硬换行渲染结果有什么区别

Go Goldmark 里最容易混淆的是：Markdown 源码中的普通回车，和用户明确要求的硬换行，不是同一种语义。普通回车通常仍属于同一个段落，默认 HTML 渲染会保留换行字符；浏览器在普通文本中又会折叠它，所以看起来常常像一个空格。硬换行则会明确输出
。如果打开 html.WithHardWraps()，改变的是软换行的输出方式，并不会把两个段落合成一段。

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

软换行在Goldmark默认配置下会直接渲染成普通空格，不会生成HTML换行标签；硬换行则会被解析为`
`标签实现强制换行，二者的渲染效果差异完全来自Markdown源码的换行规则和Goldmark的扩展配置。

先把三种换行分开

下面这段 Markdown 看起来都有“换行”，但解析结构不同：

第一行
第二行

新段落
硬换行第一行  
硬换行第二行

前两行属于同一个段落，第一行末尾没有硬换行标记；中间的空行会生成两个

；行尾两个空格则把最后两行留在同一段落中，同时要求在两行之间出现硬换行。也可以用行尾反斜杠表达硬换行，但要注意它是 Markdown 语法的一部分，不是 Go 字符串里的普通转义。

因此，想让一段说明文字在源码中便于阅读，不等于想让浏览器强制断行。把每个源码回车都改成
，会让自动换行、复制文本和移动端窄屏阅读变得更僵硬。

Goldmark 默认值和 WithHardWraps 的差别

Goldmark 的 HTML renderer 默认不会把软换行升级为硬换行。需要“源码一行对应页面一行”的场景，可以在 renderer 上显式设置 WithHardWraps()：

package main

import (
    "bytes"
    "fmt"

    "github.com/yuin/goldmark/v2/parser"
    "github.com/yuin/goldmark/v2/renderer/html"
)

func renderMarkdown(source []byte, hardWraps bool) (string, error) {
    // parser 负责识别软换行与显式硬换行，不在这里手工替换换行符。
    doc := parser.New().Parse(source)

    opts := make([]html.Option, 0, 1)
    if hardWraps {
        // 只把软换行输出为 
，空行形成的段落边界仍然保留。
        opts = append(opts, html.WithHardWraps())
    }
    renderer := html.New(opts...)

    var buf bytes.Buffer
    // Render 的 source 必须与 Parse 使用同一份字节内容。
    if err := renderer.Render(&buf, source, doc); err != nil {
        return "", fmt.Errorf("render markdown: %w", err)
    }
    return buf.String(), nil
}

默认模式下，普通回车通常会出现在同一个

的文本中；浏览器如何显示还取决于 CSS 的空白处理。开启硬包裹后，软换行会变成
。显式硬换行本来就是硬换行，两种 renderer 配置都不会把它降级成普通空白。

Markdown 位置	解析含义	默认 HTML	WithHardWraps
段落中普通回车	软换行	保留换行字符
行尾两个空格或反斜杠	硬换行
空行	新段落	新的	新的

中文正文为什么要看 LineBreakStrategy

英文单词之间本来有空格，软换行被当作空白通常不明显；中文连续字符没有词间空格，源码中的回车可能在视觉上留下多余间隔。Goldmark 的 v2 文档提供了 html.WithLineBreakStrategy，可以选择简单的东亚字符规则或 CSS Text Level 3 风格的分段转换。

// 选择 CJK 软换行策略，避免把中文两侧的源码回车显示成多余空格。
renderer := html.New(
    html.WithLineBreakStrategy(html.SimpleEastAsianLineBreakStrategy),
)

// 如果项目要求中文连续文本完全按 CSS 分段规则处理，可改用：
// html.CSSText3LineBreakStrategy

这个策略只处理软换行的呈现方式，不会取消行尾两个空格、反斜杠等显式硬换行。需要诗句、地址清单或逐行字段时，保留硬换行；普通说明、段落和长文本则让浏览器自然换行，通常更利于复制和响应式布局。

按内容类型选择，不要全局强制断行

可以把判断压缩成一张清单：

• 普通技术文章：默认软换行，中文项目再评估 LineBreakStrategy。
• 歌词、诗句、地址或逐行键值：在 Markdown 中明确写硬换行。
• 导入的旧 Markdown 依赖“每行都显示”：短期使用 WithHardWraps()，同时检查列表、引用和复制结果。
• 代码块：由 fenced code block 的语法和 CSS 控制，不要拿正文段落的硬包裹选项代替代码样式。

最后检查三个结果：空行是否仍生成独立段落，显式硬换行是否保持
，中文软换行是否出现不必要的空格。只要这三项符合内容意图，Goldmark 的换行配置就没有越界。

常见问题

开启 WithHardWraps 后空行会失效吗？

不会。空行负责结束段落，WithHardWraps() 只改变段落内部软换行的 HTML 表达。

两个空格和 WithHardWraps 可以一起使用吗？

可以，但两者解决的问题不同：两个空格是输入里的显式硬换行，选项是把普通软换行也升级为硬换行。

中文项目一定要启用 CJK 策略吗？

不一定。先看内容是否依赖源码换行和浏览器显示空白；只有软换行在中文文本中造成多余间隔时，再选择合适的策略。