vditor

易于使用的 Markdown 编辑器，为适配不同的应用场景而生

English  |  Demo

💡 简介

Vditor 是一款浏览器端的 Markdown 编辑器，支持所见即所得、即时渲染（类似 Typora）和分屏预览模式。它使用 TypeScript 实现，支持原生 JavaScript 以及 Vue、React、Angular 和 Svelte 等框架。

欢迎到 Vditor 官方讨论区了解更多。同时也欢迎关注 B3log 开源社区微信公众号 B3log开源：

🗺️ 背景

随着 Markdown 排版方式的普及，越来越多的应用开始集成 Markdown 编辑器。目前主流可集成的 Markdown 编辑器现状如下：

• 有的仅支持分屏预览，即编辑区和预览区分离
• 有的同时支持所见即所得和分屏预览，但所见即所得模式下不能完整支持 Markdown 语法排版
• 几乎没有类似 Typora 的即时渲染

而这三点恰好对应了三种应用场景：

• 分屏预览：适配传统的 Markdown 使用场景，适合大屏下编辑排版
• 所见即所得：对不熟悉 Markdown 的用户友好，熟悉 Markdown 的用户也可以无缝使用
• 即时渲染：理论上这是最为优雅的 Markdown 编辑方式，让熟悉 Markdown 的用户能够更专注于内容创作

所以，一个能够适配应用场景的 Markdown 编辑器至关重要，它需要考虑到：

• 传统 Markdown 用户的使用场景，提供分屏预览
• 富文本编辑用户的使用场景，提供所见即所得
• 高阶 Markdown 用户的使用场景，提供即时渲染

Vditor 在这些方面做了努力，希望能为现代化的通用 Markdown 编辑领域做出一些贡献。

✨ 特性

• 支持三种编辑模式：所见即所得（wysiwyg）、即时渲染（ir）、分屏预览（sv）
• 支持大纲、数学公式、脑图、图表、流程图、甘特图、时序图、五线谱、多媒体、语音阅读、标题锚点、代码高亮及复制、graphviz 渲染、plantumlUML图
• 导出、图片懒加载、任务列表、多平台预览、多主题切换、复制到微信公众号/知乎功能
• 实现 CommonMark 和 GFM 规范，可对 Markdown 进行格式化和语法树查看，并支持10+项配置
• 工具栏包含 36+ 项操作，除支持扩展外还可对每一项中的快捷键、提示、提示位置、图标、点击事件、类名、子工具栏进行自定义
• 表情/at/话题等自动补全扩展
• 可使用拖拽、剪切板粘贴上传，显示实时上传进度，支持 CORS 跨域上传
• 实时保存内容，防止意外丢失
• 录音支持，用户可直接发布语音
• 粘贴 HTML 自动转换为 Markdown，如粘贴中包含外链图片可通过指定接口上传到服务器
• 支持主窗口大小拖拽、字符计数
• 多主题支持，内置黑白绿三套主题
• 多语言支持，内置中、英、韩文本地化
• 支持主流浏览器，对移动端友好

🔮 编辑模式

所见即所得（WYSIWYG）

所见即所得模式对不熟悉 Markdown 的用户较为友好，熟悉 Markdown 的话也可以无缝使用。

即时渲染（IR）

即时渲染模式对熟悉 Typora 的用户应该不会感到陌生，理论上这是最优雅的 Markdown 编辑方式。

分屏预览（SV）

传统的分屏预览模式适合大屏下的 Markdown 编辑。

🍱 语法支持

• 所有 CommonMark 语法：分隔线、ATX 标题、Setext 标题、缩进代码块、围栏代码块、HTML 块、链接引用定义、段落、块引用、列表、反斜杠转义、HTML 实体、行级代码、强调、加粗、链接、图片、行级 HTML、硬换行、软换行和纯文本。
• 所有 GFM 语法：表格、任务列表项、删除线、自动链接、XSS 过滤
• 常用 Markdown 扩展语法：脚注、ToC、自定义标题 ID
• 图表语法
  • 流程图、时序图、甘特图，通过 Mermaid 支持
  • Graphviz
  • 折线图、饼图、脑图等，通过 ECharts 支持
• 五线谱：通过 abc.js 支持
• 数学公式：数学公式块、行级数学公式，通过 MathJax 和 KaTeX 支持
• YAML Front Matter
• 中文语境优化
  • 中西文之间插入空格
  • 术语拼写修正
  • 中文后跟英文逗号句号等标点替换为中文对应标点

以上大部分特性可以通过开关配置是否启用，开发者可根据自己的应用场景选择搭配。

🗃 案例

• Sym 一款用 Java 实现的现代化社区（论坛/BBS/社交网络/博客）平台
• Solo & Pipe B3log 分布式社区的博客端节点，欢迎加入下一代社区网络
• Tditor 基于React、Vditor、Springboot， 一款打造极致文字创作体验的在线Markdown编辑平台
• Arya 基于 Vue、Vditor，所构建的在线 Markdown 编辑器
• 更多案例

🛠️ 使用文档

CommonJS

• 安装依赖

npm install vditor --save

• 在代码中引入并初始化对象，可参考 index.js

import Vditor from 'vditor'
import "~vditor/src/assets/less/index"

const vditor = new Vditor(id, {options...})

HTML script

• 在 HTML 中插入 CSS 和 JavaScript，可参考 demo

<!-- ⚠️生产环境请指定版本号，如 https://unpkg.com/vditor@x.x.x/dist... -->
<link rel="stylesheet" href="https://unpkg.com/vditor/dist/index.css" />
<script src="https://unpkg.com/vditor/dist/index.min.js"></script>

示例代码

• 官方示例 / 示例源码
• CommonJS Editor
• CommonJS Render
• 在Svelte中使用

主题

编辑器主题

编辑器所展现的外观。内置classic，dark 2 套主题。

• 编辑器初始化时可通过 options.theme 设置内置主题
• 初始化完成后可通过 setTheme 更新编辑器主题
• 可通过修改 index.less 中的变量对主题颜色进行定制
• 可参考现有结构和类名在原有基础上进行修改

内容主题

Markdown 输出的 HTML 所展现的外观。内置 ant-design, light，dark，wechat 4 套主题。支持内容主题扩展接口。

• 需在显示元素上添加 class="vditor-reset"
• 编辑器初始化时可通过 options.preview.theme 设置内置或自己开发的主题列表
• 内容渲染初始化时可通过 IPreviewOptions.theme 设置内置或自己开发的主题
• 初始化完成后可通过 setTheme 或 setContentTheme 更新内容主题

代码主题

代码块所展现的外观。内置 github 等 36 套主题。

• 编辑器初始化时可通过 options.preview.hljs 对代码块样式、行号、是否启用进行设置
• 内容渲染初始化时可通过 IPreviewOptions.hljs 对代码块样式、行号、是否启用进行设置
• 初始化完成后可通过 setTheme 或 setCodeTheme 更新代码主题

API

id

可填入元素 id 或元素自身 HTMLElement

⚠️：当填入元素自身的 HTMLElement 时需设置 options.cache.id 或将 options.cache.enable 设置为 false

options

options.toolbar

• 工具栏，可使用 name 进行简写：