Markdown output

The Markdown plugin lets you switch the default output from HTML to Markdown. This way you can produce lightweight text documents with a simple formatting syntax that is popular among developers.

# Demo

The editor below is configured to output GitHub Flavored Markdown. Edit the content and see how the Markdown output changes (you can find it below the editor).

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

## Markdown output 🛫

[CKEditor 5](https://ckeditor.com/) can be configured to output Markdown instead of HTML. Markdown is a lightweight markup language that you can use to add formatting to plain text documents. Use the **Source** button to check and edit the Markdown source code of this content.

The editor-produced Markdown output supports most essential features, like [links](https://ckeditor.com/), **different** kinds of _emphasis_, `inline code formatting`, or code blocks:

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

## Markdown input 🛬

Thanks to the [autoformatting feature](https://ckeditor.com/docs/ckeditor5/latest/features/autoformat.html), you can use Markdown syntax when writing. Try it out - use these (or any other) Markdown shortcuts in the editor to format the content on the fly 🚀!

| Inline formatting | Shortcut |
| --- | --- |
| **Bold** | Type `**` or `__` around your text. |
| _Italic_ | Type `*` or `_` around your text. |
| `Code` | Type `ˋ` around your text. |
| ~Strikethrough~ | Type `~~` around your text. |

Shh! 🤫 Markdown has very basic support for tables. Some advanced table-related features like table or cell styling were disabled in this demo.

## Block formatting

You can also use Markdown to create various text blocks, such as:

*   Block quotes - Start a line with `﹥` followed by a space.
*   Headings:
    1.  Heading 1 - Start a line with `#` followed by a space.
    2.  Heading 2 - Start a line with `##` followed by a space.
    3.  Heading 3 - Start a line with `###` followed by a space.
*   Lists, including nested ones:
    *   Numbered lists - Start a line with `1.` or `1)` followed by a space.
    *   Bulleted lists - Start a line with `*` or `-` followed by a space.
    *   To-do lists - Start a line with `[ ]` or `[x]` followed by a space to insert an unchecked or checked list item.
*   Code blocks - Start a line with `ˋˋˋ`.
*   Horizontal lines - Start a line with `---`.

# Additional feature information

Coupled with the autoformatting feature, the Markdown plugin offers the full-fledged Markdown WYSIWYG editing experience, as described in the “CKEditor 5: the best open source Markdown editor” blog post. Visit the free online Markdown editor to see this solution implemented.

Please remember that Markdown syntax is really 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.

# Extending formatting support

If you need more extensive Markdown support for formatting elements (for example, having the title attribute on links represented as [Foo Bar](https://foo.bar "My link title")), you can also install General HTML Support. This advanced feature allows the integrators to provide additional tags, elements, and attributes, not yet supported by other CKEditor 5 plugins and extend the formatting capabilities.

# The Markdown data processor

The Markdown plugin 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 (for example, the marked library).

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

import { Bold, Italic } from '@ckeditor/ckeditor5-basic-styles';
import { Essentials } from '@ckeditor/ckeditor5-essentials';
// More imports.
// ...

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

ClassicEditor
    .create( document.querySelector( '#snippet-markdown' ), {
        plugins: [
            Markdown,
            Essentials,
            Bold,
            Italic,
            // More plugins.
            // ...
        ],
        // More of editor's configuration.
        // ...
    } )
    .then( /* ... */ )
    .catch( /* ... */ );

# Known issues

While the Markdown plugin is stable and ready to use, some issues are still being worked on. Feel free to upvote 👍  these on GitHub if you would like to see this introduced.

• Pasting Markdown-formatted content does not automatically convert the pasted syntax markers into properly formatted content. GitHub issues: #2321, #2322.
• The Markdown code generated with the Markdown output feature will not properly render nested tables. GitHub issue: #9475.

# Related features

Some other ways to output the edited content include:

• Source editing – Allows for Markdown source edition if configured accordingly.
• 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!
• Paste Markdown – Paste Markdown-formatted content straight into the editor.

# Contribute

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