WeKan Markdown 编辑器：有序列表自动编号与 `3\.` 转义点号的正确写法

WeKan Markdown 编辑器有序列表自动编号与3\.转义点号的正确写法【免费下载链接】wekanThe Open Source kanban, built with Meteor. GitHub issues/PRs are only for FLOSS Developers, not for support, support is at https://wekan.fi/commercial-support/ . PR source translation to imports/i18n/data/en.i18n.json, other translations at https://app.transifex.com/wekan/wekan项目地址: https://gitcode.com/GitHub_Trending/we/wekan本文以 WeKan 文档 Numbered-text.md 为主体讲清 WeKan 输入字段中 Markdown 有序列表的自动编号机制为什么写1. / 1. / 1.会渲染成1. / 2. / 3.以及当你在列表标题中想原样显示3. Something时必须写成3\. Something的原因与原理并给出 WeKan 前端 Markdown 渲染管线的源码级佐证解析器配置、Blaze helper、DOMPurify 白名单读完后可直接在 WeKan 的卡片描述、评论、列表标题等字段中正确书写带编号文本。1. 文档原始结论数字点号会被自动编号转义才能原样显示Numbered-text.md 给出的核心规则只有一条如果你在列表标题List titles中想创建这样的编号文本3. Something 必须这样写转义点号才能正确显示3\. Something原因是输入字段支持 Markdown 的自动编号autonumbering。也就是说在 WeKan 的输入字段里3. Something这种数字 点号 空格 文本的写法会被 Markdown 解析器识别为有序列表项而不是普通文本。如果希望它按字面显示例如3.只是一个编号标签、版本号、步骤标记而非列表序号需要用反斜杠转义点号3\. Something渲染结果即为字面的3. Something不会变成列表。2. 自动编号行为源数字只是标记渲染时按顺序重排文档随后用两组示例说明自动编号的具体表现。这是 CommonMark/Markdown 规范中有序列表的标准行为源文本中写的数字只决定这是一条有序列表项渲染时浏览器按条目顺序连续编号。示例一三行全部写1.1. Something nice 1. Something cool 1. Something great实际显示为1. Something nice 2. Something cool 3. Something great示例二重新剪贴/调换行顺序后仍然全部写1.1. Something great 1. Something nice 1. Something cool显示自动重排为1. Something great 2. Something nice 3. Something cool这意味着在 WeKan 中维护编号清单时无需手工维护序号插入、删除、拖拽、剪贴重排条目后显示编号始终正确。文档原话总结为你可以自由地剪切/粘贴重排列表而不必手动重排数字so you can cut/paste reorder list freely, without manually reordering numbers。3. 源码佐证WeKan 的 Markdown 渲染管线自动编号并非 WeKan 的自定义逻辑而是其 Markdown 解析器的固有行为。从源码结构看整条管线如下3.1 解析器实例MarkdownIt 及其配置WeKan 的 Markdown 能力封装在 Meteor 包packages/markdown中解析器实例在 template-integration.js 中创建const Markdown new MarkdownIt({ html: true, linkify: true, typographer: true, breaks: true, });有序列表、自动编号、反斜杠转义3\.中\.不被当作列表定界符都属于 MarkdownIt 遵循的 CommonMark 规则开箱即用无需 WeKan 额外代码breaks: true使单个换行渲染为br因此列表标题这类短文本字段中的列表排版与书写行一一对应需要说明的是packages/markdown/README.md 仍写着基于 marked.js 的 GFM 解析器而当前src/下的实际实现已切换为markdown-it并叠加了 emoji、数学公式、GFM 任务列表等扩展以源码为准。3.2 渲染入口{{#markdown}}Blaze helper同一文件 template-integration.js 注册了名为markdown的 Blaze 模板Blaze.Template.registerHelper(markdown, ...)。任何 Jade/Blaze 模板都可以这样使用见 packages/markdown/README.md 中的用法示例{{#markdown}} ...markdown text here... {{/markdown}}WeKan 的前端模板实际调用点例如 editor.jade 中的viewer模板template(nameviewer) .viewer(dirauto) mentions markdown {{ UI.contentBlock }}markdownhelper 的执行流程template-integration.js若管理员面板开启了 always show code as plain textMarkdown.alwaysShowCodeAsText或文本中含有隐藏的 Markdown 链接[]空链接描述则整段源码转义为pre纯文本显示不做任何 Markdown 渲染——这是一种安全防隐形内容策略否则依次执行外部 issue 自动链接autolinkExternalIssueReferences、WeKan 卡片 URL 自动链接autolinkWekanCardUrls、Markdown.render(text)生成 HTML生成的 HTML 必须通过 DOMPurify 消毒后才注入页面DOMPurify.sanitize(renderedMarkdown, getSecureDOMPurifyConfig())渲染抛错时降级为转义纯文本保证卡片可打开。3.3 为什么有序列表能通过安全过滤ol/li之所以能出现在最终页面上是因为 secureDOMPurify.js 的白名单显式放行了列表元素ALLOWED_TAGS: [a, p, br, strong, em, u, s, del, strike, h1, h2, h3, h4, h5, h6, ul, ol, li, blockquote, pre, code, img, table, thead, tbody, tr, th, td, hr, div, span, input, ...MATHML_TAGS],同时FORBID_ATTR封禁了style、class、id和所有on*事件属性secureDOMPurify.jsFORBID_TAGS封禁script、svg、iframe等危险标签。因此 Markdown 有序列表在 WeKan 中是白名单内的安全 HTML可以放心用于编号文本而不会被过滤丢失。4. 实战写法对照表结合文档示例与上述机制在 WeKan 的列表标题、卡片描述、评论等支持 Markdown 渲染的字段中目的写法渲染效果多行编号清单推荐序号可乱写1. A/1. B/1. C1. A2. B3. C单行字面编号不让它变列表3\. Something3. Something字面编号后接说明3\. 阶段三验收3. 阶段三验收剪贴重排后保持各行1.即可自动按当前行序重排 1/2/3要点归纳要真正的列表就全写1.——这是文档推荐的工作流序号交给渲染器编辑者只关心行序要字面编号就转义点号——3\.中的反斜杠使点号不再是列表定界符Markdown 将其渲染为普通字符该转义技巧依赖 CommonMark 的转义语法同样适用于行首*、-等无序列表定界符写法同构- 字面内容写为\- 字面内容但本文档明确给出的场景是数字 点号此处仅按文档范围陈述有序列表情形。5. 适用边界与限制适用范围该行为取决于字段是否经过markdownBlaze helper 渲染。凡走 editor.jade 这类 viewer/editor 模板的富文本字段均适用直接以纯文本插值如 title输出的界面位置不经过 Markdown 管线行为以对应模板为准。管理员安全开关的影响若管理员在 Admin Panel / Features 中开启 show all code as plain textMarkdown.alwaysShowCodeAsText所有 Markdown包括有序列表编号都会降级为原始纯文本显示此时看不到自动编号效果。不改变存储内容自动编号只发生在渲染阶段数据库中保存的仍是原始 Markdown 源码例如三行1.因此任何客户端看到的编号一致导出/同步也不会产生序号漂移。6. 相关文件索引内容路径本篇对应的功能文档docs/Features/Editor/Numbered-text.mdMarkdownIt 实例与markdownhelper 注册packages/markdown/src/template-integration.js渲染入口与降级/安全分支packages/markdown/src/template-integration.jsDOMPurify 白名单ol/li放行packages/markdown/src/secureDOMPurify.js包用法说明{{#markdown}}packages/markdown/README.md前端 viewer 模板调用点client/components/main/editor.jade同目录相关编辑器文档Multiline.md、LaTeX.md、Emoji.md【免费下载链接】wekanThe Open Source kanban, built with Meteor. GitHub issues/PRs are only for FLOSS Developers, not for support, support is at https://wekan.fi/commercial-support/ . PR source translation to imports/i18n/data/en.i18n.json, other translations at https://app.transifex.com/wekan/wekan项目地址: https://gitcode.com/GitHub_Trending/we/wekan创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考