Wiki.js 支持哪些编辑器？Markdown 与可视化编辑切换指南

图 0：Wiki.js 多编辑器体系与数据迁移核心机制概览

一、Wiki.js 支持的六大编辑器类型及适用场景

在 Wiki.js 2.x 中，编辑器不是界面上的简单皮肤，而是与页面的“内容格式（Content Format）”严格绑定的处理引擎。系统根据团队不同角色分工，提供了覆盖工程、业务、数据和出版规范的 6 种编辑器：

1. Markdown 源码编辑器（Markdown）

基于 CodeMirror 构建源码编辑区，搭配定制的 Markdown-it 渲染管线。它支持左右双栏实时同步滚动预览、快捷插入表格与代码块。在拓展能力上，原生整合了 KaTeX 数学公式渲染、Mermaid 动态架构图表、Prism 语法高亮以及 ::: tip 等自定义容器标签。底层内容直接以 .md 纯文本存储，对 Git 存储库的双向同步极为友好。

2. Visual 可视化编辑器（WYSIWYG）

基于 CKEditor 5 深度定制开发，专为不熟悉 Markdown 标记语法的业务团队打造。操作逻辑与常见的现代富文本处理器一致，提供所见即所得的标题层级、字体修饰、无序/有序列表、拖拽式图像上传以及图形化多行表格操作。其底层将内容直接序列化为经过规范化清理的 HTML DOM 结构。

3. Code 代码编辑器（Code Editor）

内置轻量级代码编辑引擎（Ace / CodeMirror），允许用户直接编写原始的 HTML、CSS 样式表甚至内联 JavaScript 片段。它通常用于制作团队专属的门户首页、引入复杂的外部 iframe 组件、绘制定制交互面板，或直接嵌入外部监控看板。

4. AsciiDoc 专业文档编辑器

采用 AsciiDoctor.js 作为核心驱动。相较于 Markdown，AsciiDoc 具备更严格的技术出版工业规范，支持更加复杂的跨章节交叉引用、文档局部导入（include）、附录定义与严谨的属性变量替换。适合大型系统架构设计书、产品技术白皮书和学术性专著的编写。

5. OpenAPI / Swagger 接口文档编辑器

专为现代微服务与 API 研发设计的专用文档编辑器。支持在线以 YAML 或 JSON 格式编写符合 OpenAPI 3.0 规范的接口描述。页面前端会自动集成 Swagger UI / Redoc 解析引擎，直接生成带有参数定义、请求示例以及在线接口发起测试功能的交互式 API 规范页。

6. Tabular 表格编辑器

内置轻量级电子表格引擎，提供网格单元格式的排版体验。允许用户直接录入行列结构化数据、设置单元格数据类型并执行基础公式求和与聚合计算。适用于服务器资产台账、权限对照表、测试用例追踪等高度表格化的知识沉淀。

图 1：Wiki.js 支持的六大编辑器架构与底层存储格式映射对比

二、管理员配置：开启指定编辑器与设定全站默认

虽然 Wiki.js 内置了上述多种编辑器，但在开箱默认状态下，系统可能只激活了部分选项。为了避免团队内部产生过多杂乱无序的文档格式，系统管理员需要合理配置启用的编辑器列表，并为新文档指定全站默认编辑器。

• 登录管理控制台：
  以拥有 Super Administrator 或具备系统管理权限的账户登录 Wiki.js。点击左侧主菜单底部的齿轮图标（Administration），进入全站管理控制台。
• 进入编辑器设置页面：
  在管理控制台左侧的侧边栏导航中，找到并点击 Editors（编辑器）配置菜单项。
• 激活目标编辑器并收拢选项：
  在编辑器列表中，你可以看到全部 6 类编辑器。点击对应条目右侧的开关，将其置为激活（Enabled）。针对常规知识库协作，强烈建议仅保留 Markdown 和 Visual 两个主力编辑器，并停用团队当前阶段不需要的冷门编辑器，从而避免新人在创建文档时因选项过多而产生选择困难。
• 配置全站默认编辑器（Default Editor）：
  在页面顶部的 Default Editor 下拉菜单中，选择全站初始默认编辑器。如果你的团队以软件开发为主，建议选定为 Markdown；如果是跨部门混合或全员协同知识库，可将其设为 Visual。配置完成后，务必点击右上角的 Save 按钮保存。
• 调整各编辑器详细参数与权限组：
  点击各编辑器卡片右下角的齿轮图标，可以进入深层定制页。例如在 Markdown 中启用或关闭数学公式扩展（KaTeX）、流程图（Mermaid）；在 Visual 中配置 CKEditor 的工具栏按钮集合。如需控制权限，可在 Groups 用户组设置中，细化哪些部门只允许读写指定类型的文档。

图 2：Wiki.js 管理后台启用与默认编辑器配置操作流程

三、Markdown 与可视化编辑器切换的核心阻碍与原理

在日常使用中，很多团队成员希望在编写某篇文档时，能在 Markdown 和 Visual 编辑器之间自由切换。然而在实际界面中，Wiki.js 并没有提供一键切换视图的“实时 Toggle 按钮”。这一设计的背后并非功能缺失，而是由底层数据结构的本质差异所决定的：

1. 抽象语法树（AST）与 HTML DOM 结构的语义不对等

Markdown 是一种专注于语义而非样式的轻量级纯文本标记。Wiki.js 在解析 Markdown 时，会将原始字符解析为抽象语法树（AST），并依据扩展插件动态渲染为网页结构。而 Visual 编辑器（CKEditor 5）则是基于严格的强模式 HTML DOM 模型运行的，它只接受其内部模型能够识别的标准 HTML 标签。

2. 扩展语法的不可逆降级

在 Markdown 中，技术人员经常使用丰富的扩展语法，例如：

• 代码块标头：```typescript 或 ```bash
• 动态渲染图表：```mermaid 流程图与时序图
• 数学公式块：$$\sum_{i=1}^n i$$
• 定制容器提醒框：::: tip 提示 与 ::: warning 警告

如果系统强制将这些语法转换到 Visual 可视化编辑器中，CKEditor 无法理解这些私有 DSL。它只能将它们编译后的静态结果（例如已经栅格化或内联成固定 span/div 的静态快照）写入 HTML。一旦转入可视化，原来的源码标记将被彻底拍平，失去原有的语法编辑能力。

3. 反向解析时的 HTML 污染

当尝试把 Visual 编辑器生成的 HTML 反向转换为 Markdown 时，CKEditor 生成的富文本容器（例如 <figure class="table">、带有内联样式的 <span style="color:..."> 以及复杂嵌套的 <div>）很难被标准 Markdown 语法表达。反编译工具（如 Turndown）只能被迫保留原始 HTML 标签，导致生成的 Markdown 源码中混杂着大量杂乱的 HTML 标签，彻底破坏了 Markdown 的纯净性与可读性。

图 3：Markdown 与 Visual (HTML) 格式转换机制及信息损耗深度解析

四、现有页面跨格式切换的三种实操方案

如果现有页面确实因为协作者变更或内容重构需要更换编辑器，可以根据文档的重要程度和内容复杂度，选择以下三种行之有效的实操方案：

方案一：页面属性转换法（Page Settings -> Convert Content）

适用场景：结构简单、只包含普通段落、常规列表与基础表格的轻量页面。

具体步骤：

1. 打开需要转换的页面，进入编辑模式（点击右下方编辑浮标）。
2. 点击右上角的齿轮或更多操作菜单，进入 Page Actions → Page Settings。
3. 在属性面板中找到 Content Format（或 Editor 关联项）。在下拉列表中将 markdown 改选为 html（或反向操作）。
4. 系统会提示进行格式转换（Convert）。确认后，Wiki.js 会调用内置转换器将文本进行初步转译。
5. 回到编辑器中，仔细通篇检查各级标题、列表缩进和超链接是否发生跑位，微调保存。

方案二：安全重构迁移法（克隆副本 + 重设格式 + 校验替换）

适用场景：企业核心业务文档、技术架构说明、包含大量格式化代码与复杂排版的生产文档（生产环境首选推荐）。

具体步骤：

1. 提取纯文本：以原编辑器模式打开页面，全选复制代码源码并保存在本地编辑器中。
2. 新建过渡页面：在 Wiki.js 中点击新建页面（New Page），目标路径可暂设为临时路由（如 docs/temp-migration-page）。在格式选择弹窗中明确指定目标编辑器（如 Visual Editor）。
3. 结构化粘贴与排版：
   • 如果是由 Markdown 迁移到 Visual：可以利用现代浏览器的富文本复制机制，或者在 Wiki.js 的 Markdown 预览栏中全选复制带格式的内容，直接粘贴到 CKEditor 中。
   • 如果是由 Visual 迁移到 Markdown：建议先将富文本内容通过 Markdown 清理转换工具转为标准语法，再填入 Markdown 编辑器，并重新为代码块标注语言高亮头。
4. 验证与路径替换：确认过渡页面的排版、图片资源与内外链跳转无误后，将旧页面重命名或归档，将新页面路由更名为原正式路径。

方案三：纯文本清洗与正则过滤法（Visual 转回 Markdown）

适用场景：误用 Visual 编辑器创建的技术文档，其中掺杂了大量垃圾 HTML 标签，需要恢复为纯净的 Markdown 格式。

具体步骤：

1. 在页面设置中导出或复制该页面的 HTML 源码。
2. 利用本地脚本或工具（例如 VS Code 的正则查找替换或 Node.js Turndown 库）剔除冗余的 <span>、空 <p></p> 以及内嵌的行内样式 style="..."。
3. 将清洗后的标准 HTML 转成 Markdown，重建标准表格语法。
4. 重新以 Markdown 模式保存页面并提交历史版本。

五、团队规范与编辑器选型决策建议

为了从根本上降低后期的格式迁移成本，企业与团队在搭建 Wiki.js 知识库初期，就应当制定明确的内容规范，遵循“按部门角色与内容生命周期选型”的原则：

图 4：Wiki.js 页面编辑器选型与格式迁移决策模型

1. 研发与技术运维团队

应当统一切换为 Markdown 编辑器。技术文档不仅包含大量命令、参数配置和逻辑流程图，更依赖于细粒度的 Git 历史追踪。Markdown 文本的差异比对（Diff）清晰明了，且易于与 GitHub / GitLab 代码仓实现持续集成同步。

2. 人事、行政、财务与综合运营

建议以 Visual 可视化编辑器 为准入规范。这些岗位的核心述求在于快速上手、所见即所得、字体色彩标重以及多行单元格表格的频繁调整。使用 CKEditor 能够免去对特殊符号与语法的学习记忆成本，大幅提高非技术岗位的协同编辑积极性。

3. 避免单页反复“折返跑”

文档建立后，应当在元数据中明确其所属规范类型，尽量避免在同一篇文档的生命周期内反复在 Markdown 与 Visual 之间往返切换。若需要跨部门审阅技术文档，非技术人员可以通过评论（Comments）功能反馈修改建议，而将具体的内容编辑权留给技术团队在 Markdown 源码中维护。