WeKan 编辑器 Emoji 功能实战markdown-it-emoji 的 GitHub 表情短代码支持及其 Markdown 渲染集成【免费下载链接】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 仓库中 docs/Features/Editor/Emoji.md 整理成文。WeKan 从 v4.29 起把 Markdown 渲染引擎从 marked 换成 markdown-it并引入 markdown-it-emoji 插件使卡片标题、卡片描述等输入框直接支持 GitHub 全套表情短代码。读完本文你将掌握表情短代码的实际用法、其在源码中的渲染管线位置markdown-it 实例配置、插件注册、DOMPurify 净化以及按官方文档为 WeKan 添加其他 markdown-it 插件的完整开发流程与依赖更新方法。从 marked 到 markdown-it渲染引擎迁移背景Emoji 功能并非凭空出现它是 WeKan v4.29 Markdown 渲染引擎迁移的产物。官方文档明确记载Wekan v4.29 changes markdown rendering from marked to markdown-it.迁移到 markdown-it 之后WeKan 同时加入了 markdown-it-emoji 插件该插件支持GitHub 完整表情列表即 GitHub 上可用的全部 emoji 短代码集合。这也解释了为什么 WeKan 中表情写法与 GitHub Issue/PR 中一致直接写:表情名:。在当前仓库中这一依赖关系可以直接验证。package.json 的 dependencies 中同时声明了两个核心包markdown-it: ^15.0.0, markdown-it-emoji: ^3.0.0,见 package.json而实际承载渲染逻辑的 Meteor 包是wekan-markdown其 packages/markdown/package.js 声明了包名wekan-markdown、版本1.0.9并将src/template-integration.js注册为客户端集成文件。Emoji 短代码的实际用法使用方式极其简单在支持 Markdown 的输入框中直接写入带冒号包裹的表情短代码。官方文档给出的示例:rainbow: :thumbsup: :100:渲染后会显示对应的表情 。仓库中保留了这一示例的原始输入样本即 docs/Features/Editor/example-input.txt其核心内容正是:rainbow: :thumbsup: :100:可以在哪些位置使用表情短代码结合姊妹文档 docs/Features/Editor/Markdown/Markdown.md该文档开头即注明 “Wekan now uses markdown-it and markdown-it-emoji plugin”并指回 Emoji 页WeKan 支持 Markdown 渲染的位置包括卡片名称Card name看板名称Board name仅在看板视图中生效卡片描述、列表标题、任务清单Card description, list and task list由于表情短代码走的是同一套 markdown-it 渲染管线凡上述位置可写**加粗**、链接之处均可直接写:rainbow:等短代码。源码级实现表情插件如何接入渲染管线WeKan 的 Markdown 渲染集中在 packages/markdown/src/template-integration.js 中这是理解 Emoji 功能以及所有 Markdown 能力的入口文件。1. MarkdownIt 实例配置const Markdown new MarkdownIt({ html: true, linkify: true, typographer: true, breaks: true, });template-integration.js四个配置项含义分别是允许内联 HTML、自动识别裸链接、开启排版美化如智能引号、单个换行转为br。其中breaks: true对看板卡片尤其重要——用户在卡片描述里按一次回车就能换行符合看板工具的使用习惯。2. 表情插件注册const emojiPlugin markdownItEmoji.full || markdownItEmoji.default || markdownItEmoji; if (emojiPlugin) { Markdown.use(emojiPlugin); }template-integration.js这里取的是markdown-it-emoji的full数据集合即前文所说的“GitHub 全套表情列表”。代码兼容了 CJS/ESM 两种模块形态full || default || 模块本身保证在不同打包环境下都能取到插件函数随后用Markdown.use()挂到实例上。注册后markdown-it 在解析阶段就会把:short_code:形式的文本转换为表情输出。3. 渲染管线与安全防护表情短代码转换后输出并不会直接进页面。整个渲染由 Blaze 模板助手markdown完成template-integration.js其管线大致为原始源码直显分支当管理员设置alwaysShowCodeAsText为 true或文本中检测到隐藏链接[]时跳过 Markdown 渲染整段源码经 HTML 转义后以pre形式原样展示红底警告防止隐藏链接、HTML 注释、脚本等被“藏”在渲染结果里正常渲染分支先做外部 Issue 前缀自动链接autolinkExternalIssueReferences与 WeKan 卡片 URL 自动链接autolinkWekanCardUrls再调用Markdown.render()完成 Markdown含表情短代码到 HTML 的转换DOMPurify 净化渲染结果经DOMPurify.sanitize(renderedMarkdown, getSecureDOMPurifyConfig())过滤安全配置见 packages/markdown/src/secureDOMPurify.js后才通过HTML.Raw()注入页面失败兜底任何渲染异常都会被捕获内容降级为转义后的纯文本pre展示保证“任何一张卡片都不会因为内容问题而打不开”源码注释中特别引用了 #6588 的 linkify 崩溃教训。这意味着 Emoji 功能的边界很清晰markdown-it-emoji只负责短代码到表情 HTML 的转换最终能否呈现仍受 DOMPurify 白名单约束。如何为 WeKan 添加另一个 markdown-it 插件Emoji 文档的主体是一份可复现的插件扩展开发指南以最新 Ubuntu amd64 为例分 Meteor 2 与 Meteor 3 两条路线。以下按原文档步骤完整保留并对照当前仓库状态加以注释。Meteor 2 路线1. 安装并配置 gitsudo apt -y install git git config --global user.name Yourfirstname Yourlastname git config --global user.email email-address-you-use-at-githubexample.com git config --global push.default simple nano .ssh/config在.ssh/config中加入你的 GitHub 用户名User和 SSH 私钥路径IdentityFile是私钥不是.pub公钥缩进使用一个 TabHost * IdentitiesOnlyyes Host github.com Hostname github.com User xet7 IdentityFile ~/.ssh/id_xet7ed按 Ctrl-o Enter Ctrl-x Enter 保存退出。若还没有 SSH 密钥运行ssh-keygen并连续按约 3 次回车直到生成私钥~/.ssh/id_rsa与公钥~/.ssh/id_rsa.pub再把公钥.pub添加到 GitHub 账户的 Web 界面。把 Meteor 加入 PATH编辑~/.bashrc在文件末尾添加export PATH~/.meteor:$PATH2. Fork 并克隆仓库先在 GitHub Web 页面 forkwekan/wekan然后mkdir repos cd repos git clone gitgithub.com:YourGithubUsername/wekan.git cd wekan3. 运行构建菜单build.sh会显示两级菜单1) Setup 2) Dev server 3) Tests 4) Docker 5) Tools 6) Quit先选类别号再选类别内项目号# Setup - Install dependencies ./build.sh 1 # Setup 1 # Install dependencies # Setup - Build WeKan ./build.sh 1 # Setup 2 # Build WeKan # Dev server - localhost:3000 ./build.sh 2 # Dev server 1 # localhost:3000这三步分别对应安装依赖、构建 WeKan、以开发模式启动底层使用meteor命令能侦测文件变化自动重编译并刷新浏览器。注意偶尔仍需 Ctrl-c 停止后重新执行Setup - Build WeKan做一次完整构建若目标端口已有 dev server 在运行Dev server 选项会先停掉旧实例再在同一端口启动新实例。随后到 http://localhost:3000 注册并登录注册流程参见 docs/Features/Login/Adding-users.md。4.可选通常无需添加新插件包meteor npm install markdown-it-something --save原文档提示编辑wekan/packages/markdown/src-integration.js按新插件页面的示例代码接入或参考 emoji 插件的接法。对照当前仓库需要注意该文件现在的实际路径是 packages/markdown/src/template-integration.js接入点就是在文件顶部 import 新包后Markdown.use(新插件, 配置)——emoji 插件正是这么加的。5. 测试验证新插件语法是否生效例如在卡片标题、卡片描述等其他输入字段中试验。6. 提交并创建 Pull Request如果普通 Markdown、emoji、新插件语法都工作正常提交变更git add --all git commit -m Added plugin markdown-it-something. git push然后在你的 fork 仓库页面点击 “Create pull request”。参考对照源码中其实已经留有一个“想接入但被禁用”的插件实例——Mermaid。template-integration.js 处markdownItMermaid的 import 与Markdown.use(markdownItMermaid, { maxTextSize: 200000 })调用均被注释掉注释说明了为规避 “Maximum call stack size exceeded” 而放大maxTextSize的缘由对应的功能文档见 docs/Features/Editor/Mermaid-Diagram.md。这说明上述“添加插件”流程正是仓库内真实走过的路径也解释了为什么当前版本中 Mermaid 语法默认不渲染。Meteor 3 路线原文档以 2024-06-26 为参考时点指出当时 Node.js LTS 为 20.15.0建议切换到最新 Node.js LTS 并删除旧 Meteorsudo n 20.15.0 sudo npm -g install npm cd rm -rf .meteor安装 Meteor 3 的方式参考 Meteor 官方 PR示例命令npx meteorrc查看分支并切换到 Meteor 3 分支cd repos/wekan git branch -a git checkout feature-meteor3构建 WeKan./build.sh 2如有报错逐一修复也可以尝试直接运行./build.sh 3依赖与版本更新插件引入后日常维护需要同时关注 npm 包与 Meteor 两条线。更新 npm 包并处理安全漏洞npm update npm audit npm audit fix若npm audit fix无效可加 force 强制升级可能引入破坏性变更需回归验证npm audit fix --force仍不解决时按npm audit输出的链接移除弃用依赖、换成维护中的替代包。更新 Meteor# 更新到下一个 Meteor 发布 meteor update # 更新到指定 Meteor 发布 meteor update --release METEOR3.0-rc.4 # 尝试更新全部 Meteor 包 meteor update --release METEOR3.0-rc.4 --all-packages # 允许不兼容更新可能可用 meteor update --release METEOR3.0-rc.4 --all-packages --allow-incompatible-update如果同时变更了 Meteor 与 Node.js 版本可能需要重置 Meteormeteor reset或者干脆删除 wekan 仓库前提是本地改动不再需要重新克隆后再走构建流程。小结WeKan 的 Emoji 功能本质是一次渲染引擎升级的附带能力v4.29 用 markdown-it 替换 marked 后通过Markdown.use(markdownItEmoji.full)一行接入即获得 GitHub 全套表情短代码支持package.json 中的markdown-it-emoji: ^3.0.0即此依赖。其渲染结果统一经过隐藏链接检测与 DOMPurify 净化后才输出到页面失败时降级为纯文本保证了卡片永远可打开。而对贡献者而言docs/Features/Editor/Emoji.md 更是一份完整的 markdown-it 插件扩展开发手册——从 git/SSH 环境准备、fork 克隆、build.sh构建菜单、开发服务器验证到提 PR 与 npm/Meteor 双轨版本更新均给出了可直接照做的命令序列可作为向 WeKan 编辑器添加新 Markdown 语法如表格增强、图表渲染等的标准操作依据。【免费下载链接】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），仅供参考 WeKan 编辑器 Emoji 功能实战：markdown-it-emoji 的 GitHub 表情短代码支持及其 Markdown 渲染集成
WeKan 编辑器 Emoji 功能实战markdown-it-emoji 的 GitHub 表情短代码支持及其 Markdown 渲染集成【免费下载链接】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 仓库中 docs/Features/Editor/Emoji.md 整理成文。WeKan 从 v4.29 起把 Markdown 渲染引擎从 marked 换成 markdown-it并引入 markdown-it-emoji 插件使卡片标题、卡片描述等输入框直接支持 GitHub 全套表情短代码。读完本文你将掌握表情短代码的实际用法、其在源码中的渲染管线位置markdown-it 实例配置、插件注册、DOMPurify 净化以及按官方文档为 WeKan 添加其他 markdown-it 插件的完整开发流程与依赖更新方法。从 marked 到 markdown-it渲染引擎迁移背景Emoji 功能并非凭空出现它是 WeKan v4.29 Markdown 渲染引擎迁移的产物。官方文档明确记载Wekan v4.29 changes markdown rendering from marked to markdown-it.迁移到 markdown-it 之后WeKan 同时加入了 markdown-it-emoji 插件该插件支持GitHub 完整表情列表即 GitHub 上可用的全部 emoji 短代码集合。这也解释了为什么 WeKan 中表情写法与 GitHub Issue/PR 中一致直接写:表情名:。在当前仓库中这一依赖关系可以直接验证。package.json 的 dependencies 中同时声明了两个核心包markdown-it: ^15.0.0, markdown-it-emoji: ^3.0.0,见 package.json而实际承载渲染逻辑的 Meteor 包是wekan-markdown其 packages/markdown/package.js 声明了包名wekan-markdown、版本1.0.9并将src/template-integration.js注册为客户端集成文件。Emoji 短代码的实际用法使用方式极其简单在支持 Markdown 的输入框中直接写入带冒号包裹的表情短代码。官方文档给出的示例:rainbow: :thumbsup: :100:渲染后会显示对应的表情 。仓库中保留了这一示例的原始输入样本即 docs/Features/Editor/example-input.txt其核心内容正是:rainbow: :thumbsup: :100:可以在哪些位置使用表情短代码结合姊妹文档 docs/Features/Editor/Markdown/Markdown.md该文档开头即注明 “Wekan now uses markdown-it and markdown-it-emoji plugin”并指回 Emoji 页WeKan 支持 Markdown 渲染的位置包括卡片名称Card name看板名称Board name仅在看板视图中生效卡片描述、列表标题、任务清单Card description, list and task list由于表情短代码走的是同一套 markdown-it 渲染管线凡上述位置可写**加粗**、链接之处均可直接写:rainbow:等短代码。源码级实现表情插件如何接入渲染管线WeKan 的 Markdown 渲染集中在 packages/markdown/src/template-integration.js 中这是理解 Emoji 功能以及所有 Markdown 能力的入口文件。1. MarkdownIt 实例配置const Markdown new MarkdownIt({ html: true, linkify: true, typographer: true, breaks: true, });template-integration.js四个配置项含义分别是允许内联 HTML、自动识别裸链接、开启排版美化如智能引号、单个换行转为br。其中breaks: true对看板卡片尤其重要——用户在卡片描述里按一次回车就能换行符合看板工具的使用习惯。2. 表情插件注册const emojiPlugin markdownItEmoji.full || markdownItEmoji.default || markdownItEmoji; if (emojiPlugin) { Markdown.use(emojiPlugin); }template-integration.js这里取的是markdown-it-emoji的full数据集合即前文所说的“GitHub 全套表情列表”。代码兼容了 CJS/ESM 两种模块形态full || default || 模块本身保证在不同打包环境下都能取到插件函数随后用Markdown.use()挂到实例上。注册后markdown-it 在解析阶段就会把:short_code:形式的文本转换为表情输出。3. 渲染管线与安全防护表情短代码转换后输出并不会直接进页面。整个渲染由 Blaze 模板助手markdown完成template-integration.js其管线大致为原始源码直显分支当管理员设置alwaysShowCodeAsText为 true或文本中检测到隐藏链接[]时跳过 Markdown 渲染整段源码经 HTML 转义后以pre形式原样展示红底警告防止隐藏链接、HTML 注释、脚本等被“藏”在渲染结果里正常渲染分支先做外部 Issue 前缀自动链接autolinkExternalIssueReferences与 WeKan 卡片 URL 自动链接autolinkWekanCardUrls再调用Markdown.render()完成 Markdown含表情短代码到 HTML 的转换DOMPurify 净化渲染结果经DOMPurify.sanitize(renderedMarkdown, getSecureDOMPurifyConfig())过滤安全配置见 packages/markdown/src/secureDOMPurify.js后才通过HTML.Raw()注入页面失败兜底任何渲染异常都会被捕获内容降级为转义后的纯文本pre展示保证“任何一张卡片都不会因为内容问题而打不开”源码注释中特别引用了 #6588 的 linkify 崩溃教训。这意味着 Emoji 功能的边界很清晰markdown-it-emoji只负责短代码到表情 HTML 的转换最终能否呈现仍受 DOMPurify 白名单约束。如何为 WeKan 添加另一个 markdown-it 插件Emoji 文档的主体是一份可复现的插件扩展开发指南以最新 Ubuntu amd64 为例分 Meteor 2 与 Meteor 3 两条路线。以下按原文档步骤完整保留并对照当前仓库状态加以注释。Meteor 2 路线1. 安装并配置 gitsudo apt -y install git git config --global user.name Yourfirstname Yourlastname git config --global user.email email-address-you-use-at-githubexample.com git config --global push.default simple nano .ssh/config在.ssh/config中加入你的 GitHub 用户名User和 SSH 私钥路径IdentityFile是私钥不是.pub公钥缩进使用一个 TabHost * IdentitiesOnlyyes Host github.com Hostname github.com User xet7 IdentityFile ~/.ssh/id_xet7ed按 Ctrl-o Enter Ctrl-x Enter 保存退出。若还没有 SSH 密钥运行ssh-keygen并连续按约 3 次回车直到生成私钥~/.ssh/id_rsa与公钥~/.ssh/id_rsa.pub再把公钥.pub添加到 GitHub 账户的 Web 界面。把 Meteor 加入 PATH编辑~/.bashrc在文件末尾添加export PATH~/.meteor:$PATH2. Fork 并克隆仓库先在 GitHub Web 页面 forkwekan/wekan然后mkdir repos cd repos git clone gitgithub.com:YourGithubUsername/wekan.git cd wekan3. 运行构建菜单build.sh会显示两级菜单1) Setup 2) Dev server 3) Tests 4) Docker 5) Tools 6) Quit先选类别号再选类别内项目号# Setup - Install dependencies ./build.sh 1 # Setup 1 # Install dependencies # Setup - Build WeKan ./build.sh 1 # Setup 2 # Build WeKan # Dev server - localhost:3000 ./build.sh 2 # Dev server 1 # localhost:3000这三步分别对应安装依赖、构建 WeKan、以开发模式启动底层使用meteor命令能侦测文件变化自动重编译并刷新浏览器。注意偶尔仍需 Ctrl-c 停止后重新执行Setup - Build WeKan做一次完整构建若目标端口已有 dev server 在运行Dev server 选项会先停掉旧实例再在同一端口启动新实例。随后到 http://localhost:3000 注册并登录注册流程参见 docs/Features/Login/Adding-users.md。4.可选通常无需添加新插件包meteor npm install markdown-it-something --save原文档提示编辑wekan/packages/markdown/src-integration.js按新插件页面的示例代码接入或参考 emoji 插件的接法。对照当前仓库需要注意该文件现在的实际路径是 packages/markdown/src/template-integration.js接入点就是在文件顶部 import 新包后Markdown.use(新插件, 配置)——emoji 插件正是这么加的。5. 测试验证新插件语法是否生效例如在卡片标题、卡片描述等其他输入字段中试验。6. 提交并创建 Pull Request如果普通 Markdown、emoji、新插件语法都工作正常提交变更git add --all git commit -m Added plugin markdown-it-something. git push然后在你的 fork 仓库页面点击 “Create pull request”。参考对照源码中其实已经留有一个“想接入但被禁用”的插件实例——Mermaid。template-integration.js 处markdownItMermaid的 import 与Markdown.use(markdownItMermaid, { maxTextSize: 200000 })调用均被注释掉注释说明了为规避 “Maximum call stack size exceeded” 而放大maxTextSize的缘由对应的功能文档见 docs/Features/Editor/Mermaid-Diagram.md。这说明上述“添加插件”流程正是仓库内真实走过的路径也解释了为什么当前版本中 Mermaid 语法默认不渲染。Meteor 3 路线原文档以 2024-06-26 为参考时点指出当时 Node.js LTS 为 20.15.0建议切换到最新 Node.js LTS 并删除旧 Meteorsudo n 20.15.0 sudo npm -g install npm cd rm -rf .meteor安装 Meteor 3 的方式参考 Meteor 官方 PR示例命令npx meteorrc查看分支并切换到 Meteor 3 分支cd repos/wekan git branch -a git checkout feature-meteor3构建 WeKan./build.sh 2如有报错逐一修复也可以尝试直接运行./build.sh 3依赖与版本更新插件引入后日常维护需要同时关注 npm 包与 Meteor 两条线。更新 npm 包并处理安全漏洞npm update npm audit npm audit fix若npm audit fix无效可加 force 强制升级可能引入破坏性变更需回归验证npm audit fix --force仍不解决时按npm audit输出的链接移除弃用依赖、换成维护中的替代包。更新 Meteor# 更新到下一个 Meteor 发布 meteor update # 更新到指定 Meteor 发布 meteor update --release METEOR3.0-rc.4 # 尝试更新全部 Meteor 包 meteor update --release METEOR3.0-rc.4 --all-packages # 允许不兼容更新可能可用 meteor update --release METEOR3.0-rc.4 --all-packages --allow-incompatible-update如果同时变更了 Meteor 与 Node.js 版本可能需要重置 Meteormeteor reset或者干脆删除 wekan 仓库前提是本地改动不再需要重新克隆后再走构建流程。小结WeKan 的 Emoji 功能本质是一次渲染引擎升级的附带能力v4.29 用 markdown-it 替换 marked 后通过Markdown.use(markdownItEmoji.full)一行接入即获得 GitHub 全套表情短代码支持package.json 中的markdown-it-emoji: ^3.0.0即此依赖。其渲染结果统一经过隐藏链接检测与 DOMPurify 净化后才输出到页面失败时降级为纯文本保证了卡片永远可打开。而对贡献者而言docs/Features/Editor/Emoji.md 更是一份完整的 markdown-it 插件扩展开发手册——从 git/SSH 环境准备、fork 克隆、build.sh构建菜单、开发服务器验证到提 PR 与 npm/Meteor 双轨版本更新均给出了可直接照做的命令序列可作为向 WeKan 编辑器添加新 Markdown 语法如表格增强、图表渲染等的标准操作依据。【免费下载链接】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），仅供参考