README

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






 







English  |  Demo



🔥 欢迎观摩我们的另一个开源项目 思源笔记


 💡 简介

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

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

!b3logos.jpg

 🗺️ 背景

随着 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，如粘贴中包含外链图片可通过指定接口上传到服务器
 支持主窗口大小拖拽、字符计数
 多主题支持，内置黑白绿三套主题
 多语言支持，内置中、英、韩文本地化
 支持主流浏览器，对移动端友好

!editor.png

!preview.png

 🔮 编辑模式

 所见即所得（WYSIWYG）

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

!vditor-wysiwyg

 即时渲染（IR）

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

!vditor-ir

 分屏预览（SV）

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

!vditor-sv

 🍱 语法支持

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

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

 🗃 案例

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

 🛠️ 使用文档

 CommonJS

 安装依赖

shell
npm install vditor --save


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

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

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


 HTML script

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

html





 示例代码

 官方示例 / 示例源码
 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 更新