wmd

A full-featured markdown processor based on Showdown

npm install wmd
27 downloads in the last week
59 downloads in the last month

WMD

A Markdown parser for CommonJS (and node.js) based on the excellent Showdown.

Essentially WMD, is just a wrapper around Showdown, with a few hooks for preprocessing, and some default preprocessors and postprocessors.

Example

var wmd = require('wmd');

var html = wmd('Markdown *rocks*.');
console.log(html);

Documentation

wmd(markdown, options)

  • markdown - A string containing Markdown.
  • options - (optional) An object containing options (see options section)

The main function for converting Markdown to HTML, and normally the only function you'll need ot use. Applies all preprocessors defined in options before passing the result to Showdown for the final rendering.

By default, the underscores and metadata preprocessors are used.

This function returns a doc object. The contents of the doc object may differ depending on the preprocessors used, but will always contain the following:

  • doc.html - The final HTML output of the conversion.
  • doc.markdown - The markdown text passed to the processsor after all preprocesor functions have been applied.
  • doc.raw - The raw string before preprocessors were applied.

The string representation of a doc object (doc.toString()) is the same as doc.html.

wmd.preprocessors

An object containing core preprocessor functions:

  • underscores - code-friendly underscore processing taken from GitHub Flavored Markdown. This means the bar in foo_bar_baz does not get emphasis.
  • fencedCodeBlocks - GitHub style fenced code blocks
  • yamlFrontMatter - Jekyll style YAML front matter for metadata
  • metadata - takes metatdata information from the top of a markdown file and adds it to doc.metadata.

    property1: some value
    property2: multi
               line
               value
    
    # Markdown goes here
    

    Would result in the following doc object:

    {
        metadata: {
            property1: "some value",
            property2: "multi\nline\nvalue"
        },
        html: "<h1>Markdown goes here</h1>",
        markdown: "# Markdown goes here",
        raw: "property1: some value\nproperty2: multi\nline\nvalue\n\n# Markdown goes here"
    }
    

Adding preprocessors to wmd:

var wmd = require('wmd');
var html = wmd('Markdown *rocks*.', {
    preprocessors: [
        function (doc) {
            doc.markdown += '.. even more!';
            return doc;
        }
    ]
});

By default, the underscores and metadata preprocessors will be used.

wmd.postprocessors

An object containing core postprocessor functions:

  • jsdom - uses jsdom to add doc.window containing the HTML generated from markdown
  • first_para - adds doc.first_para containing the text in the first p tag
  • heading - adds doc.heading containing the text in the first h1 tag

Adding postprocessors to wmd:

var wmd = require('wmd');
var html = wmd('Markdown *rocks*.', {
    postprocessors: [
        function (doc) {
            doc.html += '<b>more html stuff</b>';
            return doc;
        }
    ]
});

By default, no postprocessors will be used.

wmd.processor(markdown)

  • markdown - A string containing Markdown.

The function which performs the conversion from markdown to html. By default this is just Showdown's makeHTML function.

wmd.preprocess(doc, options)

  • doc - A doc object
  • options - (optional) An object containing options (see options section)

Applies the preprocessor functions defined in options to the doc (usually updating doc.markdown, sometimes adding new properties) before the doc is passed to the processor.

wmd.postprocess(doc, options)

  • doc - A doc object
  • options - (optional) An object containing options (see options section)

Applies the postprocessor functions defined in options to the doc.

wmd.readOptions(options)

  • options - (optional) An object containing options (see options section)

You would not normally need to call this directly. This function adds default options to those passed to the main wmd function.

Options

  • preprocessors - An array of functions which can transform the document before its passed to the processor function. By default the underscores and metadata preprocessors are used.
  • postprocessors - An array of functions which can transform the document after its been passed to the processor function. By default, no postprocessors are used.
npm loves you