Cherry Markdown 编辑器

English | 简体中文 | 日本語

文档

演示

简介

Cherry Markdown 编辑器是一个 Javascript Markdown 编辑器。它具有开箱即用、轻量化和易于扩展的优点。它可以在浏览器或服务器（使用 NodeJs）中运行。

开箱即用

开发者可以以非常简单的方式调用和实例化 Cherry Markdown 编辑器。实例化后的 Cherry Markdown 编辑器默认支持大多数常用的 markdown 语法（如标题、目录、流程图、公式等）。

易于扩展

当 Cherry Markdown 编辑器支持的语法无法满足您的需求时，可以快速进行二次开发或功能扩展。同时，Cherry Markdown 编辑器应该由纯 JavaScript 实现，不应依赖于 angular、vue 和 react 等框架技术。框架只提供容器环境。

特性

语法特性

图片缩放、对齐和引用
根据表格内容生成图表
调整字体颜色和大小
字体背景色、上标和下标
插入检查列表
插入音频或视频

多种模式

实时预览与滚动同步
仅预览模式
无工具栏模式（极简编辑模式）
移动端预览模式

功能特性

从富文本复制并粘贴为 markdown 文本
经典换行和常规换行
多光标编辑
图片大小编辑
导出为图片或 PDF
浮动工具栏：出现在新行的开头
气泡工具栏：选中文本时出现

性能特性

部分渲染
部分更新

安全性

Cherry Markdown 内置安全 Hook，通过过滤白名单和 DomPurify 进行扫描过滤。

样式主题

Cherry Markdown 有多种样式主题可供选择。

功能展示

点击这里查看更多详情

安装

通过 yarn

yarn add cherry-markdown

通过 npm

npm install cherry-markdown --save

如果需要启用 mermaid 绘图和表格转图表功能，需要同时添加 mermaid 和 echarts 包。

目前，Cherry 推荐的插件版本是 echarts@4.6.0 mermaid@9.4.3。

# 安装 mermaid，启用 mermaid 和绘图功能
yarn add mermaid@9.4.3
# 安装 echarts，开启表格转图表功能
yarn add echarts@4.6.0

快速开始

浏览器

UMD

<link href="cherry-editor.min.css" />
<div id="markdown-container"></div>
<script src="cherry-editor.min.js"></script>
<script>
  new Cherry({
    id: 'markdown-container',
    value: '# 欢迎使用 cherry 编辑器！',
  });
</script>

ESM

import 'cherry-markdown/dist/cherry-markdown.css';
import Cherry from 'cherry-markdown';
const cherryInstance = new Cherry({
  id: 'markdown-container',
  value: '# 欢迎使用 cherry 编辑器！',
});

Node

const { default: CherryEngine } = require('cherry-markdown/dist/cherry-markdown.engine.core.common');
const cherryEngineInstance = new CherryEngine();
const htmlContent = cherryEngineInstance.makeHtml('# 欢迎使用 cherry 编辑器！');

精简版本

由于 mermaid 库的体积较大，cherry 构建产物包含一个不内置 Mermaid 的核心构建包。可以通过以下方式引入核心构建：

完整模式（带用户界面）

import 'cherry-markdown/dist/cherry-markdown.css';
import Cherry from 'cherry-markdown/dist/cherry-markdown.core';
const cherryInstance = new Cherry({
  id: 'markdown-container',
  value: '# 欢迎使用 cherry 编辑器！',
});

引擎模式（仅语法编译）

// 引入 Cherry 引擎核心构建
// 引擎配置项与 Cherry 配置项相同，以下文档内容仅介绍 Cherry 核心包
import CherryEngine from 'cherry-markdown/dist/cherry-markdown.engine.core';
const cherryEngineInstance = new CherryEngine();
const htmlContent = cherryEngineInstance.makeHtml('# 欢迎使用 cherry 编辑器！');

// --> <h1>欢迎使用 cherry 编辑器！</h1>

⚠️ 关于 mermaid

核心构建包不包含mermaid依赖，需要手动导入相关插件。

import 'cherry-markdown/dist/cherry-markdown.css';
import Cherry from 'cherry-markdown/dist/cherry-markdown.core';
import CherryMermaidPlugin from 'cherry-markdown/dist/addons/cherry-code-block-mermaid-plugin';
import mermaid from 'mermaid';

// 插件注册必须在Cherry实例化之前完成
Cherry.usePlugin(CherryMermaidPlugin, {
  mermaid, // 传入mermaid对象
  // mermaidAPI: mermaid.mermaidAPI, // 也可以传入mermaid API
  // 同时，你可以在这里配置mermaid的行为，请参考mermaid官方文档
  // theme: 'neutral',
  // sequence: { useMaxWidth: false, showSequenceNumbers: true }
});

const cherryInstance = new Cherry({
  id: 'markdown-container',
  value: '# 欢迎使用cherry编辑器！',
});

动态导入

推荐使用动态导入，以下是webpack动态导入的示例。

import 'cherry-markdown/dist/cherry-markdown.css';
import Cherry from 'cherry-markdown/dist/cherry-markdown.core';

const registerPlugin = async () => {
  const [{ default: CherryMermaidPlugin }, mermaid] = await Promise.all([
    import('cherry-markdown/src/addons/cherry-code-block-mermaid-plugin'),
    import('mermaid'),
  ]);
  Cherry.usePlugin(CherryMermaidPlugin, {
    mermaid, // 传入mermaid对象
  });
};

registerPlugin().then(() => {
  // 插件注册必须在Cherry实例化之前完成
  const cherryInstance = new Cherry({
    id: 'markdown-container',
    value: '# 欢迎使用cherry编辑器！',
  });
});

配置

查看 /src/Cherry.config.js 或点击这里

示例

点击这里查看更多示例。

客户端

正在开发中，敬请期待或查看 /client/

扩展

自定义语法

点击这里

自定义工具栏

点击这里

单元测试

选择Jest作为单元测试工具，因为它支持断言、异步和快照。单元测试包括CommonMark测试和快照测试。

CommonMark测试

执行 yarn run test:commonmark 来测试官方CommonMark套件。这个命令运行速度快。

套件位于 test/suites/commonmark.spec.json，例如：

{
  "markdown": " \tfoo\tbaz\t\tbim\n",
  "html": "<pre><code>foo\tbaz\t\tbim\n</code></pre>\n",
  "example": 2,
  "start_line": 363,
  "end_line": 368,
  "section": "Tabs"
},

在这个例子中，Jest会比较 Cherry.makeHtml(" \tfoo\tbaz\t\tbim\n") 生成的html与预期结果 "<pre><code>foo\tbaz\t \tbim\n</code></pre>\n"。Cherry Markdown的匹配器已忽略了 data-line 等私有属性。

CommonMark规范和套件来自：https://spec.commonmark.org/ 。

快照测试

执行 yarn run test:snapshot 来运行快照测试。你可以像 test/core/hooks/List.spec.ts 这样编写快照套件。第一次运行时，会自动生成快照。之后，Jest可以比较快照与生成的HTML。如果需要重新生成快照，删除 test/core/hooks/__snapshots__ 下的旧快照，然后再次运行此命令。

快照测试运行较慢。它应该只用于测试容易出错且包含Cherry Markdown特殊语法的Hooks。