caolan/wmd

wanton markdown - a markdown parser based on showdown

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.

wmd's Issues

Standalone metadata preprocessor

@caolan, I would like to use your metadata preprocessor, but I would like to use it with the marked engine. Are you interested in splitting it out into a standalone repo? Or would you like me to?

FWIW, I wrote a number of other pre-processors that I'm using with the marked engine. My current plan is to adopt the same preprocessor API that you are using (taking and returning an object with a markdown property).

Metadata parsing does not work on Windows

https://github.com/caolan/wmd/blob/master/lib/preprocessors.js uses \n as the newline character and thus fails to correctly parse metadata lines on Windows.

Add npm test

Patch available here, https://gist.github.com/harsha-mudi/11295520

metadata example in documentation lacks newlines

It seems some newlines are missing in this text (the output as displayed in guthub website):

property1: some value property2: multi line value