要完整显示较长的 Markdown 代码行，请保持代码原样并调整其显示方式。本指南将帮助 Mac 用户诊断示例被截断的问题、在 Obsidian 阅读视图中启用自动换行，并了解这些设置在 GitHub 上是否适用。

哪些因素决定代码行是否换行？

围栏代码块会将代码保留为字面内容。CommonMark 定义了围栏的开始和结束方式，以及内容的解析规则；它没有提供可移植的长行换行开关。其当前规范对应 0.31.2 版。CommonMark 规范：围栏代码块。

GitHub Flavored Markdown 遵循相同的基本围栏代码块规则。其规范同样没有规定可在围栏的信息字符串中添加换行指令。因此，在语言名称后添加 wrap 并不能确立可移植的换行行为。已发布的 GFM 规范标明其版本为 0.29-gfm；不要将该版本号与当前 CommonMark 版本混淆。GitHub Flavored Markdown 规范。

对于此任务，请区分以下三种结果：

结果 读者看到的内容 是否需要更改示例源文本？
视觉换行 一行源文本显示为多行 否
水平滚动 该行延伸到可视区域之外，但仍可查看 否
手动换行 示例中增加了源文本行 是

如果想让整行都显示在窗格内，实际做法是启用自动换行；如果需要保留视觉对齐，则可使用滚动。手动换行需要另行确认示例含义没有改变。

CSS 明确区分了源文本与显示效果：空白字符处理会影响渲染，但不会更改底层文档数据。因此，如果示例需要保持为一行且可复制，视觉换行是一个不错的起点。CSS 文本模块第 3 级。

首先检查示例内容是缺失了，还是仅仅不在视野中

在编辑较长的命令或表达式之前，先检查源文本。在 Obsidian 中，使用编辑模式控件选择 源代码模式。若要在 Mac 上与渲染结果对比，可按 Cmd+E 在编辑视图和 阅读视图 之间切换。Obsidian 将这些视图与作为编辑模式的 实时预览 区分开来。视图与编辑模式。

请在单独的笔记中使用此合成测试。复制其中的 Markdown 内容，包括开头和结尾的三反引号行。内容是普通文本，并非可执行命令。

```text
BEGIN sample=amber notebook=desktop layout=wide description=This synthetic example contains a deliberately long line so you can check whether the final marker remains visible when the note pane becomes narrow END
```

缩窄笔记窗格，并查找 END。如果它出现在续行中，说明自动换行正在工作。如果在代码块中水平移动后能看到它，说明滚动可以访问该内容。如果仍然无法查看，请先将渲染后的代码块与源文本进行对比，再判断文本是否已被删除。

此测试能区分两种需要不同解决方法的问题：源文本内容缺失时，需要恢复示例；内容存在但无法查看时，则需要调整显示方式。尝试设置时保持测试内容不变，这样你就能确认改进是否由所更改的设置带来。

还要检查围栏。结束围栏必须使用与开始围栏相同的字符，且包含至少相同数量的围栏字符。示例中的匹配围栏可能会提前关闭代码块。CommonMark 规范：围栏代码块。讲解 Markdown 语法时，可以使用四反引号的外层围栏来显示包含三反引号的内部代码块，如上所示。创建和高亮显示代码块。

添加 CSS 之前，先为 Obsidian 笔记腾出更多空间

打开 设置 → 编辑器，找到 可读行长度。Obsidian 文档说明，此设置用于限制行的最大长度。暂时将其关闭，然后在相同的窗口尺寸下对比同一篇测试笔记。这是宽度调整；文档并未将其描述为代码块的自动换行开关。设置。

如果现在可以显示完整示例，那么调整宽度或许就足以满足你的桌面布局需求。做决定前，请先测试更窄的窗格：某种窗口布局有更多空间，并不能说明该行在其他布局中仍然易读。

不要试图通过更改 严格换行 来解决代码溢出问题。Obsidian 文档将其与 Markdown 换行相关联，而围栏代码会被视为字面内容。该设置解决的是另一种格式问题。设置，CommonMark 规范：围栏代码块。

在 Obsidian 阅读视图中自动换行较长的代码行

对于选定的笔记，可以使用 Obsidian 文档所述的 CSS 片段机制和 cssclasses 属性。以下是基于该机制和标准 CSS 行为编写的自定义样式，适用于 阅读视图 中普通的已渲染围栏代码块；它不是 Obsidian 提供的自动换行预设，也不是编辑器模式的配置。CSS 片段。

创建并启用片段

  1. 打开 设置 → 外观 → CSS 片段。
  2. 选择 打开片段文件夹。
  3. 使用纯文本编辑器，在该文件夹中创建 wrap-code.css，并保存以下 CSS。
  4. 返回 CSS 片段，选择 重新加载片段，并启用 wrap-code。

这些是 Obsidian 文档中的桌面端安装步骤。启用后，通常会自动应用已保存的片段更改。CSS 片段。

.wrap-code pre,
.wrap-code pre code {
  white-space: pre-wrap;
  overflow-wrap: anywhere;
  word-break: normal;
}

在测试笔记开头添加以下属性块。如果笔记已有属性，请将 wrap-code 添加到现有 cssclasses 值中，而不要再插入第二个属性块。

---
cssclasses:
  - wrap-code
---

Obsidian 文档说明，cssclasses 可用于将自定义 CSS 应用到选定的笔记。在这里，.wrap-code 将规则限定在这些笔记中；其余选择器则针对已渲染的预格式化块及其中的代码内容。此规则不会配置编辑界面。CSS 片段。

了解 CSS 更改的内容

white-space: pre-wrap 声明会保留空白字符和源文本换行，同时允许视觉换行。overflow-wrap: anywhere 声明还允许原本无法断开的字符串在必要时换行，且不会插入连字符。两者结合后，既能处理包含空格的长行，也能处理连续不断的长标记。CSS 文本模块第 3 级，overflow-wrap CSS 属性。

不要将其替换为 white-space: normal：该值会折叠空白字符，从而改变你想保留的视觉缩进。另外，单独使用 overflow-wrap 无法克服禁止换行的空白处理规则。white-space CSS 属性，CSS 文本模块第 3 级。

返回 阅读视图，缩窄窗格，再次检查 END。然后将测试内容复制到纯文本编辑器，并与原文对比。预期结果是：同一行源文本显示为多行。此复制检查可以确认当前安装的渲染器和主题是否按预期工作。

留意不同渲染器之间的差异

Obsidian 外观自定义不会成为围栏代码块可移植的 Markdown 语法。将示例移到其他位置时，请单独测试目标环境。可用下表判断需要检查哪些内容：

目标环境 可依赖的内容 需要单独验证的内容
CommonMark 实现 文档所述的围栏代码块解析规则 自动换行、滚动和可用显示宽度
GitHub 渲染的 Markdown GitHub 文档所述的围栏和语言标识符 目标环境实际的代码块显示方式
Obsidian 阅读视图 已渲染笔记和已启用的本地样式 该片段是否适用于当前主题
Obsidian 实时预览 或 源代码模式 所选编辑模式 编辑器显示方式；上面的片段不会配置它

这些语法边界来自 CommonMark 规范、GitHub 的代码块文档和 Obsidian 的视图文档。

GitHub 文档说明，在开始围栏后添加语言标识符可启用语法高亮。因此，将 text 更改为其他语言标识符，并不是官方文档所述的换行请求方式。请为示例保留正确的标识符，并在负责显示内容的渲染器中处理显示行为。创建和高亮显示代码块。

如果无法控制目标环境的显示方式，可以选择保留完整行，并使用目标环境提供的导航方式；也可以将示例改写成有效的较短源代码行。改写必须遵循示例所用的语言或格式；Markdown 围栏无法使任意插入的换行变得有效。

排查问题时，不要删掉必要内容来缩短代码

如果 Obsidian 规则看起来没有效果，请按以下顺序操作：

  1. 确认你正在测试 阅读视图。
  2. 确认 wrap-code.css 显示在 CSS 片段 中且已启用。
  3. 确认笔记的 cssclasses 中包含且仅包含 wrap-code。
  4. 在查看内容不变的测试笔记时，关闭再重新启用该片段。
  5. 如有需要，暂时禁用其他片段，并与 Obsidian 默认主题进行对比，以排查样式冲突。
  6. 在判定任务完成之前，用实际示例重复测试。

请将选择器规则视为需要在你的安装环境中验证的自定义样式。主题或专用代码块渲染器可能使用不同的样式或结构。如果普通围栏测试正常，但实际代码块不正常，这个差异就是有用的证据：请检查实际代码块所用的渲染器，不要盲目添加换行符。

最后检查时，请确认可以看到最后一个字符、缩进仍然易于理解、复制的文本与预期源文本一致，并且示例在读者将使用的视图中正常显示。保留完整源文本，有意选择自动换行或滚动，并测试所有重要的目标环境。

来源