将GitHub Markdown转换为Read the Docs时如何保留换行符？

问题本质 #

你碰到的问题核心是：GitHub专属的Markdown（GFM）扩展语法（比如自定义Tooltip、原生HTML折叠面板的换行逻辑），在Read the Docs使用的解析器里不兼容，导致Tooltip失效、折叠面板内容被合并成一行。

一、多行Tooltip的解决办法 #

GitHub那种[tooltip_id]: ## "多行内容"的自定义Tooltip是GFM独有的，Read the Docs不支持，换这两种方式：

1. 用HTML title 属性（最省事） #

直接用<span>配合title属性，用
代表换行：

<span title="this is line 1 of my tooltip&#10;this is line 2 of my tooltip">multiline tooltip</span>

这种方式在Read the Docs里能正常显示多行提示框。

2. 用Sphinx扩展（支持自定义样式） #

如果你的文档是基于Sphinx构建的，装个sphinx-hoverxref扩展就能实现带样式的多行Tooltip：

• 先在requirements.txt里加sphinx-hoverxref
• 再在conf.py里配置启用：

extensions = [
    # 其他已用扩展...
    'sphinx_hoverxref'
]

hoverxref_auto_ref = True
hoverxref_role_types = {
    'ref': 'tooltip',
    'doc': 'tooltip',
}

之后用标准的Markdown/reStructuredText引用语法，内容里用换行或<br>就能实现多行。

二、多行折叠面板（Summary/Details）的解决办法 #

原生HTML的<details>/<summary>在Read the Docs里需要手动处理换行，不然解析器会自动合并文本，试试这两种方式：

1. 插入HTML <br> 标签 #

在需要换行的地方加<br>，空行也可以用<br>实现：

<details>
  <summary>this is an example of a summary with multiple lines details</summary>
  this is line 1 of my details.<br>
  <br>
  this is line 2 of my details.
</details>

2. 用Markdown换行规则 #

每一行结尾加两个空格再换行，同时把折叠内容放在段落块里：

<details>
  <summary>this is an example of a summary with multiple lines details</summary>
  this is line 1 of my details.  
  this is line 2 of my details.
</details>

（注意第一行结尾的两个空格，解析器会识别为换行）

关于Read the Docs直接编辑内容 #

Read the Docs本身没有独立的内置编辑器，它靠GitHub/GitLab等代码仓库存文档源文件。不过你可以点Read the Docs页面右上角的Edit按钮，直接跳转到对应仓库的文件编辑界面改内容，提交后Read the Docs会自动重新构建页面。

内容的提问来源于stack exchange，提问作者ffsb