mdast-deku v1.0.0
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
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
9 years ago