remark-stringify

What is remark-stringify?

The remark-stringify package is a plugin for the remark ecosystem that allows you to serialize Markdown Abstract Syntax Trees (ASTs) into Markdown text. It is commonly used in conjunction with other remark plugins to process and transform Markdown content programmatically.

What are remark-stringify's main functionalities?

Basic Markdown Serialization

This feature allows you to convert a Markdown AST into a Markdown string. The example demonstrates how to serialize a simple AST representing a paragraph with the text 'Hello, world!'.

const remark = require('remark');
const stringify = require('remark-stringify');

const markdownAST = {
  type: 'root',
  children: [
    { type: 'paragraph', children: [{ type: 'text', value: 'Hello, world!' }] }
  ]
};

const markdownText = remark().use(stringify).stringify(markdownAST);
console.log(markdownText); // Outputs: 'Hello, world!\n'

Customizing Output

This feature allows you to customize the output format of the serialized Markdown. The example shows how to set options for bullet points and fenced code blocks.

const remark = require('remark');
const stringify = require('remark-stringify');

const markdownAST = {
  type: 'root',
  children: [
    { type: 'paragraph', children: [{ type: 'text', value: 'Hello, world!' }] }
  ]
};

const markdownText = remark()
  .use(stringify, { bullet: '*', fences: true })
  .stringify(markdownAST);
console.log(markdownText); // Outputs: 'Hello, world!\n'

Handling Complex ASTs

This feature demonstrates how to handle more complex ASTs, including headings, paragraphs, and lists. The example shows how to serialize an AST with multiple types of nodes.

const remark = require('remark');
const stringify = require('remark-stringify');

const markdownAST = {
  type: 'root',
  children: [
    { type: 'heading', depth: 1, children: [{ type: 'text', value: 'Title' }] },
    { type: 'paragraph', children: [{ type: 'text', value: 'This is a paragraph.' }] },
    { type: 'list', ordered: false, children: [
      { type: 'listItem', children: [{ type: 'paragraph', children: [{ type: 'text', value: 'Item 1' }] }] },
      { type: 'listItem', children: [{ type: 'paragraph', children: [{ type: 'text', value: 'Item 2' }] }] }
    ] }
  ]
};

const markdownText = remark().use(stringify).stringify(markdownAST);
console.log(markdownText); // Outputs: '# Title\n\nThis is a paragraph.\n\n* Item 1\n* Item 2\n'

Other packages similar to remark-stringify

markdown-it

Markdown-it is a fast and flexible Markdown parser that can also be used to render Markdown from an AST. It offers a wide range of plugins and customization options, making it a versatile alternative to remark-stringify.

marked

Marked is a low-level Markdown compiler that allows for extensive customization. It is known for its speed and flexibility, making it a good choice for projects that require fine-grained control over Markdown rendering.

showdown

Showdown is a bidirectional Markdown to HTML converter that can also be used to serialize Markdown from an AST. It is easy to use and offers a range of extensions for additional functionality.

README

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 parse = require('remark-parse');
var toc = require('remark-toc');
var stringify = require('remark-stringify');

process.stdin
    .pipe(unified())
    .use(markdown)
    .use(toc)
    .use(html)
    .pipe(process.stdout, {
        'bullet': '*',
        'fence': '~',
        'fences': true,
        'incrementListMarker': false
    });

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.

• 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.

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

    /* Add a visitor for `heading`s. */
    visitors.heading = function (node) {
        return (node.depth === 2 ? '\n' : '') + heading.apply(this, arguments);
    };
}

module.exports = gap;

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