mdast-util-to-markdown
    TypeScript icon, indicating that this package has built-in type declarations

    1.2.6 • Public • Published

    mdast-util-to-markdown

    Build Coverage Downloads Size Sponsors Backers Chat

    mdast utility to parse markdown.

    When to use this

    Use this if you have direct access to an AST and need to serialize it. Use remark instead, which includes this, but has a nice interface and hundreds of plugins.

    Install

    This package is ESM only: Node 12+ is needed to use it and it must be imported instead of required.

    npm:

    npm install mdast-util-to-markdown

    Use

    Say we have the following script, example.js:

    import {toMarkdown} from 'mdast-util-to-markdown'
    
    const tree = {
      type: 'root',
      children: [
        {
          type: 'blockquote',
          children: [
            {type: 'thematicBreak'},
            {
              type: 'paragraph',
              children: [
                {type: 'text', value: '- a\nb !'},
                {
                  type: 'link',
                  url: 'example.com',
                  children: [{type: 'text', value: 'd'}]
                }
              ]
            }
          ]
        }
      ]
    }
    
    console.log(toMarkdown(tree))

    Now, running node example yields (note the properly escaped characters which would otherwise turn into a list and image respectively):

    > ***
    >
    > \- a
    > b \![d](example.com)

    API

    This package exports the following identifier: toMarkdown. There is no default export.

    toMarkdown(tree[, options])

    Serialize mdast to markdown.

    Formatting options
    options.bullet

    Marker to use for bullets of items in unordered lists ('*', '+', or '-', default: '*').

    options.bulletOther

    Marker to use in certain cases where the primary bullet doesn’t work ('*', '+', or '-', default: depends).

    There are three cases where the primary bullet can’t be used:

    • When three list items are on their own, the last one is empty, and bullet is also a valid rule: * - +. This would turn into a thematic break if serialized with three primary bullets. As this is an edge case unlikely to appear in normal markdown, the last list item will be given a different bullet.
    • When a thematic break is the first child of one of the list items, and bullet is the same character as rule: - ***. This would turn into a single thematic break if serialized with primary bullets. As this is an edge case unlikely to appear in normal markdown this markup is always fixed, even if bulletOther is not passed
    • When two unordered lists appear next to each other: * a\n- b. CommonMark sees different bullets as different lists, but several markdown parsers parse it as one list. To solve for both, we instead inject an empty comment between the two lists: * a\n<!---->\n* b, but if bulletOther is given explicitly, it will be used instead
    options.bulletOrdered

    Marker to use for bullets of items in ordered lists ('.' or ')', default: '.').

    options.bulletOrderedOther

    Marker to use in certain cases where the primary bullet for ordered items doesn’t work ('.' or ')', default: none).

    There is one case where the primary bullet for ordered items can’t be used:

    • When two ordered lists appear next to each other: 1. a\n2) b. CommonMark added support for ) as a marker, but other markdown parsers do not support it. To solve for both, we instead inject an empty comment between the two lists: 1. a\n<!---->\n1. b, but if bulletOrderedOther is given explicitly, it will be used instead
    options.closeAtx

    Whether to add the same number of number signs (#) at the end of an ATX heading as the opening sequence (boolean, default: false).

    options.emphasis

    Marker to use to serialize emphasis ('*' or '_', default: '*').

    options.fence

    Marker to use to serialize fenced code ('`' or '~', default: '`').

    options.fences

    Whether to use fenced code always (boolean, default: false). The default is to fenced code if there is a language defined, if the code is empty, or if it starts or ends in empty lines.

    options.incrementListMarker

    Whether to increment the value of bullets of items in ordered lists (boolean, default: true).

    options.listItemIndent

    Whether to indent the content of list items with the size of the bullet plus one space (when 'one') or a tab stop ('tab'), or depending on the item and its parent list ('mixed', uses 'one' if the item and list are tight and 'tab' otherwise) ('one', 'tab', or 'mixed', default: 'tab').

    options.quote

    Marker to use to serialize titles ('"' or "'", default: '"').

    options.resourceLink

    Whether to use resource links ([text](url)) always (boolean, default: false). The default is to use autolinks (<https://example.com>) when possible.

    options.rule

    Marker to use for thematic breaks ('*', '-', or '_', default: '*').

    options.ruleRepetition

    Number of markers to use for thematic breaks (number, default: 3, min: 3).

    options.ruleSpaces

    Whether to add spaces between markers in thematic breaks (boolean, default: false).

    options.setext

    Whether to use setext headings when possible (boolean, default: false). Setext headings are not possible for headings with a rank more than 2 or when they’re empty.

    options.strong

    Marker to use to serialize strong ('*' or '_', default: '*').

    options.tightDefinitions

    Whether to join definitions w/o a blank line (boolean, default: false). Shortcut for a join function like so:

    function (left, right) {
      if (left.type === 'definition' && right.type === 'definition') {
        return 0
      }
    }
    options.handlers

    Object mapping node types to custom handlers. Useful for syntax extensions. Take a look at lib/handle for examples.

    options.join

    List of functions used to determine what to place between two flow nodes. Often, they are joined by one blank line. In certain cases, it’s nicer to have them next to each other. Or, they can’t occur together. These functions receive two adjacent nodes and their parent and can return number or boolean, referring to how many blank lines to use between them. A return value of true is as passing 1. A return value of false means the nodes cannot be joined by a blank line, such as two adjacent block quotes or indented code after a list, in which case a comment will be injected to break them up:

    > Quote 1
    
    <!---->
    
    > Quote 2
    options.unsafe

    List of patterns to escape. Useful for syntax extensions. Take a look at lib/unsafe.js for examples.

    Extension options
    options.extensions

    List of extensions (Array.<ToMarkdownExtension>). Each ToMarkdownExtension is an object with the same interface as options here.

    Returns

    string — Serialized markdown.

    List of extensions

    Security

    mdast-util-to-markdown will do its best to serialize markdown to match the syntax tree, but there are several cases where that is impossible. It’ll do its best, but complete roundtripping is impossible given that any value could be injected into the tree.

    As Markdown is sometimes used for HTML, and improper use of HTML can open you up to a cross-site scripting (XSS) attack, use of mdast-util-to-markdown and parsing it again later could potentially be unsafe. When parsing markdown afterwards and then going to HTML, use something like hast-util-sanitize to make the tree safe.

    Related

    Contribute

    See contributing.md in syntax-tree/.github for ways to get started. See support.md for ways to get help.

    This project has a code of conduct. By interacting with this repository, organization, or community you agree to abide by its terms.

    License

    MIT © Titus Wormer

    Install

    npm i mdast-util-to-markdown

    DownloadsWeekly Downloads

    2,595,800

    Version

    1.2.6

    License

    MIT

    Unpacked Size

    92.1 kB

    Total Files

    97

    Last publish

    Collaborators

    • wooorm
    • kmck