prosemirror-markdown

<h1>prosemirror-markdown</h1> [ <a href="http://prosemirror.net">WEBSITE</a> | <a href="https://github.com/prosemirror/prosemirror-markdown/issues">ISSUES</a> | <a href="https://discuss.prosemirror.net">FORUM</a> | <a href="https://gitter.im/ProseMirror/prosemirror">GITTER</a> ] This is a (non-core) module for <a href="http://prosemirror.net">ProseMirror</a>. 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 <a href="https://prosemirror.net/docs/guide/#schema">schema</a> that corresponds to the document schema used by <a href="http://commonmark.org/">CommonMark</a>, and a parser and serializer to convert between ProseMirror documents in that schema and CommonMark/Markdown text. This code is released under an <a href="https://github.com/prosemirror/prosemirror/tree/master/LICENSE">MIT license</a>. There's a <a href="http://discuss.prosemirror.net">forum</a> for general discussion and support requests, and the <a href="https://github.com/prosemirror/prosemirror/issues">Github bug tracker</a> is the place to report issues. We aim to be an inclusive, welcoming community. To make that explicit, we have a <a href="http://contributor-covenant.org/version/1/1/0/">code of conduct</a> that applies to communication around the project. <h2>Documentation</h2> <dl> <dt id="schema"> <code><a href="#schema">schema</a>: Schema<"doc" | "paragraph" | "blockquote" | "horizontal_rule" | "heading" | "code_block" | "ordered_list" | "bullet_list" | "list_item" | "text" | "image" | "hard_break", "em" | "strong" | "link" | "code"></code></dt> <dd>Document schema for the data model used by CommonMark. </dd> <dt id="MarkdownParser"> <h4> <code>class</code> <a href="#MarkdownParser">MarkdownParser</a></h4> </dt> <dd>A configuration of a Markdown parser. Such a parser uses <a href="https://github.com/markdown-it/markdown-it">markdown-it</a> to tokenize a file, and then runs the custom rules it is given over the tokens to create a ProseMirror document tree. <dl><dt id="MarkdownParser.constructor"> <code>new <a href="#MarkdownParser.constructor">MarkdownParser</a>(<a id="MarkdownParser.constructor^schema" href="#MarkdownParser.constructor^schema">schema</a>: Schema, <a id="MarkdownParser.constructor^tokenizer" href="#MarkdownParser.constructor^tokenizer">tokenizer</a>: any, <a id="MarkdownParser.constructor^tokens" href="#MarkdownParser.constructor^tokens">tokens</a>: <a href="https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Object">Object</a><<a href="#ParseSpec">ParseSpec</a>>)</code></dt> <dd>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 <code>tokens</code> 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: </dd><dt id="MarkdownParser.schema"> <code><a href="#MarkdownParser.schema">schema</a>: Schema</code></dt> <dd>The parser's document schema. </dd><dt id="MarkdownParser.tokenizer"> <code><a href="#MarkdownParser.tokenizer">tokenizer</a>: any</code></dt> <dd>This parser's markdown-it tokenizer. </dd><dt id="MarkdownParser.tokens"> <code><a href="#MarkdownParser.tokens">tokens</a>: <a href="https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Object">Object</a><<a href="#ParseSpec">ParseSpec</a>></code></dt> <dd>The value of the <code>tokens</code> object used to construct this parser. Can be useful to copy and modify to base other parsers on. </dd><dt id="MarkdownParser.parse"> <code><a href="#MarkdownParser.parse">parse</a>(<a id="MarkdownParser.parse^text" href="#MarkdownParser.parse^text">text</a>: <a href="https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/String">string</a>) → any</code></dt> <dd>Parse a string as <a href="http://commonmark.org/">CommonMark</a> markup, and create a ProseMirror document as prescribed by this parser's rules. </dd></dl> </dd> <dt id="ParseSpec"> <h4> <code>interface</code> <a href="#ParseSpec">ParseSpec</a></h4> </dt> <dd>Object type used to specify how Markdown tokens should be parsed. <dl><dt id="ParseSpec.node"> <code><a href="#ParseSpec.node">node</a>⁠?: <a href="https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/String">string</a></code></dt> <dd>This token maps to a single node, whose type can be looked up in the schema under the given name. Exactly one of <code>node</code>, <code>block</code>, or <code>mark</code> must be set. </dd><dt id="ParseSpec.block"> <code><a href="#ParseSpec.block">block</a>⁠?: <a href="https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/String">string</a></code></dt> <dd>This token (unless <code>noCloseToken</code> is true) comes in <code>_open</code> and <code>_close</code> 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 <code>_open</code> or <code>_close</code>, use the <code>noCloseToken</code> option. </dd><dt id="ParseSpec.mark"> <code><a href="#ParseSpec.mark">mark</a>⁠?: <a href="https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/String">string</a></code></dt> <dd>This token (again, unless <code>noCloseToken</code> is true) also comes in <code>_open</code> and <code>_close</code> variants, but should add a mark (named by the value) to its content, rather than wrapping it in a node. </dd><dt id="ParseSpec.attrs"> <code><a href="#ParseSpec.attrs">attrs</a>⁠?: Attrs</code></dt> <dd>Attributes for the node or mark. When <code>getAttrs</code> is provided, it takes precedence. </dd><dt id="ParseSpec.getAttrs"> <code><a href="#ParseSpec.getAttrs">getAttrs</a>⁠?: fn(<a id="ParseSpec.getAttrs^token" href="#ParseSpec.getAttrs^token">token</a>: any, <a id="ParseSpec.getAttrs^tokenStream" href="#ParseSpec.getAttrs^tokenStream">tokenStream</a>: any[], <a id="ParseSpec.getAttrs^index" href="#ParseSpec.getAttrs^index">index</a>: <a href="https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Number">number</a>) → Attrs</code></dt> <dd>A function used to compute the attributes for the node or mark that takes a <a href="https://markdown-it.github.io/markdown-it/#Token">markdown-it token</a> and returns an attribute object. </dd><dt id="ParseSpec.noCloseToken"> <code><a href="#ParseSpec.noCloseToken">noCloseToken</a>⁠?: <a href="https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Boolean">boolean</a></code></dt> <dd>Indicates that the <a href="https://markdown-it.github.io/markdown-it/#Token">markdown-it token</a> has no <code>_open</code> or <code>_close</code> for the nodes. This defaults to <code>true</code> for <code>code_inline</code>, <code>code_block</code> and <code>fence</code>. </dd><dt id="ParseSpec.ignore"> <code><a href="#ParseSpec.ignore">ignore</a>⁠?: <a href="https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Boolean">boolean</a></code></dt> <dd>When true, ignore content for the matched token. </dd></dl> </dd> <dt id="defaultMarkdownParser"> <code><a href="#defaultMarkdownParser">defaultMarkdownParser</a>: <a href="#MarkdownParser">MarkdownParser</a></code></dt> <dd>A parser parsing unextended <a href="http://commonmark.org/">CommonMark</a>, without inline HTML, and producing a document in the basic schema. </dd> <dt id="MarkdownSerializer"> <h4> <code>class</code> <a href="#MarkdownSerializer">MarkdownSerializer</a></h4> </dt> <dd>A specification for serializing a ProseMirror document as Markdown/CommonMark text. <dl><dt id="MarkdownSerializer.constructor"> <code>new <a href="#MarkdownSerializer.constructor">MarkdownSerializer</a>(<a id="MarkdownSerializer.constructor^nodes" href="#MarkdownSerializer.constructor^nodes">nodes</a>: <a href="https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Object">Object</a><fn(<a id="MarkdownSerializer.constructor^nodes^state" href="#MarkdownSerializer.constructor^nodes^state">state</a>: <a href="#MarkdownSerializerState">MarkdownSerializerState</a>, <a id="MarkdownSerializer.constructor^nodes^node" href="#MarkdownSerializer.constructor^nodes^node">node</a>: Node, <a id="MarkdownSerializer.constructor^nodes^parent" href="#MarkdownSerializer.constructor^nodes^parent">parent</a>: Node, <a id="MarkdownSerializer.constructor^nodes^index" href="#MarkdownSerializer.constructor^nodes^index">index</a>: <a href="https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Number">number</a>)>, <a id="MarkdownSerializer.constructor^marks" href="#MarkdownSerializer.constructor^marks">marks</a>: <a href="https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Object">Object</a><<a href="https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Object">Object</a>>, <a id="MarkdownSerializer.constructor^options" href="#MarkdownSerializer.constructor^options">options</a>⁠?: <a href="https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Object">Object</a> = {})</code></dt> <dd>Construct a serializer with the given configuration. The <code>nodes</code> object should map node names in a given schema to function that take a serializer state and such a node, and serialize the node. <dl><dt id="MarkdownSerializer.constructor^options"> <code><a href="#MarkdownSerializer.constructor^options">options</a></code></dt> <dd><dl><dt id="MarkdownSerializer.constructor^options.escapeExtraCharacters"> <code><a href="#MarkdownSerializer.constructor^options.escapeExtraCharacters">escapeExtraCharacters</a>⁠?: <a href="https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/RegExp">RegExp</a></code></dt> <dd>Extra characters can be added for escaping. This is passed directly to String.replace(), and the matching characters are preceded by a backslash. </dd></dl></dd></dl></dd><dt id="MarkdownSerializer.nodes"> <code><a href="#MarkdownSerializer.nodes">nodes</a>: <a href="https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Object">Object</a><fn(<a id="MarkdownSerializer.nodes^state" href="#MarkdownSerializer.nodes^state">state</a>: <a href="#MarkdownSerializerState">MarkdownSerializerState</a>, <a id="MarkdownSerializer.nodes^node" href="#MarkdownSerializer.nodes^node">node</a>: Node, <a id="MarkdownSerializer.nodes^parent" href="#MarkdownSerializer.nodes^parent">parent</a>: Node, <a id="MarkdownSerializer.nodes^index" href="#MarkdownSerializer.nodes^index">index</a>: <a href="https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Number">number</a>)></code></dt> <dd>The node serializer functions for this serializer. </dd><dt id="MarkdownSerializer.marks"> <code><a href="#MarkdownSerializer.marks">marks</a>: <a href="https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Object">Object</a><<a href="https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Object">Object</a>></code></dt> <dd>The mark serializer info. </dd><dt id="MarkdownSerializer.options"> <code><a href="#MarkdownSerializer.options">options</a>: <a href="https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Object">Object</a></code></dt> <dd><dl><dt id="MarkdownSerializer.options.escapeExtraCharacters"> <code><a href="#MarkdownSerializer.options.escapeExtraCharacters">escapeExtraCharacters</a>⁠?: <a href="https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/RegExp">RegExp</a></code></dt> <dd>Extra characters can be added for escaping. This is passed directly to String.replace(), and the matching characters are preceded by a backslash. </dd></dl></dd><dt id="MarkdownSerializer.serialize"> <code><a href="#MarkdownSerializer.serialize">serialize</a>(<a id="MarkdownSerializer.serialize^content" href="#MarkdownSerializer.serialize^content">content</a>: Node, <a id="MarkdownSerializer.serialize^options" href="#MarkdownSerializer.serialize^options">options</a>⁠?: <a href="https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Object">Object</a> = {}) → <a href="https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/String">string</a></code></dt> <dd>Serialize the content of the given node to <a href="http://commonmark.org/">CommonMark</a>. <dl><dt id="MarkdownSerializer.serialize^options"> <code><a href="#MarkdownSerializer.serialize^options">options</a></code></dt> <dd><dl><dt id="MarkdownSerializer.serialize^options.tightLists"> <code><a href="#MarkdownSerializer.serialize^options.tightLists">tightLists</a>⁠?: <a href="https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Boolean">boolean</a></code></dt> <dd>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. </dd></dl></dd></dl></dd></dl> </dd> <dt id="MarkdownSerializerState"> <h4> <code>class</code> <a href="#MarkdownSerializerState">MarkdownSerializerState</a></h4> </dt> <dd>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 <code>toMarkdown</code>). <dl><dt id="MarkdownSerializerState.options"> <code><a href="#MarkdownSerializerState.options">options</a>: {tightLists⁠?: <a href="https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Boolean">boolean</a>, escapeExtraCharacters⁠?: <a href="https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/RegExp">RegExp</a>}</code></dt> <dd>The options passed to the serializer. </dd><dt id="MarkdownSerializerState.wrapBlock"> <code><a href="#MarkdownSerializerState.wrapBlock">wrapBlock</a>(<a id="MarkdownSerializerState.wrapBlock^delim" href="#MarkdownSerializerState.wrapBlock^delim">delim</a>: <a href="https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/String">string</a>, <a id="MarkdownSerializerState.wrapBlock^firstDelim" href="#MarkdownSerializerState.wrapBlock^firstDelim">firstDelim</a>: <a href="https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/String">string</a>, <a id="MarkdownSerializerState.wrapBlock^node" href="#MarkdownSerializerState.wrapBlock^node">node</a>: Node, <a id="MarkdownSerializerState.wrapBlock^f" href="#MarkdownSerializerState.wrapBlock^f">f</a>: fn())</code></dt> <dd>Render a block, prefixing each line with <code>delim</code>, and the first line in <code>firstDelim</code>. <code>node</code> should be the node that is closed at the end of the block, and <code>f</code> is a function that renders the content of the block. </dd><dt id="MarkdownSerializerState.ensureNewLine"> <code><a href="#MarkdownSerializerState.ensureNewLine">ensureNewLine</a>()</code></dt> <dd>Ensure the current content ends with a newline. </dd><dt id="MarkdownSerializerState.write"> <code><a href="#MarkdownSerializerState.write">write</a>(<a id="MarkdownSerializerState.write^content" href="#MarkdownSerializerState.write^content">content</a>⁠?: <a href="https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/String">string</a>)</code></dt> <dd>Prepare the state for writing output (closing closed paragraphs, adding delimiters, and so on), and then optionally add content (unescaped) to the output. </dd><dt id="MarkdownSerializerState.closeBlock"> <code><a href="#MarkdownSerializerState.closeBlock">closeBlock</a>(<a id="MarkdownSerializerState.closeBlock^node" href="#MarkdownSerializerState.closeBlock^node">node</a>: Node)</code></dt> <dd>Close the block for the given node. </dd><dt id="MarkdownSerializerState.text"> <code><a href="#MarkdownSerializerState.text">text</a>(<a id="MarkdownSerializerState.text^text" href="#MarkdownSerializerState.text^text">text</a>: <a href="https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/String">string</a>, <a id="MarkdownSerializerState.text^escape" href="#MarkdownSerializerState.text^escape">escape</a>⁠?: <a href="https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Boolean">boolean</a> = true)</code></dt> <dd>Add the given text to the document. When escape is not <code>false</code>, it will be escaped. </dd><dt id="MarkdownSerializerState.render"> <code><a href="#MarkdownSerializerState.render">render</a>(<a id="MarkdownSerializerState.render^node" href="#MarkdownSerializerState.render^node">node</a>: Node, <a id="MarkdownSerializerState.render^parent" href="#MarkdownSerializerState.render^parent">parent</a>: Node, <a id="MarkdownSerializerState.render^index" href="#MarkdownSerializerState.render^index">index</a>: <a href="https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Number">number</a>)</code></dt> <dd>Render the given node as a block. </dd><dt id="MarkdownSerializerState.renderContent"> <code><a href="#MarkdownSerializerState.renderContent">renderContent</a>(<a id="MarkdownSerializerState.renderContent^parent" href="#MarkdownSerializerState.renderContent^parent">parent</a>: Node)</code></dt> <dd>Render the contents of <code>parent</code> as block nodes. </dd><dt id="MarkdownSerializerState.renderInline"> <code><a href="#MarkdownSerializerState.renderInline">renderInline</a>(<a id="MarkdownSerializerState.renderInline^parent" href="#MarkdownSerializerState.renderInline^parent">parent</a>: Node)</code></dt> <dd>Render the contents of <code>parent</code> as inline content. </dd><dt id="MarkdownSerializerState.renderList"> <code><a href="#MarkdownSerializerState.renderList">renderList</a>(<a id="MarkdownSerializerState.renderList^node" href="#MarkdownSerializerState.renderList^node">node</a>: Node, <a id="MarkdownSerializerState.renderList^delim" href="#MarkdownSerializerState.renderList^delim">delim</a>: <a href="https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/String">string</a>, <a id="MarkdownSerializerState.renderList^firstDelim" href="#MarkdownSerializerState.renderList^firstDelim">firstDelim</a>: fn(<a id="MarkdownSerializerState.renderList^firstDelim^index" href="#MarkdownSerializerState.renderList^firstDelim^index">index</a>: <a href="https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Number">number</a>) → <a href="https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/String">string</a>)</code></dt> <dd>Render a node's content as a list. <code>delim</code> should be the extra indentation added to all lines except the first in an item, <code>firstDelim</code> is a function going from an item index to a delimiter for the first line of the item. </dd><dt id="MarkdownSerializerState.esc"> <code><a href="#MarkdownSerializerState.esc">esc</a>(<a id="MarkdownSerializerState.esc^str" href="#MarkdownSerializerState.esc^str">str</a>: <a href="https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/String">string</a>, <a id="MarkdownSerializerState.esc^startOfLine" href="#MarkdownSerializerState.esc^startOfLine">startOfLine</a>⁠?: <a href="https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Boolean">boolean</a> = false) → <a href="https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/String">string</a></code></dt> <dd>Escape the given string so that it can safely appear in Markdown content. If <code>startOfLine</code> is true, also escape characters that have special meaning only at the start of the line. </dd><dt id="MarkdownSerializerState.repeat"> <code><a href="#MarkdownSerializerState.repeat">repeat</a>(<a id="MarkdownSerializerState.repeat^str" href="#MarkdownSerializerState.repeat^str">str</a>: <a href="https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/String">string</a>, <a id="MarkdownSerializerState.repeat^n" href="#MarkdownSerializerState.repeat^n">n</a>: <a href="https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Number">number</a>) → <a href="https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/String">string</a></code></dt> <dd>Repeat the given string <code>n</code> times. </dd><dt id="MarkdownSerializerState.markString"> <code><a href="#MarkdownSerializerState.markString">markString</a>(<a id="MarkdownSerializerState.markString^mark" href="#MarkdownSerializerState.markString^mark">mark</a>: Mark, <a id="MarkdownSerializerState.markString^open" href="#MarkdownSerializerState.markString^open">open</a>: <a href="https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Boolean">boolean</a>, <a id="MarkdownSerializerState.markString^parent" href="#MarkdownSerializerState.markString^parent">parent</a>: Node, <a id="MarkdownSerializerState.markString^index" href="#MarkdownSerializerState.markString^index">index</a>: <a href="https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Number">number</a>) → <a href="https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/String">string</a></code></dt> <dd>Get the markdown string for a given opening or closing mark. </dd><dt id="MarkdownSerializerState.getEnclosingWhitespace"> <code><a href="#MarkdownSerializerState.getEnclosingWhitespace">getEnclosingWhitespace</a>(<a id="MarkdownSerializerState.getEnclosingWhitespace^text" href="#MarkdownSerializerState.getEnclosingWhitespace^text">text</a>: <a href="https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/String">string</a>) → {leading⁠?: <a href="https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/String">string</a>, trailing⁠?: <a href="https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/String">string</a>}</code></dt> <dd>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. </dd></dl> </dd> <dt id="defaultMarkdownSerializer"> <code><a href="#defaultMarkdownSerializer">defaultMarkdownSerializer</a>: <a href="#MarkdownSerializer">MarkdownSerializer</a></code></dt> <dd>A serializer for the <a href="#schema">basic schema</a>. </dd> </dl>