尧图网页设计 
后端前端云原生【免费下载链接】hedgedocHedgeDoc - Ideas grow better together项目地址https://gitcode.com/gh_mirrors/he/hedgedoc点击查看免费下载本指南以 HedgeDoc 2.0 官方 FAQdocs/content/faq/index.md为骨架逐条解读社区最常问的六类问题公式引擎为何从 MathJax 换成 KaTeX、sequence代码块为何被弃用、标题标签与逗号分隔 tags 为何不再支持、渲染器为何建议独立域名部署、forkawesome 图标为何被替换。文中不仅给出迁移前后的完整写法还结合仓库前端扩展App Extension与后端配置源码讲清每一项变更背后的实现原理与验证方式读完即可在你的笔记中完成平滑迁移。一、为什么 HedgeDoc 2.0 从 MathJax 切换到 KaTeXHedgeDoc 2.0 重构了 React 前端其中一个重要的渲染内核变更是数学公式的渲染引擎从 MathJax 2 切换为 KaTeX。官方 FAQ 给出了三个原因KaTeX 渲染速度快得多相比 MathJax 的完整排版流程KaTeX 采用预生成的字体与更轻量的解析管线显著降低公式渲染耗时这对实时协作编辑场景尤为关键。MathJax 的 React 组件无人维护旧方案依赖的react-mathjax组件已停止维护且不支持 MathJax 3继续沿用存在兼容性风险。KaTeX 覆盖面足够KaTeX 支持日常数学表达所需的全部命令足以满足 Markdown 笔记中的公式需求。源码层面的实现佐证公式渲染能力在前端以扩展App Extension形式注入。KatexAppExtension负责将 KaTeX 注册进 Markdown 渲染管线katex-app-extension.ts构建KatexMarkdownExtension渲染扩展同时向编辑器「速查表Cheatsheet」注册katex条目方便用户在编辑器中查询公式语法。katex-markdown-extension.ts通过markdown-it-mathjax插件解析 LaTeX 语法把行内公式inline math与独立公式display math包装为app-katex标签再由KatexReplacer组件在渲染端替换为 KaTeX 输出的 HTML。换句话说编辑器中的公式书写方式没有变化仍然是$...$或$$...$$变化的只是后端排版引擎。如果你在迁移到 2.0 后发现公式渲染样式略有不同这是引擎差异的正常表现语法本身无需改动。二、为什么sequence代码块语言被弃用如何迁移HedgeDoc 2.0 开始统一使用 Mermaid 渲染时序图sequence diagram。FAQ 明确说明时序图的语法本身没有变化只是代码块的标记语言需要从sequence改为mermaid并在图表内容之前插入一行sequenceDiagram。弃用写法HedgeDoc 1.xAlice-John: Hello John, how are you? John--Alice: Great!新写法HedgeDoc 2.0源码层面的实现佐证弃用不是一句口号而是由前端扩展与编辑器 Linter 双重落实的legacy-sequence-diagram-app-extension.ts 保留了旧语法兼容同时注册了一个SingleLineRegexLinter用正则/sequence/匹配旧的代码围栏在编辑器中直接弹出弃用警告并给出替换建议mermaid\nsequenceDiagram。mermaid-app-extension.ts 注册了 markdowntags:tag1,tag2从 HedgeDoc 2.0 起**标题中的标签声明不再被支持**。官方 FAQ 的建议是改用 frontmatter 元数据来指定标签。frontmatter 是笔记正文开头的 YAML 块HedgeDoc 的 frontmatter 解析实现在 [commons/src/note-frontmatter](https://link.gitcode.com/i/4a571d8fefb17955a40db1a727cb71d4) 目录下其中 [parse-tags-field.ts](https://link.gitcode.com/i/6183386423e5ddd191519530265a2474) 专门负责解析 tags 字段。正确写法如下 yaml --- title: 我的笔记 tags: - tag1 - tag2 ---标题中的tags:只是普通文本不会影响笔记的标签索引、搜索与权限管理务必迁移到 frontmatter 中。四、为什么 YAML 元数据中逗号分隔的 tags 定义被弃用除了标题标签YAML 元数据里的逗号分隔写法同样被弃用。原因很直接YAML 规范本身已为列表提供了标准定义项目方没有必要再维护一套自定义的逗号分隔语法。弃用写法tags: tag1, tag2新写法YAML 列表tags: - tag1 - tag2或使用 YAML 行内数组tags: [tag1, tag2]源码层面的实现佐证有趣的是虽然官方文档已声明逗号分隔写法弃用但解析器仍保留了向后兼容parseTagsField在遇到字符串输入时仍会按逗号切分、逐项去除首尾空白并丢弃空标签遇到数组输入时则逐项转为字符串并 trim。这说明旧笔记即使暂时未迁移也不会立即失效但新笔记应统一使用 YAML 标准列表写法避免将来解析器移除兼容逻辑后出现意外。五、为什么建议把渲染器Renderer部署到独立的子域名HedgeDoc 的架构中编辑器Editor与渲染器Renderer可以分离部署。FAQ 指出当渲染器由另一个域名提供时攻击者更难通过渲染后的笔记内容操纵 HedgeDoc 或窃取凭证因为渲染器与编辑器之间隔离更彻底。这能显著提升软件安全性大幅缓解跨站脚本攻击XSS风险。当然你可以不启用这层额外防护直接运行但官方推荐在条件允许时启用。如何配置HD_RENDERER_BASE_URL渲染器域名通过环境变量HD_RENDERER_BASE_URL配置。配置参考文档 docs/content/references/config/general.md 给出的定义是环境变量默认值说明HD_RENDERER_BASE_URLHD_BASE_URL的内容渲染器运行的 URL省略时与HD_BASE_URL相同后端在 backend/src/config/app.config.ts 中对该变量做校验解析rendererBaseUrl: process.env.HD_RENDERER_BASE_URL。前端侧frontend/src/utils/base-url-from-env-extractor.ts 在启动时读取环境变量并缓存 base URLHD_RENDERER_BASE_URL未设置时自动回退到HD_BASE_URL即编辑器的地址这也与配置表中「默认值为 HD_BASE_URL 的内容」一致。单元测试 base-url-from-env-extractor.spec.ts 覆盖了合法 URL、非法 URL、未设置等分支。参考示例与 frontend/package.json 中start:dev:mock脚本的用法一致HD_BASE_URLhttps://hedgedoc.example.org/ HD_RENDERER_BASE_URLhttps://renderer.example.org/重要提醒反向代理同步调整!!! note 启用独立域名后你的反向代理配置需要同步调整把指向该域名如renderer.example.org的请求转发到前端服务。否则渲染器域名将无法访问页面渲染会失败。反向代理的整体配置方法参见 docs/content/how-to/reverse-proxy.md。六、为什么 forkawesome 图标被弃用如何替换forkawesome 图标集维护不够活跃HedgeDoc 2.0 决定用 Bootstrap Icons 替代它。为了保持与 HedgeDoc 1.x 笔记的兼容性项目仍会暂时导入旧图标但未来很可能移除。官方 FAQ 的建议很明确最佳行动是尽快把旧图标替换为 Bootstrap Icons。源码层面的实现佐证旧图标的提示同样由编辑器 Linter 落实。在 fork-awesome-html-tag-app-extension.ts 中正则/i class[][\w\s]*fa-[\w-][\w\s-]*[][^]*\/?(?:\/i)?/用于匹配形如i classfa fa-xxx的旧图标 HTML 标签一旦命中就在编辑器中显示弃用提示并引导用户查阅本文对应的 FAQ 说明。因此当你编辑旧笔记时编辑器会自动标出需要替换的图标标签。替换示例!-- 弃用写法 -- i classfa fa-github/i !-- 新写法Bootstrap Icons -- i classbi bi-github/i迁移清单小结对照本指南为 HedgeDoc 2.0 笔记做一次体检公式$...$/$$...$$语法不变渲染引擎已自动切换为 KaTeX时序图sequence改为mermaid并首行加sequenceDiagram标签删除标题中的tags:改用 frontmatter 的 YAML 列表或行内数组安全部署如条件允许为渲染器配置独立域名HD_RENDERER_BASE_URL并同步调整反向代理图标把i classfa fa-...替换为i classbi bi-...。以上每一项都在当前仓库中有对应的源码与测试可查证前端扩展目录 frontend/src/extensions/external-lib-app-extensions 存放 KaTeX、Mermaid 等渲染扩展frontend/src/extensions/essential-app-extensions 存放 fork-awesome 兼容与提示逻辑frontmatter 解析位于 commons/src/note-frontmatterURL 解析与配置校验分别见 frontend/src/utils/base-url-from-env-extractor.ts 与 backend/src/config/app.config.ts。如果仍有疑问可以前往社区论坛或 Matrix 聊天室继续提问见 docs/content/faq/index.md 开头说明。赞分享后端前端云原生【免费下载链接】hedgedocHedgeDoc - Ideas grow better together项目地址https://gitcode.com/gh_mirrors/he/hedgedoc点击查看免费下载相关推荐Mermaid 数学公式渲染配置指南用 KaTeX 在图表中嵌入 LaTeX/MathML 表达式Mermaid 数学公式渲染配置指南用 KaTeX 在图表中嵌入 LaTeX/MathML 表达式 本文围绕 Mermaidv10.9.0的数学公式M图表库前端数据可视化Starward启动器公告域名迁移的技术解析Starward启动器公告域名迁移的技术解析 在游戏启动器开发过程中公告系统的域名管理是一个容易被忽视但至关重要的环节。近期Starward启动器项目中发现了桌面应用Cherry Studio 数学公式渲染迁移指南MathJax 移除与 KaTeX 全面接管Cherry Studio 数学公式渲染迁移指南MathJax 移除与 KaTeX 全面接管 导读 本文围绕 Cherry Studiocherry st人工智能大模型AI 应用交互助手本地部署上一篇Taro 类方法中定义 JSX 的限制与 no-jsx-in-class-method 规则实践下一篇purchases-flutter未来展望新功能预告与最佳实践分享创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考 HedgeDoc 2.0 FAQ 深度解析：从 KaTeX 公式、Mermaid 图表到渲染器域名隔离的技术迁移指南
后端前端云原生【免费下载链接】hedgedocHedgeDoc - Ideas grow better together项目地址https://gitcode.com/gh_mirrors/he/hedgedoc点击查看免费下载本指南以 HedgeDoc 2.0 官方 FAQdocs/content/faq/index.md为骨架逐条解读社区最常问的六类问题公式引擎为何从 MathJax 换成 KaTeX、sequence代码块为何被弃用、标题标签与逗号分隔 tags 为何不再支持、渲染器为何建议独立域名部署、forkawesome 图标为何被替换。文中不仅给出迁移前后的完整写法还结合仓库前端扩展App Extension与后端配置源码讲清每一项变更背后的实现原理与验证方式读完即可在你的笔记中完成平滑迁移。一、为什么 HedgeDoc 2.0 从 MathJax 切换到 KaTeXHedgeDoc 2.0 重构了 React 前端其中一个重要的渲染内核变更是数学公式的渲染引擎从 MathJax 2 切换为 KaTeX。官方 FAQ 给出了三个原因KaTeX 渲染速度快得多相比 MathJax 的完整排版流程KaTeX 采用预生成的字体与更轻量的解析管线显著降低公式渲染耗时这对实时协作编辑场景尤为关键。MathJax 的 React 组件无人维护旧方案依赖的react-mathjax组件已停止维护且不支持 MathJax 3继续沿用存在兼容性风险。KaTeX 覆盖面足够KaTeX 支持日常数学表达所需的全部命令足以满足 Markdown 笔记中的公式需求。源码层面的实现佐证公式渲染能力在前端以扩展App Extension形式注入。KatexAppExtension负责将 KaTeX 注册进 Markdown 渲染管线katex-app-extension.ts构建KatexMarkdownExtension渲染扩展同时向编辑器「速查表Cheatsheet」注册katex条目方便用户在编辑器中查询公式语法。katex-markdown-extension.ts通过markdown-it-mathjax插件解析 LaTeX 语法把行内公式inline math与独立公式display math包装为app-katex标签再由KatexReplacer组件在渲染端替换为 KaTeX 输出的 HTML。换句话说编辑器中的公式书写方式没有变化仍然是$...$或$$...$$变化的只是后端排版引擎。如果你在迁移到 2.0 后发现公式渲染样式略有不同这是引擎差异的正常表现语法本身无需改动。二、为什么sequence代码块语言被弃用如何迁移HedgeDoc 2.0 开始统一使用 Mermaid 渲染时序图sequence diagram。FAQ 明确说明时序图的语法本身没有变化只是代码块的标记语言需要从sequence改为mermaid并在图表内容之前插入一行sequenceDiagram。弃用写法HedgeDoc 1.xAlice-John: Hello John, how are you? John--Alice: Great!新写法HedgeDoc 2.0源码层面的实现佐证弃用不是一句口号而是由前端扩展与编辑器 Linter 双重落实的legacy-sequence-diagram-app-extension.ts 保留了旧语法兼容同时注册了一个SingleLineRegexLinter用正则/sequence/匹配旧的代码围栏在编辑器中直接弹出弃用警告并给出替换建议mermaid\nsequenceDiagram。mermaid-app-extension.ts 注册了 markdowntags:tag1,tag2从 HedgeDoc 2.0 起**标题中的标签声明不再被支持**。官方 FAQ 的建议是改用 frontmatter 元数据来指定标签。frontmatter 是笔记正文开头的 YAML 块HedgeDoc 的 frontmatter 解析实现在 [commons/src/note-frontmatter](https://link.gitcode.com/i/4a571d8fefb17955a40db1a727cb71d4) 目录下其中 [parse-tags-field.ts](https://link.gitcode.com/i/6183386423e5ddd191519530265a2474) 专门负责解析 tags 字段。正确写法如下 yaml --- title: 我的笔记 tags: - tag1 - tag2 ---标题中的tags:只是普通文本不会影响笔记的标签索引、搜索与权限管理务必迁移到 frontmatter 中。四、为什么 YAML 元数据中逗号分隔的 tags 定义被弃用除了标题标签YAML 元数据里的逗号分隔写法同样被弃用。原因很直接YAML 规范本身已为列表提供了标准定义项目方没有必要再维护一套自定义的逗号分隔语法。弃用写法tags: tag1, tag2新写法YAML 列表tags: - tag1 - tag2或使用 YAML 行内数组tags: [tag1, tag2]源码层面的实现佐证有趣的是虽然官方文档已声明逗号分隔写法弃用但解析器仍保留了向后兼容parseTagsField在遇到字符串输入时仍会按逗号切分、逐项去除首尾空白并丢弃空标签遇到数组输入时则逐项转为字符串并 trim。这说明旧笔记即使暂时未迁移也不会立即失效但新笔记应统一使用 YAML 标准列表写法避免将来解析器移除兼容逻辑后出现意外。五、为什么建议把渲染器Renderer部署到独立的子域名HedgeDoc 的架构中编辑器Editor与渲染器Renderer可以分离部署。FAQ 指出当渲染器由另一个域名提供时攻击者更难通过渲染后的笔记内容操纵 HedgeDoc 或窃取凭证因为渲染器与编辑器之间隔离更彻底。这能显著提升软件安全性大幅缓解跨站脚本攻击XSS风险。当然你可以不启用这层额外防护直接运行但官方推荐在条件允许时启用。如何配置HD_RENDERER_BASE_URL渲染器域名通过环境变量HD_RENDERER_BASE_URL配置。配置参考文档 docs/content/references/config/general.md 给出的定义是环境变量默认值说明HD_RENDERER_BASE_URLHD_BASE_URL的内容渲染器运行的 URL省略时与HD_BASE_URL相同后端在 backend/src/config/app.config.ts 中对该变量做校验解析rendererBaseUrl: process.env.HD_RENDERER_BASE_URL。前端侧frontend/src/utils/base-url-from-env-extractor.ts 在启动时读取环境变量并缓存 base URLHD_RENDERER_BASE_URL未设置时自动回退到HD_BASE_URL即编辑器的地址这也与配置表中「默认值为 HD_BASE_URL 的内容」一致。单元测试 base-url-from-env-extractor.spec.ts 覆盖了合法 URL、非法 URL、未设置等分支。参考示例与 frontend/package.json 中start:dev:mock脚本的用法一致HD_BASE_URLhttps://hedgedoc.example.org/ HD_RENDERER_BASE_URLhttps://renderer.example.org/重要提醒反向代理同步调整!!! note 启用独立域名后你的反向代理配置需要同步调整把指向该域名如renderer.example.org的请求转发到前端服务。否则渲染器域名将无法访问页面渲染会失败。反向代理的整体配置方法参见 docs/content/how-to/reverse-proxy.md。六、为什么 forkawesome 图标被弃用如何替换forkawesome 图标集维护不够活跃HedgeDoc 2.0 决定用 Bootstrap Icons 替代它。为了保持与 HedgeDoc 1.x 笔记的兼容性项目仍会暂时导入旧图标但未来很可能移除。官方 FAQ 的建议很明确最佳行动是尽快把旧图标替换为 Bootstrap Icons。源码层面的实现佐证旧图标的提示同样由编辑器 Linter 落实。在 fork-awesome-html-tag-app-extension.ts 中正则/i class[][\w\s]*fa-[\w-][\w\s-]*[][^]*\/?(?:\/i)?/用于匹配形如i classfa fa-xxx的旧图标 HTML 标签一旦命中就在编辑器中显示弃用提示并引导用户查阅本文对应的 FAQ 说明。因此当你编辑旧笔记时编辑器会自动标出需要替换的图标标签。替换示例!-- 弃用写法 -- i classfa fa-github/i !-- 新写法Bootstrap Icons -- i classbi bi-github/i迁移清单小结对照本指南为 HedgeDoc 2.0 笔记做一次体检公式$...$/$$...$$语法不变渲染引擎已自动切换为 KaTeX时序图sequence改为mermaid并首行加sequenceDiagram标签删除标题中的tags:改用 frontmatter 的 YAML 列表或行内数组安全部署如条件允许为渲染器配置独立域名HD_RENDERER_BASE_URL并同步调整反向代理图标把i classfa fa-...替换为i classbi bi-...。以上每一项都在当前仓库中有对应的源码与测试可查证前端扩展目录 frontend/src/extensions/external-lib-app-extensions 存放 KaTeX、Mermaid 等渲染扩展frontend/src/extensions/essential-app-extensions 存放 fork-awesome 兼容与提示逻辑frontmatter 解析位于 commons/src/note-frontmatterURL 解析与配置校验分别见 frontend/src/utils/base-url-from-env-extractor.ts 与 backend/src/config/app.config.ts。如果仍有疑问可以前往社区论坛或 Matrix 聊天室继续提问见 docs/content/faq/index.md 开头说明。赞分享后端前端云原生【免费下载链接】hedgedocHedgeDoc - Ideas grow better together项目地址https://gitcode.com/gh_mirrors/he/hedgedoc点击查看免费下载相关推荐Mermaid 数学公式渲染配置指南用 KaTeX 在图表中嵌入 LaTeX/MathML 表达式Mermaid 数学公式渲染配置指南用 KaTeX 在图表中嵌入 LaTeX/MathML 表达式 本文围绕 Mermaidv10.9.0的数学公式M图表库前端数据可视化Starward启动器公告域名迁移的技术解析Starward启动器公告域名迁移的技术解析 在游戏启动器开发过程中公告系统的域名管理是一个容易被忽视但至关重要的环节。近期Starward启动器项目中发现了桌面应用Cherry Studio 数学公式渲染迁移指南MathJax 移除与 KaTeX 全面接管Cherry Studio 数学公式渲染迁移指南MathJax 移除与 KaTeX 全面接管 导读 本文围绕 Cherry Studiocherry st人工智能大模型AI 应用交互助手本地部署上一篇Taro 类方法中定义 JSX 的限制与 no-jsx-in-class-method 规则实践下一篇purchases-flutter未来展望新功能预告与最佳实践分享创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考