remark-stringify

Compiler for unified. Stringifies an MDAST syntax tree to markdown. Used in the remark processor. Can be extended to change how markdown is compiled.

Installation

npm:

npm install remark-stringify

Usage

var unified = require('unified');
var createStream = require('unified-stream');
var parse = require('remark-parse');
var toc = require('remark-toc');
var stringify = require('remark-stringify');

var processor = unified()
  .use(parse)
  .use(toc)
  .use(stringify, {
    bullet: '*',
    fence: '~',
    fences: true,
    incrementListMarker: false
  });

process.stdin
  .pipe(createStream(processor))
  .pipe(process.stdout);

Table of Contents

• API
  • processor.use(stringify)
  • stringify.Compiler
• Extending the Compiler
  • Compiler#visitors
  • function visitor(node[, parent])
• License

API

processor.use(stringify)

Configure the processor to stringify MDAST syntax trees to markdown.

options

Options are passed later through processor.stringify(), processor.process(), or processor.pipe(). The following settings are supported:

• gfm (boolean, default: true):

  • Escape pipes (|, for tables)
  • Escape colons (:, for literal URLs)
  • Escape tildes (~, for strike-through)

• commonmark (boolean, default: false):

  • Compile adjacent blockquotes separately
  • Escape more characters using slashes, instead of as entities

• pedantic (boolean, default: false):

  • Escape underscores in words

• entities (string or boolean, default: false):

  • true — Entities are generated for special HTML characters (& > &) and non-ASCII characters (© > ©). If named entities are not (widely) supported, numbered character references are used (’ > ’)

  • 'numbers' — Numbered entities are generated (& > &) for special HTML characters and non-ASCII characters

  • 'escape' — Special HTML characters are encoded (& > &, ’ > ’), non-ASCII characters not (ö persists)

• setext (boolean, default: false) — Compile headings, when possible, in Setext-style: using = for level one headings and - for level two headings. Other heading levels are compiled as ATX (respecting closeAtx)

• closeAtx (boolean, default: false) — Compile ATX headings with the same amount of closing hashes as opening hashes

• looseTable (boolean, default: false) — Create tables without fences (initial and final pipes)

• spacedTable (boolean, default: true) — Create tables without spacing between pipes and content

• paddedTable (boolean, default: true) — Create tables with padding in each cell so that they are the same size

• fence ('~' or '`', default: '`') — Fence marker to use for code blocks

• fences (boolean, default: false) — Stringify code blocks without language with fences

• bullet ('-', '*', or '+', default: '-') — Bullet marker to use for unordered list items

• listItemIndent ('tab', 'mixed' or '1', default: 'tab')

  How to indent the content from list items:

  • 'tab': use tab stops (4 spaces)
  • '1': use one space
  • 'mixed': use 1 for tight and tab for loose list items

• incrementListMarker (boolean, default: true) — Whether to increment ordered list item bullets

• rule ('-', '*', or '_', default: '*') — Marker to use for thematic breaks (horizontal rules)

• ruleRepetition (number, default: 3) — Number of markers to use for thematic breaks (horizontal rules). Should be 3 or more

• ruleSpaces (boolean, default true) — Whether to pad thematic break (horizontal rule) markers with spaces

• strong ('_' or '*', default '*') — Marker to use for importance

• emphasis ('_' or '*', default '_') — Marker to use for emphasis

stringify.Compiler

Access to the raw compiler, if you need it.

Extending the Compiler

If this plug-in is used, it adds a Compiler constructor to the processor. Other plug-ins can change and add visitors on the compiler’s prototype to change how markdown is stringified.

The below plug-in modifies a visitor to add an extra blank line before level two headings.

module.exports = gap;

function gap() {
  var Compiler = this.Compiler;
  var visitors = Compiler.prototype.visitors;
  var heading = visitors.heading;

  visitors.heading = heading;

  function heading(node) {
    return (node.depth === 2 ? '\n' : '') + heading.apply(this, arguments);
  }
}

Compiler#visitors

An object mapping node types to visitors.

function visitor(node[, parent])

Stringify node.

Parameters

• node (Node) — Node to compile
• parent (Node, optional) — Parent of node

Returns

string, the compiled given node.

License

MIT © Titus Wormer