Joplin 的 HTML 转 Markdown 机制换行、连续空行与 HtmlToMd 测试实证【免费下载链接】joplinJoplin - the privacy-focused note taking app with sync capabilities for Windows, macOS, Linux, Android and iOS.项目地址: https://gitcode.com/GitHub_Trending/jo/joplin本文以 Joplin 仓库中packages/app-cli/tests/html_to_md/repeated_brs.html/repeated_brs.md这一对测试夹具为主体结合 HtmlToMd 核心实现 与 测试驱动脚本完整讲清 Joplin 在 HTML→Markdown 转换中如何处理br/换行、连续多个br/产生的空行以及行尾br/为何会被丢弃。读完后你能理解 Joplin 富文本/剪藏内容转为 Markdown 时换行语义的完整约定并能复现、扩展这套测试。测试用例对输入 HTML 与期望输出repeated_brs.md本身是期望输出文件fixture与同目录的输入文件配套使用。测试驱动 packages/app-cli/tests/HtmlToMd.tsL9-L94会扫描packages/app-cli/tests/html_to_md/目录下所有.html文件把内容包进div后交给HtmlToMd.parse()再与同名.md文件逐字节比对repeated_brs.html不命中任何特殊分支因此使用全默认选项解析。输入文件 repeated_brs.html 全文如下Abr/br/br/test.br/ A single lt;br/gt;br/can use two spaces at the end of the line, butbr/br/the markdown renderer discards these if the line is otherwise empty.期望输出 repeated_brs.md 全文如下Abr/br/test. A single lt;br/gt; can use two spaces at the end of the line, but br/the markdown renderer discards these if the line is otherwise empty.注意输出中保留的br/是字面标签Joplin 笔记支持行内 HTML而输入中的lt;br/gt;是转义文本即字面字符串br/原样保留、不做转换。换行映射规则从这份夹具能读出的三种情形把输入与输出逐段对照可以归纳出三条可验证的映射行为。夹具文本自己也用英文把设计理由写了出来A singlebr/can use two spaces at the end of the line, but the markdown renderer discards these if the line is otherwise empty输入片段期望输出语义Abr/br/br/test.A换行 br/br/test.连续 3 个br/保留 1 次真实换行 2 个字面br/标签表示A 与 test 之间有两个空行line,换行butline, but同一行源码中普通的换行符在 Markdown 段落内是 soft break渲染为空格butbr/br/the ...but换行 br/the ...连续 2 个br/1 次真实换行 1 个字面br/test.br/行尾、之后无内容test.尾部br/消失行尾br/会生成仅含行尾空格的空行而 Markdown 渲染器会丢弃这种行因此被直接省去设计动机在于Markdown 中硬换行的惯用写法是行尾两个空格加换行但这种表示法无法表达真正空出一行——空行里的两个空格会被渲染器当作无意义空白丢弃。Joplin 因此对仅由br/撑出的空行改用字面br/标签来表达保证 HTML→Markdown→HTML 的往返渲染等价。源码佐证br: 选项与 Joplin 的 turndown 分叉核心实现在 packages/lib/HtmlToMd.ts。parse()方法把 Joplin 的ParseOptionsL7-L18含anchorNames、preserveTableStyles、tightLists、collapseMultipleBlankLines等映射为 turndown 构造参数其中与换行直接相关的配置是L36-L39// If soft-breaks are enabled, lines need to end with two or more spaces for // trailing br/s to render. See // https://github.com/laurent22/joplin/issues/8430 br: ,要点Joplin 使用的是自己的 turndown 分叉 packages/turndown模块名joplin/turndown而非上游 turndown。br是 turndown 的标准选项定义br的替换文本而collapseMultipleBlankLines、tightLists等参数从源码结构看由该分叉实现HtmlToMd只负责透传L42-L43。br: 的含义即上文夹具所说明的约定单个br/被替换为两个空格配合换行形成行尾双空格硬换行。源码注释明确指出这是为了让行尾br/在启用 soft-breaks 时也能正确渲染对应仓库 issue 编号 #8430见 HtmlToMd.ts 注释。其他默认转换参数也固定于此headingStyle: atx、codeBlockStyle: fenced、bulletListMarker: -、emDelimiter: *、strongDelimiter: **并注册 GFM 插件、remove(script)/remove(style)L23-L67。parse()返回值可选地经markdownUtils.prependBaseUrl补全相对链接前缀L84-L85repeated_brs测试未设置baseUrl故输出为纯文本对比。相关约定与邻近测试代码块内不加行尾空格。同目录的 linebreaks.html / linebreaks.md 进一步固化了换行约定其夹具文本写明 br-style linebreaks should be replaced with two spaces followed by a newline并特别约束pre内的br不得产生行尾空格污染代码块期望输出中代码块各行均无尾部空格。这与repeated_brs是同一约定在不同节点类型下的补充。多个连续br与空行折叠。测试驱动脚本 中另有一个针对collapseMultipleBlankLines的用例输入pFirst/pbrbrbrpSecond/p时默认false保留多段空行结果含\n\n \n开启后折叠为单个空行。这说明br序列产生的空行在块级边界处的处理是独立的、可配置的与repeated_brs用例中空行用字面br/标签表达的段落内策略互为呼应。如何复现与扩展在packages/app-cli目录下用 Jest 运行该测试套件即可配置见 jest.config.jscd packages/app-cli yarn jest tests/HtmlToMd.ts测试失败时驱动脚本会把实际输出 / 期望输出逐行加引号打印HtmlToMd.ts便于精确定位差异行。若需新增换行类用例只需在packages/app-cli/tests/html_to_md/下放入xxx.html与同名xxx.md注意测试会把 HTML 整体包进div且 Windows 下自动归一化 CRLF无需修改驱动脚本只有当用例需要特殊解析选项如preserveTableStyles、tightLists时才按文件名前缀在 L27-L49 增加分支。【免费下载链接】joplinJoplin - the privacy-focused note taking app with sync capabilities for Windows, macOS, Linux, Android and iOS.项目地址: https://gitcode.com/GitHub_Trending/jo/joplin创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考