Important: This documentation covers Yarn 1 (Classic).
For Yarn 2+ docs and migration guide, see yarnpkg.com.

Package detail

prosemirror-markdown

prosemirror7.3mMIT1.13.2TypeScript support: included

ProseMirror Markdown integration

readme

prosemirror-markdown

[ WEBSITE | ISSUES | FORUM | GITTER ]

This is a (non-core) module for ProseMirror. ProseMirror is a well-behaved rich semantic content editor based on contentEditable, with support for collaborative editing and custom document schemas.

This module implements a ProseMirror schema that corresponds to the document schema used by CommonMark, and a parser and serializer to convert between ProseMirror documents in that schema and CommonMark/Markdown text.

This code is released under an MIT license. There's a forum for general discussion and support requests, and the Github bug tracker is the place to report issues.

We aim to be an inclusive, welcoming community. To make that explicit, we have a code of conduct that applies to communication around the project.

Documentation

schema: Schema<"doc" | "paragraph" | "blockquote" | "horizontal_rule" | "heading" | "code_block" | "ordered_list" | "bullet_list" | "list_item" | "text" | "image" | "hard_break", "em" | "strong" | "link" | "code">

Document schema for the data model used by CommonMark.

class MarkdownParser

A configuration of a Markdown parser. Such a parser uses markdown-it to tokenize a file, and then runs the custom rules it is given over the tokens to create a ProseMirror document tree.

new MarkdownParser(schema: Schema, tokenizer: any, tokens: Object<ParseSpec>)

Create a parser with the given configuration. You can configure the markdown-it parser to parse the dialect you want, and provide a description of the ProseMirror entities those tokens map to in the tokens object, which maps token names to descriptions of what to do with them. Such a description is an object, and may have the following properties:

schema: Schema

The parser's document schema.

tokenizer: any

This parser's markdown-it tokenizer.

tokens: Object<ParseSpec>

The value of the tokens object used to construct this parser. Can be useful to copy and modify to base other parsers on.

parse(text: string) → any

Parse a string as CommonMark markup, and create a ProseMirror document as prescribed by this parser's rules.

interface ParseSpec

Object type used to specify how Markdown tokens should be parsed.

node⁠?: string

This token maps to a single node, whose type can be looked up in the schema under the given name. Exactly one of node, block, or mark must be set.

block⁠?: string

This token (unless noCloseToken is true) comes in _open and _close variants (which are appended to the base token name provides a the object property), and wraps a block of content. The block should be wrapped in a node of the type named to by the property's value. If the token does not have _open or _close, use the noCloseToken option.

mark⁠?: string

This token (again, unless noCloseToken is true) also comes in _open and _close variants, but should add a mark (named by the value) to its content, rather than wrapping it in a node.

attrs⁠?: Attrs

Attributes for the node or mark. When getAttrs is provided, it takes precedence.

getAttrs⁠?: fn(token: any, tokenStream: any[], index: number) → Attrs

A function used to compute the attributes for the node or mark that takes a markdown-it token and returns an attribute object.

noCloseToken⁠?: boolean

Indicates that the markdown-it token has no _open or _close for the nodes. This defaults to true for code_inline, code_block and fence.

ignore⁠?: boolean

When true, ignore content for the matched token.

defaultMarkdownParser: MarkdownParser

A parser parsing unextended CommonMark, without inline HTML, and producing a document in the basic schema.

class MarkdownSerializer

A specification for serializing a ProseMirror document as Markdown/CommonMark text.

new MarkdownSerializer(nodes: Object<fn(state: MarkdownSerializerState, node: Node, parent: Node, index: number)>, marks: Object<Object>, options⁠?: Object = {})

Construct a serializer with the given configuration. The nodes object should map node names in a given schema to function that take a serializer state and such a node, and serialize the node.

options
escapeExtraCharacters⁠?: RegExp

Extra characters can be added for escaping. This is passed directly to String.replace(), and the matching characters are preceded by a backslash.

nodes: Object<fn(state: MarkdownSerializerState, node: Node, parent: Node, index: number)>

The node serializer functions for this serializer.

marks: Object<Object>

The mark serializer info.

options: Object
escapeExtraCharacters⁠?: RegExp

Extra characters can be added for escaping. This is passed directly to String.replace(), and the matching characters are preceded by a backslash.

serialize(content: Node, options⁠?: Object = {}) → string

Serialize the content of the given node to CommonMark.

options
tightLists⁠?: boolean

Whether to render lists in a tight style. This can be overridden on a node level by specifying a tight attribute on the node. Defaults to false.

class MarkdownSerializerState

This is an object used to track state and expose methods related to markdown serialization. Instances are passed to node and mark serialization methods (see toMarkdown).

options: {tightLists⁠?: boolean, escapeExtraCharacters⁠?: RegExp}

The options passed to the serializer.

wrapBlock(delim: string, firstDelim: string, node: Node, f: fn())

Render a block, prefixing each line with delim, and the first line in firstDelim. node should be the node that is closed at the end of the block, and f is a function that renders the content of the block.

ensureNewLine()

Ensure the current content ends with a newline.

write(content⁠?: string)

Prepare the state for writing output (closing closed paragraphs, adding delimiters, and so on), and then optionally add content (unescaped) to the output.

closeBlock(node: Node)

Close the block for the given node.

text(text: string, escape⁠?: boolean = true)

Add the given text to the document. When escape is not false, it will be escaped.

render(node: Node, parent: Node, index: number)

Render the given node as a block.

renderContent(parent: Node)

Render the contents of parent as block nodes.

renderInline(parent: Node)

Render the contents of parent as inline content.

renderList(node: Node, delim: string, firstDelim: fn(index: number) → string)

Render a node's content as a list. delim should be the extra indentation added to all lines except the first in an item, firstDelim is a function going from an item index to a delimiter for the first line of the item.

esc(str: string, startOfLine⁠?: boolean = false) → string

Escape the given string so that it can safely appear in Markdown content. If startOfLine is true, also escape characters that have special meaning only at the start of the line.

repeat(str: string, n: number) → string

Repeat the given string n times.

markString(mark: Mark, open: boolean, parent: Node, index: number) → string

Get the markdown string for a given opening or closing mark.

getEnclosingWhitespace(text: string) → {leading⁠?: string, trailing⁠?: string}

Get leading and trailing whitespace from a string. Values of leading or trailing property of the return object will be undefined if there is no match.

defaultMarkdownSerializer: MarkdownSerializer

A serializer for the basic schema.

changelog

1.13.2 (2025-03-18)

Bug fixes

Add a code flag to the code mark.

1.13.1 (2024-09-26)

Bug fixes

Fix a type error caused by use of an older markdown-it type package.

1.13.0 (2024-05-20)

Bug fixes

Fix the type of MarkdownParser.parse to be non-nullable. Add a strict option to MarkdownSerializer

New features

The new strict option to MarkdownSerializer makes it possible to make the serializer ignore node and mark types it doesn't know.

1.12.0 (2023-12-11)

Bug fixes

Block-level markup inside a heading is no longer escaped by the serializer.

Do not backslash-escape a + at the start of line when it isn't followed by a space. Upgrade to markdown-it 14

New features

MarkdownSerializerState.renderInline now takes a parameter that controls whether block-level markup should be escaped.

Upgrade to markdown-it version 14, which provides ES modules.

1.11.2 (2023-08-04)

Bug fixes

Fix some unnecessary escapes for period characters in Markdown serialization.

Only escape # signs if they would otherwise create a heading. Add a test for headings in list items

Fix a bug in MarkdownSerializer that broken expelling of whitespace from marks when the mark spanned multiple nodes.

1.11.1 (2023-06-30)

Bug fixes

Allow any blocks as first child of list items to align with what Markdown itself does.

Add parse rules that clear strong and em marks when inline CSS resets it.

1.11.0 (2023-05-17)

Bug fixes

Make sure blank lines at the end of code blocks are properly serialized.

Convert soft breaks (single newlines) in Markdown to spaces, rather than newlines in the ProseMirror document, because newlines tend to behave awkwardly in the editor.

Fix a bug that cause the object passed as configuration to MarkdownSerializer to be mutated. Add release note

Include CommonJS type declarations in the package to please new TypeScript resolution settings.

New features

A new option to MarkdownSerializer allows client code to configure which node type should be treated as hard breaks during mark serialization. Remove the extra left bracket

1.10.1 (2022-10-28)

Bug fixes

Don't treat the empty string the same as null in wrapBlock's firstDelim argument. Check content of code blocks for any sequence of backticks

Use longer sequences of backticks when serializing a code block that contains three or more backticks in a row.

1.10.0 (2022-10-05)

New features

You can now pass an optional markdown-it environment object to .

1.9.4 (2022-08-19)

Bug fixes

Don't escape colon characters at the start of a line.

Escape parentheses in images and links.

Allow links to wrap emphasis markers when serializing Markdown.

1.9.3 (2022-07-05)

Bug fixes

Make sure '!' characters in front of links are escaped.

1.9.2 (2022-07-04)

Bug fixes

Don't escape characters in autolinks.

Fix a bug that caused the serializer to not escape start-of-line markup when inside a list.

1.9.1 (2022-06-02)

Bug fixes

Fix a bug where inline nodes with content would reset the marks in their parent node during Markdown parsing.

1.9.0 (2022-05-30)

New features

Include TypeScript type declarations.

1.8.0 (2022-03-14)

New features

MarkdownSerializer now takes an escapeExtraCharacters option that can be used to control backslash-escaping behavior. Fix types for new option

1.7.1 (2022-02-16)

Bug fixes

Avoid escaping underscores surrounded by word characters.

1.7.0 (2022-01-06)

New features

Upgrade markdown-it to version 12.

1.6.2 (2022-01-04)

Bug fixes

Fix a bug where URL text in links and images was overzealously escaped.

1.6.1 (2021-12-16)

Bug fixes

Fix a bug where MarkdownParser.parse could return null when the parsed content doesn't fit the schema.

Make sure underscores are escaped when serializing to Markdown.

1.6.0 (2021-09-21)

New features

MarkdownParser.tokenizer is now public, for easier creation of parsers that base on other parsers.

1.5.2 (2021-09-03)

Bug fixes

Serializing to Markdown now properly escapes '>' characters at the start of the line.

1.5.1 (2021-01-06)

Bug fixes

The Markdown parser will now correctly set the tight attribute on list nodes.

1.5.0 (2020-07-17)

New features

Markdown parse specs can now be specified as noCloseToken, which will cause the parser to treat them as a single token, rather than a pair of _open/_close tokens.

1.4.5 (2020-05-14)

Bug fixes

Don't allow hard_break nodes in headings.

1.4.4 (2019-12-19)

Bug fixes

Fix issue that broke parsing ordered lists with a starting number other than 1.

1.4.3 (2019-12-17)

Bug fixes

Don't use short-hand angle bracket syntax when outputting self-linking URLs that are relative.

1.4.2 (2019-11-20)

Bug fixes

Rename ES module files to use a .js extension, since Webpack gets confused by .mjs

1.4.1 (2019-11-19)

Bug fixes

The file referred to in the package's module field now is compiled down to ES5.

1.4.0 (2019-11-08)

New features

Add a module field to package json file.

1.3.2 (2019-10-30)

Bug fixes

Code blocks in the schema no longer allow marks inside them.

Code blocks are now parsed with preserveWhiteSpace: full, preventing removal of newline characters.

1.3.1 (2019-06-08)

Bug fixes

Fix a bug that could occur when parsing multiple adjacent pieces of text with the same style.

1.3.0 (2019-01-22)

Bug fixes

Inline code containing backticks is now serialized wrapped in the appropriate amount of backticks.

New features

The serializer now serializes links whose target is the same as their text content using < > syntax.

Mark opening and close string callbacks now get passed the mark's context (parent fragment and index).

1.2.2 (2018-11-22)

Bug fixes

Hard breaks at the end of an emphasized or strong mark are no longer serialized to invalid Markdown text.

1.2.1 (2018-10-19)

Bug fixes

Fixes a bug where inline mark delimiters were serialized incorrectly (the closing and opening marks were swapped, which was only noticeable when they are different).

1.2.0 (2018-10-08)

Bug fixes

Fixes an issue where the Markdown serializer would escape special characters in inline code.

New features

Upgrade the markdown-it dependency to version 8.

1.1.1 (2018-07-08)

Bug fixes

Fix bug that caused superfluous backslashes to be inserted at the start of some lines when serializing to Markdown.

1.1.0 (2018-06-20)

New features

You can now override the handling of softbreak tokens in a custom handler.

1.0.4 (2018-04-17)

Bug fixes

Fix crash when serializing marks with line breaks inside of them.

1.0.3 (2018-01-10)

Bug fixes

Fix dependency version range for prosemirror-model.

1.0.2 (2017-12-07)

Bug fixes

Code blocks are always wrapped in triple backticks when serializing, to avoid parsing corner cases around indented code blocks.

1.0.1 (2017-11-05)

Bug fixes

Link marks are now non-inclusive (typing after them produces non-linked text).

1.0.0 (2017-10-13)

First stable release.