Cherry Markdown Writer

Document

Demos

Introduction

Cherry Markdown Editor is a Javascript Markdown editor. It has the advantages such as out-of-the-box, lightweight and easy to extend. It can run in browser or server(with NodeJs).

Out-of-the-box

Developer can call and instantiate Cherry Markdown Editor in a very simple way. The instantiated Cherry Markdown Editor supports most commonly used markdown syntax (such as title, TOC, flowchart, formula, etc.) by default.

Easy to extend

When the syntax that Cherry Markdown editor support can not meet your needs, secondary development or function extention can be carried out quickly. At the same time, Cherry Markdown editor should be implemented by pure JavaScript, and should not rely on framework technology such as angular, vue and react. Framework only provide a container environment.

Feature

Syntax Feature

Image zoom, alignment and reference
Generate a chart based on the content of the table
Adjust font color and size
Font background color, superscript and subscript
Insert checklist
Insert audio or video

Multiple modes

Live preview with Scroll Sync
Preview-only mode
No toolbar mode (minimalist editing mode)
Mobile preview mode

Functional Feature

Copy from rich text and paste as markdown text
Classic line feed & regular line feed
Multi-cursor editing
Image size editing
Export as image or pdf
Float toolbar: appears at the beginning of a new line
Bubble toolbar: appears when text is selected

Performance Feature

partial rendering
partial update

Security

Cherry Markdown has a built-in security Hook, by filtering the whitelist and DomPurify to do scan filter.

Style theme

Cherry Markdown has a variety of style themes to choose from.

Features show

click here for more details

Install

Via yarn

yarn add cherry-markdown

Via npm

npm install cherry-markdown --save

If you need to enable the functions of mermaid drawing and table-to-chart, you need to add mermaid and echarts packages at the same time.

Currently, the plug-in version Cherry recommend is echarts@4.6.0 mermaid@9.4.3.

# Install mermaid, enable mermaid and drawing function
yarn add mermaid@9.4.3
# Install echarts, turn on the table-to-chart function
yarn add echarts@4.6.0

Quick start

Browser

UMD

<link href="https://github.com/Tencent/cherry-markdown/blob/main/cherry-editor.min.css" />
<div id="markdown-container"></div>
<script src="https://github.com/Tencent/cherry-markdown/raw/main/cherry-editor.min.js"></script>
<script>
  new Cherry({
    id: 'markdown-container',
    value: '# welcome to cherry editor!',
  });
</script>

ESM

import 'cherry-markdown/dist/cherry-markdown.css';
import Cherry from 'cherry-markdown';
const cherryInstance = new Cherry({
  id: 'markdown-container',
  value: '# welcome to cherry editor!',
});

Node

const { default: CherryEngine } = require('cherry-markdown/dist/cherry-markdown.engine.core.common');
const cherryEngineInstance = new CherryEngine();
const htmlContent = cherryEngineInstance.makeHtml('# welcome to cherry editor!');

Lite Version

Because the size of the mermaid library is very large, the cherry build product contains a core build package without built-in Mermaid. The core build can be imported in the following ways.

Full mode (With UI Interface)

import 'cherry-markdown/dist/cherry-markdown.css';
import Cherry from 'cherry-markdown/dist/cherry-markdown.core';
const cherryInstance = new Cherry({
  id: 'markdown-container',
  value: '# welcome to cherry editor!',
});

Engine Mode (Just Syntax Compile)

// Import Cherry engine core construction
// Engine configuration items are the same as Cherry configuration items, the following document content only introduces the Cherry core package
import CherryEngine from 'cherry-markdown/dist/cherry-markdown.engine.core';
const cherryEngineInstance = new CherryEngine();
const htmlContent = cherryEngineInstance.makeHtml('# welcome to cherry editor!');

// --> <h1>welcome to cherry editor!</h1>

⚠️ About mermaid

The core build package does not contain mermaid dependency, should import related plug-ins manually.

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';

// Plug-in registration must be done before Cherry is instantiated
Cherry.usePlugin(CherryMermaidPlugin, {
  mermaid, // pass in mermaid object
  // mermaidAPI: mermaid.mermaidAPI, // Can also be passed in mermaid API
  // At the same time, you can configure mermaid's behavior here, please refer to the official mermaid document
  // theme: 'neutral',
  // sequence: { useMaxWidth: false, showSequenceNumbers: true }
});

const cherryInstance = new Cherry({
  id: 'markdown-container',
  value: '# welcome to cherry editor!',
});

Dynamic import

recommend Using Dynamic import, the following is an example of webpack Dynamic import.

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, // pass in mermaid object
  });
};

registerPlugin().then(() => {
  //  Plug-in registration must be done before Cherry is instantiated
  const cherryInstance = new Cherry({
    id: 'markdown-container',
    value: '# welcome to cherry editor!',
  });
});

Configuration

see /src/Cherry.config.js or click here

Example

Click here for more examples.

Client

Under development, please stay tuned or see /client/

Extension

Customize Syntax

click here

Customize Toolbar

click here

Unit Test

Jest is selected as a unit testing tool for its assertion, asynchronous support and snapshot. Unit test includes CommonMark test and snapshot test.

CommonMark Test

Call yarn run test:commonmark to test the official CommonMark suites. This command runs fast.

Suites are located in test/suites/commonmark.spec.json, for example:

{
  "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"
},

In this case, Jest will compare the html generated by Cherry.makeHtml(" \tfoo\tbaz\t\tbim\n") with the expected result "<pre><code>foo\tbaz\t \tbim\n</code></pre>\n". Cherry Markdown's matcher has ignored private attributes like data-line.

CommonMark specifications and suites are from: https://spec.commonmark.org/ .

Snapshot Test

Call yarn run test:snapshot to run snapshot test. You can write snapshot suite like test/core/hooks/List.spec.ts. At the first time, a snapshot will be automatically generated. After that, Jest can compare the snapshot with the generated HTML. If you need to regenerate a snapshot, delete the old snapshot under test/core/hooks/__snapshots__ and run this command again.

Snapshot test runs slower. It should only be used to test Hooks that are error-prone and contain Cherry Markdown special syntax.

Contributing

Welcome to join us to build a more powerful Markdown editor. Of course you can submit feature request to us. Please read me before you working on it.

Stargazers over time

License

Apache-2.0

Tencent / cherry-markdown

readme