mdast-deku

mdast-deku

mdast-deku compiles markdown to Deku components. Built on mdast, an extensively tested and pluggable parser.

Installation

npm:

npm install mdast-deku

Table of Contents

• Command line

• Programmatic

  • mdast.use(deku, options)

• Configuration

• CommonMark

• Integrations

• License

Programmatic

mdast.use(deku, options)

Parameters

• deku — This plugin;
• options (Object?) — See below.

Let’s say example.js looks as follows:

import element from 'virtual-element';
import {render,tree} from 'deku';
import mdast from 'mdast';
import mdastDeku from 'mdast-deku';

var MdastComp = {
  InitialState (props) {
      return { text: '# hello world' };
  },
  render(component, setState) {
    const {state} = component;
    function onChange(e) {
      setState({ text: e.target.value });
    }
    return (<div>
        <textarea
            value={state.text}
            onChange={onChange} />
        <div id='preview'>
            {mdast().use(mdastDeku).process(state.text)}
        </div>
    </div>);
  }
};

const app = tree(<MdastComp />);
app.render(document.getElementById('app'));

Configuration

All options, including the options object itself, are optional:

• entities (true, 'numbers', or 'escape', default: true) — How to encode non-ASCII and HTML-escape characters: the default generates named entities (& > &); 'numbers' generates numbered entities (& > &), and 'escape' only encodes characters which are required by HTML to be escaped: &, <, >, ", ', and `, leaving non-ASCII characters untouched.

• sanitize (boolean, default: false) — Whether or not to allow the use of HTML inside markdown.

These can passed to mdast.use() as a second argument.

You can define these in .mdastrc or package.json files too. An example .mdastrc file could look as follows:

{
  "plugins": {
    "html": {
        "sanitize": false,
        "xhtml": false,
        "entities": "numbers"
    }
  },
  "settings": {
    "commonmark": true
  }
}

Where the object at plugins.html are the options for mdast-deku. The object at settings determines how mdast parses markdown code. Read more about the latter on mdast’s readme.

CommonMark

You still need to set commonmark: true in mdast’s options

CommonMark support is a goal but not (yet) a necessity. There are some (roughly 115 of 550, relating to inline precedence, lists, emphasis and strongness) issues which I’d like to cover in the future. Note that this sounds like a lot, but they have to do with obscure differences which do not often occur in the real world. Read more on some of the reasoning in doc/commonmark.md.

Integrations

mdast-deku works great with:

• mdast-toc, which generates tables of contents;

• mdast-github, which generates references to GitHub issues, PRs, users, and more;

• mdast-comment-config and mdast-yaml-config, which specify how HTML is compiled in the document itself;

• ...and more.

All mdast nodes can be compiled to deku. In addition, mdast-deku looks for an attributes object on each node it compiles and adds the found properties as deku attributes on the compiled tag.

License

MIT © Titus Wormer, modified by Tom MacWright and Mapbox and Ulrik Augustsson