Rendered note metadata【免费下载链接】joplinJoplin - the privacy-focused note taking app with sync capabilities for Windows, macOS, Linux, Android and iOS.项目地址: https://gitcode.com/GitHub_Trending/jo/joplinJoplin 允许在笔记渲染后的 HTML 版本中使用特定的元数据标签来控制输出行为。目前唯一支持的标签是print-title它用于控制笔记标题在打印或导出时是否显示。本文详细讲解该标签的语法、使用方法、底层实现原理及实际应用场景。什么是渲染笔记元数据Rendered Note MetadataJoplin 的笔记在编辑器中以 Markdown 形式存储但在渲染如打印、导出 HTML时会转换为 HTML 格式。渲染笔记元数据是嵌入在渲染后 HTML 中的特殊 HTML 注释标签用于向渲染器传递配置指令。其设计初衷是当需要控制渲染输出行为但又不希望这种控制在笔记源文件中占用可见空间或影响 Markdown 解析时可以通过 HTML 注释形式携带元数据。由于 HTML 注释在渲染过程中会保留在输出中见 桌面版 changelog 中 Keep comments when rendering Markdown to allow rendered note metadata 的改进记录因此可以被 Joplin 的渲染管线识别并解析。该功能首次引入于 桌面版 changelog 中记录的 Added support for rendered note metadata, in particular the joplin-metadata-print-title tag。print-title 标签控制笔记标题的打印与导出print-title是目前唯一受支持的渲染笔记元数据标签用于控制笔记标题是否在打印或导出的文档顶部显示。默认行为默认情况下当笔记被打印或导出时笔记的标题会显示在文档顶部。这一行为由RenderedNoteMetadata接口的printTitle字段控制默认值为true定义在 packages/lib/services/interop/utils.tsexport interface RenderedNoteMetadata { printTitle: boolean; }禁用标题打印在某些场景下默认的标题显示行为并非所愿。例如当插件需要生成带有自定义页眉的文档时笔记标题的自动添加会造成重复或布局冲突。此时可以在笔记中插入该标签并将其值设置为false来禁用默认行为。在文档中直接添加标签即在笔记的 Markdown 正文中包含以下一行!-- joplin-metadata-print-title false --该标签有两种添加途径直接在 Markdown 文档中写入如上所示适用于单个笔记的精细控制通过 Markdown-it 内容脚本content script在渲染时注入适用于插件需要动态控制或批量处理多个笔记的场景。取值规则标签的值遵循以下解析规则源码见 packages/lib/services/interop/utils.ts标签值解析结果printTitle说明falsefalse禁用标题打印truetrue启用标题打印0false数字 0 视为禁用1true数字 1 视为启用未出现标签true默认启用其核心解析逻辑为output.printTitle propValue.toLowerCase() true || propValue 1;即值字符串的小写形式等于true或值恰好为1时printTitle为true其余情况包括false、0以及任何其他值均为false。底层实现parseRenderedNoteMetadata 解析器渲染笔记元数据的解析由parseRenderedNoteMetadata函数完成位于 packages/lib/services/interop/utils.tsexport const parseRenderedNoteMetadata (noteHtml: string) { const output: RenderedNoteMetadata { printTitle: true, }; // !-- joplin-metadata-print-title false -- const match noteHtml.match(/!--[\s]joplin-metadata-(.*?)[\s][\s](.*?)[\s]--/); if (match) { const [, propName, propValue] match; if (propName print-title) { output.printTitle propValue.toLowerCase() true || propValue 1; } else { throw new Error(Unknown view metadata: ${propName}); } } return output; };正则解析规则解析器使用如下正则表达式匹配标签/!--[\s]joplin-metadata-(.*?)[\s][\s](.*?)[\s]--/从中可以推导出标签的严格语法要求前缀必须以!--开头后跟至少一个空白字符空格、制表符等然后是joplin-metadata-属性名joplin-metadata-后捕获属性名如print-title等号等号前后各需至少一个空白字符属性值等号后捕获属性值如false后缀以--结束且--前需至少一个空白字符。可见标签对空白字符是宽容的!-- joplin-metadata-print-title 0 --等号两侧多个空格同样可以正确解析。未知元数据的错误处理如果解析到非print-title的属性名解析器会抛出Unknown view metadata: ${propName}错误。这意味着标签名是白名单式的目前仅print-title一个合法属性名任何拼写错误或自定义的其他标签都会导致解析失败。从源码结构看该设计为未来新增其他渲染元数据标签预留了扩展点只需在if (propName ...)分支中增加新属性即可。HTML 导出器如何消费该元数据print-title元数据的实际消费方是 HTML 导出器InteropService_Exporter_Html位于 packages/lib/services/interop/InteropService_Exporter_Html.tsconst noteContent []; const metadata parseRenderedNoteMetadata(result.html ? result.html : ); if (!metadata.printTitle) logger.info(Not printing title because joplin-metadata-print-title tag is set to false); if (metadata.printTitle item.title) noteContent.push(div classexported-note-title${escapeHtml(item.title)}/div); if (result.html) noteContent.push(result.html);其工作流程为将笔记的 Markdown 正文通过markupToHtml_.render(...)渲染为 HTML该调用同时支持注入插件的内容脚本见 InteropService_Exporter_Html.ts对渲染结果result.html调用parseRenderedNoteMetadata解析元数据若printTitle为true且笔记有标题则在导出 HTML 中插入div classexported-note-title标题/div若为false仅记录一条日志信息Not printing title because joplin-metadata-print-title tag is set to false标题 div 不会被插入。该导出器同样负责将插件的资源plugin assets复制到导出目录最终将标题 div 与笔记正文组装进完整的 HTML 文档InteropService_Exporter_Html.ts。测试用例验证该功能的解析逻辑有完整的单元测试覆盖见 packages/lib/services/interop/utils.test.ts。测试用例逐一验证了各种输入情况输入 HTML期望输出空字符串无标签{ printTitle: true }!-- joplin-metadata-print-title false --{ printTitle: false }!-- joplin-metadata-print-title true --{ printTitle: true }!-- joplin-metadata-print-title 0 --{ printTitle: false }!-- joplin-metadata-print-title 1 --{ printTitle: true }!-- joplin-metadata-print-title 0 --多空格{ printTitle: false }这些测试通过test.each参数化运行直接印证了前文所述的值解析规则也验证了空格宽容性。实际应用场景1. 插件生成自定义页眉文档当插件需要生成带特定自定义页头的文档时例如报告、合同、发票模板可在渲染结果中注入!-- joplin-metadata-print-title false --避免 Joplin 自动添加笔记标题从而保证文档的版式完全由插件控制。2. 通过 Markdown-it 内容脚本注入插件可以在笔记渲染过程中通过内容脚本在输出 HTML 中写入该注释。由于解析器作用于渲染后的 HTML内容脚本在渲染时注入的注释同样会被识别。3. Fountain 剧本场景的自动注入仓库中有一个现成的内置应用案例Fountain 剧本渲染插件在渲染剧本时自动注入该元数据标签。见 packages/renderer/MdToHtml/rules/fountain.tsreturn !-- joplin-metadata-print-title false -- div classfountain joplin-editable ... /div ;Fountain 剧本本身包含独立的标题页title page因此渲染器会在生成的 HTML 中自动带上joplin-metadata-print-title false确保导出或打印剧本时不会额外叠加 Joplin 笔记标题避免标题重复。这是一个元数据标签 渲染管线协同工作的典型范例。4. 静态 HTML 导出通过桌面端的导出为 HTML功能导出笔记时InteropService_Exporter_Html会读取渲染结果中的该标签。若笔记正文直接包含该注释导出的 HTML 中就不会出现div classexported-note-title实现标题的按需控制。注意事项大小写标签值true/false在解析时会先toLowerCase()处理因此FALSE、False等写法同样有效等号两侧空白等号前后必须有空白字符才能被正则捕获标准写法是标签位置该标签作为 HTML 注释写入笔记正文即可解析器会从渲染后的完整 HTML 中搜索第一个匹配的注释唯一合法属性除print-title外的任何属性名都会触发Unknown view metadata异常请勿自行发明其他标签名适用范围该元数据作用于渲染后的 HTML 版本主要影响打印与 HTML 导出流程不改变 Markdown 源文件内容。【免费下载链接】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），仅供参考 Rendered note metadata
Rendered note metadata【免费下载链接】joplinJoplin - the privacy-focused note taking app with sync capabilities for Windows, macOS, Linux, Android and iOS.项目地址: https://gitcode.com/GitHub_Trending/jo/joplinJoplin 允许在笔记渲染后的 HTML 版本中使用特定的元数据标签来控制输出行为。目前唯一支持的标签是print-title它用于控制笔记标题在打印或导出时是否显示。本文详细讲解该标签的语法、使用方法、底层实现原理及实际应用场景。什么是渲染笔记元数据Rendered Note MetadataJoplin 的笔记在编辑器中以 Markdown 形式存储但在渲染如打印、导出 HTML时会转换为 HTML 格式。渲染笔记元数据是嵌入在渲染后 HTML 中的特殊 HTML 注释标签用于向渲染器传递配置指令。其设计初衷是当需要控制渲染输出行为但又不希望这种控制在笔记源文件中占用可见空间或影响 Markdown 解析时可以通过 HTML 注释形式携带元数据。由于 HTML 注释在渲染过程中会保留在输出中见 桌面版 changelog 中 Keep comments when rendering Markdown to allow rendered note metadata 的改进记录因此可以被 Joplin 的渲染管线识别并解析。该功能首次引入于 桌面版 changelog 中记录的 Added support for rendered note metadata, in particular the joplin-metadata-print-title tag。print-title 标签控制笔记标题的打印与导出print-title是目前唯一受支持的渲染笔记元数据标签用于控制笔记标题是否在打印或导出的文档顶部显示。默认行为默认情况下当笔记被打印或导出时笔记的标题会显示在文档顶部。这一行为由RenderedNoteMetadata接口的printTitle字段控制默认值为true定义在 packages/lib/services/interop/utils.tsexport interface RenderedNoteMetadata { printTitle: boolean; }禁用标题打印在某些场景下默认的标题显示行为并非所愿。例如当插件需要生成带有自定义页眉的文档时笔记标题的自动添加会造成重复或布局冲突。此时可以在笔记中插入该标签并将其值设置为false来禁用默认行为。在文档中直接添加标签即在笔记的 Markdown 正文中包含以下一行!-- joplin-metadata-print-title false --该标签有两种添加途径直接在 Markdown 文档中写入如上所示适用于单个笔记的精细控制通过 Markdown-it 内容脚本content script在渲染时注入适用于插件需要动态控制或批量处理多个笔记的场景。取值规则标签的值遵循以下解析规则源码见 packages/lib/services/interop/utils.ts标签值解析结果printTitle说明falsefalse禁用标题打印truetrue启用标题打印0false数字 0 视为禁用1true数字 1 视为启用未出现标签true默认启用其核心解析逻辑为output.printTitle propValue.toLowerCase() true || propValue 1;即值字符串的小写形式等于true或值恰好为1时printTitle为true其余情况包括false、0以及任何其他值均为false。底层实现parseRenderedNoteMetadata 解析器渲染笔记元数据的解析由parseRenderedNoteMetadata函数完成位于 packages/lib/services/interop/utils.tsexport const parseRenderedNoteMetadata (noteHtml: string) { const output: RenderedNoteMetadata { printTitle: true, }; // !-- joplin-metadata-print-title false -- const match noteHtml.match(/!--[\s]joplin-metadata-(.*?)[\s][\s](.*?)[\s]--/); if (match) { const [, propName, propValue] match; if (propName print-title) { output.printTitle propValue.toLowerCase() true || propValue 1; } else { throw new Error(Unknown view metadata: ${propName}); } } return output; };正则解析规则解析器使用如下正则表达式匹配标签/!--[\s]joplin-metadata-(.*?)[\s][\s](.*?)[\s]--/从中可以推导出标签的严格语法要求前缀必须以!--开头后跟至少一个空白字符空格、制表符等然后是joplin-metadata-属性名joplin-metadata-后捕获属性名如print-title等号等号前后各需至少一个空白字符属性值等号后捕获属性值如false后缀以--结束且--前需至少一个空白字符。可见标签对空白字符是宽容的!-- joplin-metadata-print-title 0 --等号两侧多个空格同样可以正确解析。未知元数据的错误处理如果解析到非print-title的属性名解析器会抛出Unknown view metadata: ${propName}错误。这意味着标签名是白名单式的目前仅print-title一个合法属性名任何拼写错误或自定义的其他标签都会导致解析失败。从源码结构看该设计为未来新增其他渲染元数据标签预留了扩展点只需在if (propName ...)分支中增加新属性即可。HTML 导出器如何消费该元数据print-title元数据的实际消费方是 HTML 导出器InteropService_Exporter_Html位于 packages/lib/services/interop/InteropService_Exporter_Html.tsconst noteContent []; const metadata parseRenderedNoteMetadata(result.html ? result.html : ); if (!metadata.printTitle) logger.info(Not printing title because joplin-metadata-print-title tag is set to false); if (metadata.printTitle item.title) noteContent.push(div classexported-note-title${escapeHtml(item.title)}/div); if (result.html) noteContent.push(result.html);其工作流程为将笔记的 Markdown 正文通过markupToHtml_.render(...)渲染为 HTML该调用同时支持注入插件的内容脚本见 InteropService_Exporter_Html.ts对渲染结果result.html调用parseRenderedNoteMetadata解析元数据若printTitle为true且笔记有标题则在导出 HTML 中插入div classexported-note-title标题/div若为false仅记录一条日志信息Not printing title because joplin-metadata-print-title tag is set to false标题 div 不会被插入。该导出器同样负责将插件的资源plugin assets复制到导出目录最终将标题 div 与笔记正文组装进完整的 HTML 文档InteropService_Exporter_Html.ts。测试用例验证该功能的解析逻辑有完整的单元测试覆盖见 packages/lib/services/interop/utils.test.ts。测试用例逐一验证了各种输入情况输入 HTML期望输出空字符串无标签{ printTitle: true }!-- joplin-metadata-print-title false --{ printTitle: false }!-- joplin-metadata-print-title true --{ printTitle: true }!-- joplin-metadata-print-title 0 --{ printTitle: false }!-- joplin-metadata-print-title 1 --{ printTitle: true }!-- joplin-metadata-print-title 0 --多空格{ printTitle: false }这些测试通过test.each参数化运行直接印证了前文所述的值解析规则也验证了空格宽容性。实际应用场景1. 插件生成自定义页眉文档当插件需要生成带特定自定义页头的文档时例如报告、合同、发票模板可在渲染结果中注入!-- joplin-metadata-print-title false --避免 Joplin 自动添加笔记标题从而保证文档的版式完全由插件控制。2. 通过 Markdown-it 内容脚本注入插件可以在笔记渲染过程中通过内容脚本在输出 HTML 中写入该注释。由于解析器作用于渲染后的 HTML内容脚本在渲染时注入的注释同样会被识别。3. Fountain 剧本场景的自动注入仓库中有一个现成的内置应用案例Fountain 剧本渲染插件在渲染剧本时自动注入该元数据标签。见 packages/renderer/MdToHtml/rules/fountain.tsreturn !-- joplin-metadata-print-title false -- div classfountain joplin-editable ... /div ;Fountain 剧本本身包含独立的标题页title page因此渲染器会在生成的 HTML 中自动带上joplin-metadata-print-title false确保导出或打印剧本时不会额外叠加 Joplin 笔记标题避免标题重复。这是一个元数据标签 渲染管线协同工作的典型范例。4. 静态 HTML 导出通过桌面端的导出为 HTML功能导出笔记时InteropService_Exporter_Html会读取渲染结果中的该标签。若笔记正文直接包含该注释导出的 HTML 中就不会出现div classexported-note-title实现标题的按需控制。注意事项大小写标签值true/false在解析时会先toLowerCase()处理因此FALSE、False等写法同样有效等号两侧空白等号前后必须有空白字符才能被正则捕获标准写法是标签位置该标签作为 HTML 注释写入笔记正文即可解析器会从渲染后的完整 HTML 中搜索第一个匹配的注释唯一合法属性除print-title外的任何属性名都会触发Unknown view metadata异常请勿自行发明其他标签名适用范围该元数据作用于渲染后的 HTML 版本主要影响打印与 HTML 导出流程不改变 Markdown 源文件内容。【免费下载链接】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），仅供参考