Contribute to this guide

guideMarkdown output

The Markdown plugin allows switching the default CKEditor 5 output from HTML to Markdown. This allows for producing lightweight text documents with a simple formatting syntax, widespread among the programming and development communities and popular in many environments (e.g. GitHub). Coupled with the autoformatting feature, it allows for the full-fledged Markdown WYSIWYG editing experience.

Please remember that Markdown syntax is very simple and it does not cover all the rich-text features. Some features provided by CKEditor 5 will thus work as intended only when output to HTML as they have no Markdown equivalent.

You can learn more about the possible practical applications of Markdown editing with CKEditor 5 in this dedicated blog post depicting the idea, solutions and a case study.

# Demo

The CKEditor 5 instance below is configured to output GitHub Flavored Markdown. Use the editor to create your content and see the Markdown output displayed as you type below the editor.

The Markdown language

Markdown is a lightweight markup language that you can use to add formatting elements to plain text documents. Created by John Gruber in 20032004, Markdown is now one of the world’s most popular markup languages.


Editing with Markdown output

The CKEditor 5 WYSIWYG editor lets you use this flexible yet simple markup language in the GitHub flavor. The editor-produced Markdown output supports the most important features, like links, different kinds of emphasis, inline code formatting or code blocks:

p {
  text-align: center;
  color: red;
}

Formatting blocks with Markdown

Markdown can be used to create various block-level features, such as:

  • Block quotes
  • Headings
    1. Heading 1
    2. Heading 2
    3. Heading 3
  • Lists, including nested ones
    • Numbered lists
    • Bulleted lists

Support for tables in Markdown

Bear in mind that Markdown has only very basic support for tables, so things like table styles or merged cells will not work.

  Income Revenue
Walker 3 $104.000 15%
Stroller $12.000 10%
Runner $97.500 15%

Output:

Some other ways to output the edited content include:

  • Export to Word – Generate editable .docx files out of your editor-created content.
  • Export to PDF – Generate portable PDF files out of your editor-created content.
  • Autoformatting – Use Markdown syntax shortcodes to automatically format your content as you type!

# The Markdown data processor

The Markdown plugins uses a data processor (implemented by the GFMDataProcessor class) which changes the default output from HTML to Markdown. This means that you can set or get data from the editor in the Markdown format:

editor.getData(); // -> 'This is [CKEditor 5](https://ckeditor.com).'

editor.setData( 'This is **bold**.' );

The data processor outputs the GFM Markdown syntax. “GFM” stands for “GitHub Flavored Markdown” — a Markdown dialect used by GitHub. Markdown lacks any formal specification (although the CommonMark initiative aims to close this gap) and has many dialects, often incompatible with one another.

When converting the output produced by this data processor, make sure to use a compatible Markdown-to-HTML converter (e.g. the marked library).

This feature is experimental. While the CKEditor 5 architecture supports changing the data format, in most scenarios we do recommend sticking to the default format which is HTML (supported by the HtmlDataProcessor). HTML remains the best standard for rich-text data.

And please do remember — using Markdown does not automatically make your application or website secure.

# Installation

To enable this data processor in your editor, install the @ckeditor/ckeditor5-markdown-gfm package:

npm install --save @ckeditor/ckeditor5-markdown-gfm

Then add the Markdown plugin to the editor configuration, which will change the default data processor to the GFMDataProcessor:

import ClassicEditor from '@ckeditor/ckeditor5-editor-classic/src/classiceditor';

import Essentials from '@ckeditor/ckeditor5-essentials/src/essentials';
import Bold from '@ckeditor/ckeditor5-basic-styles/src/bold';
import Italic from '@ckeditor/ckeditor5-basic-styles/src/italic';
// ...

import Markdown from '@ckeditor/ckeditor5-markdown-gfm/src/markdown';

ClassicEditor
    .create( document.querySelector( '#snippet-markdown' ), {
        plugins: [
            Markdown,

            Essentials,
            Bold,
            Italic,
            // ...
        ],
        // ...
    } )
    .then( ... )
    .catch( ... );

# Known issues

Please bear in mind that the Markdown data processor does not support all rich text features. The Markdown syntax is very simple and only supports limited formatting options.

This means that advanced formatting like list styles, table styles or page break markers will be stripped in the effecting data. These are not supported by Markdown and therefore cannot be converted from HTML to Markdown.

While the Markdown plugin is stable and ready to use, some issues were reported for it. Feel free to upvote 👍  them on GitHub if they are important for you:

  • The horizontal rule is not yet supported by the autoformatting feature but it gets output to Markdown nevertheless if inserted using the toolbar button. GitHub issue: #5720.
  • Pasting Markdown-formatted content does not automatically convert the pasted syntax markers into properly formatted content. GitHub issues: #2321, #2322.

# Contribute

The source code of this feature is available on GitHub in https://github.com/ckeditor/ckeditor5/tree/master/packages/ckeditor5-markdown-gfm.