下一代的 Markdown 编辑器，为未来而构建

Vditor 是一款浏览器端的 Markdown 编辑器，使用 TypeScript 实现。支持原生 JavaScript、Vue、React、Angular。

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

我们在开发 Sym 的初期是直接使用 WYSIWYG 富文本编辑器的。那时候基于 HTML 的编辑器非常流行，项目中引用起来也很方便，也符合用户当时的使用习惯。

后来，Markdown 的崛起逐步改变了大家的排版方式。再加上我们其他几个项目都是面向程序员用户的，所以迁移到 md 上也是大势所趋。我们选择了 CodeMirror，这是一款优秀的编辑器，它对开发者提供了丰富的编程接口，对各种浏览器的兼容性也比较好。

再后来，随着我们项目业务需求方面的沉淀，使用 CodeMirror 有时候会感到比较“笨重”。比如要实现 @自动完成用户名列表、插入 Emoji、上传文件等就需要比较深入的二次开发，而这些业务需求恰恰是很多项目场景共有且必备的。

终于，我们决定开始在 Sym 中自己实现编辑器。随着几个版本的迭代，Sym 的编辑器也日趋成熟。在我们运营的社区黑客派上陆续有人问我们是否能将编辑器单独抽离出来提供给大家使用。与此同时，我们的前端主程 V 同学对于维护分散在各个项目中的编辑器也感到有点力不从心，外加对 TypeScript 的好感，所以就决定使用 ts 来实现一个全新的浏览器端 md 编辑器。

于是，Vditor 就这样诞生了。

• 支持三种编辑模式：所见即所得、即时渲染、分屏预览
• 支持任务列表、at、图表、流程图、甘特图、时序图、五线谱、多媒体、语音阅读、标题锚点渲染
• 支持快捷键操作
• 支持 Markdown 格式化， Markdown 语法树实时渲染
• 表情自动补全，设置常用表情，支持表情自定义
• 自定义工具栏按钮、提示、插入字符、快捷键，支持工具栏添加按钮
• 可使用拖拽、剪切板粘贴上传，显示实时上传进度，支持 CORS 跨域上传
• 实时保存内容，防止意外丢失
• 录音支持，用户可直接发布语音
• 粘贴 HTML 自动转换为 Markdown，如粘贴中包含外链图片可通过指定接口上传到服务器
• 提供实时预览、滚动同步定位
• 支持主窗口大小拖拽、字符计数
• 多主题支持、内置黑白两套
• 多语言支持、内置中英文
• 支持主流浏览器和移动端

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

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

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

• 🎶 Sym 一款用 Java 实现的现代化社区（论坛/BBS/社交网络/博客）平台
• 🎸 Solo & 🎷 Pipe B3log 分布式社区的博客端节点，欢迎加入下一代社区网络
• 📕 链滴笔记 一款桌面端笔记应用，支持 Windows、Mac 和 Linux
• 🌟 Starfire 一个分布式的内容分享讨论社区，星星之火可以燎原
• 📝 Arya 基于 Vue、Vditor，所构建的在线 Markdown 编辑器

• 安装依赖

npm install vditor --save

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

import Vditor from 'vditor'
import "~vditor/src/assets/scss/index" // 或者使用 dark

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

• 在 HTML 中插入 CSS 和 js，可参考 static.html

<!-- ⚠️生产环境请指定版本号，如 https://cdn.jsdelivr.net/npm/[email protected]/dist... -->
<link rel="stylesheet" href="https://cdn.jsdelivr.net/npm/vditor/dist/index.css" />
<script src="https://cdn.jsdelivr.net/npm/vditor/dist/index.min.js" defer></script>

• CommonJS
• HTML script
• Preview
• Vue

• 支持黑白两套主题：classic/dark
• 参考现有样式后使用自己开发的 scss/css 进行样式的完全自定制
• 可通过修改 index.scss 中的变量对主题颜色进行定制
• 在内容显示元素上添加 class="vditor-reset" （经典主题） 或 class="vditor-reset vditor-reset--dark"（黑色主题） 属性可对内容进行更为友好的展示

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

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

• 工具栏，可使用 name 进行简写： toolbar: ['emoji', 'br', 'bold', '|', 'line'] 。默认值参见 src/ts/util/Options.ts
• name 可枚举为： emoji , headings , bold , italic , strike , | , line , quote , list , ordered-list , check , code , inline-code , undo , redo , upload , link , table , record , edit-mode , both , preview , format , fullscreen , devtools , info , help , br
• 当 name 不在枚举中时，可以添加自定义按钮，格式如下：

{  
 hotkey: '⌘-⇧-f',  
 name: 'format',  
 tipPosition: 'ne',  
 tip: 'format',  
 icon: '<svg version="1.1" xmlns="https://www.w3.org/2000/svg" width="768" height="768" viewBox="0 0 768 768"><path d="M342 426v-84h426v84h-426zM342 256v-86h426v86h-426zM0 0h768v86h-768v-86zM342 598v-86h426v86h-426zM0 214l170 170-170 170v-340zM0 768v-86h768v86h-768z"></path></svg>',  
 click: () => {  
   alert('custom toolbar')  
 },  
}

• 文件上传的数据结构如下。后端返回的数据结构不一致时，可使用 format 进行转换。

// POST data  
xhr.send(formData);  // formData = FormData.append("file[]", File)  
// return data  
{  
 "msg": "",  
 "code": 0,  
 "data": {  
 "errFiles": ['filename', 'filename2'],  
 "succMap": {  
   "filename3": "filepath3",  
   "filename3": "filepath3"  
   }  
 }  
}

• 为了防止站外图片失效， linkToImgUrl 可将剪贴板中的站外图片地址传到服务器端进行保存处理，其数据结构如下：

// POST data  
xhr.send(JSON.stringify({url: src})); // src 为站外图片地址  
// return data  
{  
 msg: '',  
 code: 0,  
 data : {  
   originalURL: '',  
   url: ''  
 }  
}

• 不需要进行编辑操作时，仅需引入 method.min.js 后如下直接调用

Vditor.mermaidRender(document)

import VditorPreview from 'vditor/dist/method.min'  
VditorPreview.mermaidRender(document)

• 需要对页面中的 Markdown 进行渲染时可直接调用 preview 方法，参数如下：

previewElement: HTMLDivElement,   // 使用该元素进行渲染
markdown: string,  // 需要渲染的 markdown 原文
options?: IPreviewOptions {  
 anchor?: boolean;  // 为标题添加锚点
 theme?: string;  // 主题：'classic' | 'dark'，默认为 'classic'
 customEmoji?: { [key: string]: string };    // 自定义 emoji，默认为 {}  
 lang?: (keyof II18nLang);    // 语言，默认为 'zh_CN'  
 emojiPath?: string;    // 表情图片路径 
 hljs?: IHljs // 参见 options.preview.hljs 
 speech?: {  // 对选中后的内容进行阅读
  enable?: boolean
 }
 math?: IMath // 数学公式渲染配置
 transform?(html: string): string // 在渲染前进行的回调方法
 cdn?: string // 自建 CDN 地址
}

• ⚠️ method.min.js 和 index.min.js 不可同时引入

• 关于所见即所得 Markdown 编辑器的讨论
• Vditor 实现 Markdown 所见即所得
• Lute 一款对中文语境优化的 Markdown 引擎，支持 Go 和 JavaScript

1. 安装 node LTS 版本
2. 下载 最新代码并解压
3. 根目录运行 npm install
4. npm run start 启动本地服务器，打开 https://localhost:9000
5. 修改代码
6. npm run build 打包代码到 dist 目录

由于使用了按需加载的机制，默认 CDN 为 https://cdn.jsdelivr.net/npm/vditor@版本号

如果代码有修改或需要使用自建 CDN 的话，可按以下步骤进行操作：

• 初始化的 options 及 IPreviewOptions 中需添加 cdn 配置
• highlightRender , mathRender , abcRender , chartRender , mermaidRender 方法中需添加 cdn 参数
• 将 build 成功的 dist 目录或 jsDelivr 中的 dist 目录拷贝至正确的位置

版本升级时请仔细阅读 CHANGELOG 中的升级部分

• 基础语法
• 扩展语法
• 速查手册

• 讨论区
• 报告问题

Vditor 使用 MIT 开源协议。

• Lute：🎼 一款结构化的 Markdown 引擎，支持 Go 和 JavaScript
• highlight.js：JavaScript syntax highlighter
• mermaid：Generation of diagram and flowchart from text in a similar manner as Markdown
• incubator-echarts：A powerful, interactive charting and visualization library for browser
• abcjs：JavaScript library for rendering standard music notation in a browser