Skip to content

Latest commit

 

History

History
364 lines (237 loc) · 10 KB

readme.md

File metadata and controls

364 lines (237 loc) · 10 KB
Raw

remark-stringify

Build Coverage Downloads Size Chat Sponsors Backers

Compiler for unified. Stringifies mdast syntax trees to Markdown. Used in the remark processor but can be used on its own as well. Can be extended to change how Markdown is compiled.

Sponsors



🥇 ZEIT

🥇 Gatsby

🥉 Compositor

Holloway



You?

Read more about the unified collective on Medium »

Install

npm:

npm install remark-stringify

Use

var unified = require('unified')
var createStream = require('unified-stream')
var html = require('rehype-parse')
var rehype2remark = require('rehype-remark')
var stringify = require('remark-stringify')

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

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

See unified for more examples »

Table of Contents

API

See unified for API docs »

processor().use(stringify[, options])

Configure the processor to stringify mdast syntax trees to Markdown.

options

Options can be passed directly, or passed later through processor.data().

options.gfm

Stringify with the required escapes for GFM compatible Markdown (boolean, default: true).

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

Stringify for CommonMark compatible Markdown (boolean, default: false).

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

Stringify for pedantic compatible markdown (boolean, default: false).

  • Escape underscores in words
options.entities

How to stringify 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)
options.setext

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

options.closeAtx

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

options.looseTable

Create tables without fences: initial and final pipes (boolean, default: false).

options.spacedTable

Create tables with a space between a pipe and content (boolean, default: true).

options.paddedTable

Create tables with more spaces so that all cells in a column align (boolean, default: true).

options.stringLength

Function passed to markdown-table to detect the length of a table cell (Function, default: s => s.length). Used to pad tables.

options.fence

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

options.fences

Create code blocks with a fence instead of indentation if they have no info string (boolean, default: false).

When false, code blocks are indented. Code blocks with an info string are always fenced.

options.bullet

Marker to use for the bullet of unordered list items ('-', '*', or '+', default: '-').

options.listItemIndent

Style of indentation for list items ('tab', 'mixed' or '1', default: 'tab').

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

Increment ordered list item numbers (boolean, default: true).

When false, all list item numbers will be the same.

options.rule

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

options.ruleRepetition

Number of markers to use for thematic breaks / horizontal rules (number, default: 3). Musts be 3 or more.

options.ruleSpaces

Place a space between thematic break (horizontal rule) markers (boolean, default true).

options.strong

Marker to use for importance ('_' or '*', default '*').

options.emphasis

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

stringify.Compiler

Access to the compiler, if you need it.

Extending the Compiler

If the remark-stringify plugin is used, it adds a Compiler constructor function to the processor. Other plugins can add visitors to its prototype to change how Markdown is compiled.

The below plugin modifies a visitor to add an extra blank line before headings with a rank of 2.

module.exports = gap

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

  visitors.heading = heading

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

Compiler#visitors

Map of types to visitors (Object.<Function>).

function visitor(node[, parent])

Stringify node.

Parameters
  • node (Node) — Node to compile
  • parent (Parent, optional) — Parent of node. Not available on the root node
Returns

string — Compiled given node.

Contribute

See contributing.md in remarkjs/.github for ways to get started. See support.md for ways to get help. Ideas for new plugins and tools can be posted in remarkjs/ideas.

A curated list of awesome remark resources can be found in awesome remark.

This project has a Code of Conduct. By interacting with this repository, organisation, or community you agree to abide by its terms.

License

MIT © Titus Wormer