jmcmanus/pagedown-extra

This is a collection of Pagedown plugins to enable support for Markdown Extra syntax. Open demo/demo.html to try it yourself. To run the tests, just open spec/SpecRunner.html in your browser. Or, to run a browser-less test from the command line as travis-ci would, run bundle install followed by bundle exec rake. You'll need Ruby and the rake gem if you use the second method.

Overview

This is a collection of Pagedown plugins to enable support for Markdown Extra syntax. Open demo/demo.html to try it yourself. To run the tests, just open spec/SpecRunner.html in your browser. Or, to run a browser-less test from the command line as travis-ci would, run bundle install followed by bundle exec rake. You'll need Ruby and the rake gem if you use the second method., _(*1)

, _(*2)

Usage

First, make sure you have the most recent version of Pagedown (as of Feb 3, 2013), as it adds more powerful hooks that this implementation relies on., _(*3)

In order to use the extensions, you'll need to include Markdown.Extra.js after the Pagedown sources. Check out the demo for a working example., _(*4)

// create a pagedown converter - regular and sanitized versions are both supported
var converter = new Markdown.Converter();
// tell the converter to use Markdown Extra
Markdown.Extra.init(converter);
// convert some markdown
var html = converter.makeHtml("| A | B |\n| :-: | :-: |\n| 1 | 2 |");

To use this in Node.js with Pagedown:, _(*5)

var pagedown = require("pagedown");
var converter = new pagedown.Converter();
var pagedownExtra = require("pagedown-extra");
pagedownExtra.init(converter);

If you're using multiple converters on the same page, you can just call Markdown.Extra.init once for each converter and you're all set., _(*6)

If you want, you can choose to use only a subset of the extensions currently supported:, _(*7)

Markdown.Extra.init(converter, {extensions: ["tables", "fenced_code_gfm", "def_list"]});

See the Extension/Option Reference below for a complete list., _(*8)

Tables

The following markdown:, _(*9)

| Item      | Value | Qty |
| --------- | -----:|:--: |
| Computer  | $1600 | 5   |
| Phone     |   $12 | 12  |
| Pipe      |    $1 |234  |

will render to something like this depending on how you choose to style it:, _(*10)

You can also specify a class for the generated tables using Markdown.Extra.init(converter, {table_class: "table table-striped"}) for instance., _(*11)

Span-level markdown inside of table cells will also be converted., _(*12)

Fenced Code Blocks

Fenced code blocks are supported à la GitHub. This markdown:, _(*13)

```
var x = 2;
```

Will be transformed into:, _(*14)

<pre>
    <code>var x = 2;</code>
</pre>

You can specify a syntax highlighter in the options object passed to Markdown.Extra.init, in order to generated html compatible with either google-code-prettify or Highlight.js:, _(*15)

// highlighter can be either `prettify` or `highlight`
Markdown.Extra.init(converter, {highlighter: "prettify"});

If either of those is specified, the language type will be added to the code tag, e.g. <code class="language-javascript">, otherwise you just get the standard <code class="javascript"> as in PHP Markdown Extra. If prettify is specified, <pre> also becomes <pre class="prettyprint">. Otherwise, the markup is the same as what Pagedown produces for regular indented code blocks. For example, when using {highlighter: "prettify"} as shown above, this:, _(*16)

```javascript
var x = 2;
```

Would generate the following html:, _(*17)

<pre class="prettyprint">
    <code class="language-javascript">var x = 2;</code>
</pre>

Definition Lists

Term 1
:   Definition 1

Term 2
:   This definition has a code block.

        code block

becomes:, _(*18)

<dl>
  <dt>Term 1</dt>
  <dd>
    Definition 1
  </dd>
  <dt>Term 2</dt>
  <dd>
    This definition has a code block.
    <pre><code>code block</code></pre>
  </dd>
</dl>

Definitions can contain both inline and block-level markdown., _(*19)

Footnotes

Here is a footnote[^footnote].

  [^footnote]: Here is the *text* of the **footnote**.

becomes:, _(*20)

Here is a footnote., (*21)








Here is the text of the footnote. ↩

Special Attributes

You can add class and id attributes to headers and gfm fenced code blocks., _(*22)

``` {#gfm-id .gfm-class}
var foo = bar;
```

## A Header {#header-id}

### Another One ### {#header-id .hclass}

Underlined  {#what}
==========

SmartyPants

SmartyPants extension converts ASCII punctuation characters into "smart" typographic punctuation HTML entities. For example:, _(*23)

Newlines

Newlines à la GitHub (without the need of two white spaces):, _(*24)

Roses are red
Violets are blue

becomes:, _(*25)

<p>Roses are red <br>
Violets are blue</p>

Strikethrough

Strikethrough à la GitHub:, _(*26)

~~Mistaken text.~~

becomes:, _(*27)

<p><del>Mistaken text.</del></p>

Extension / Option Reference

You can enable all of the currently supported extensions with {extensions: "all"}. This is also the default. If specifying multiple extensions, you must provide them as an array. Here is a list of the current and planned options and extensions. I've chosen to use the same naming scheme as the excellent Python Markdown library., _(*28)

Italicized extensions are planned, and will be added in roughly the order shown, _(*29)

See PHP Markdown Extra's [documentation][12] for a more complete overview of syntax. In situations where it differs from how things are done on GitHub -- alignment of table headers, for instance -- I've chosen compatibility with gfm, which seems to be quickly becoming the most widely used markdown implementation., _(*30)

Special Characters

Markdown Extra adds two new special characters, | and :, that can be escaped by preceding them with \. Doing so will cause the escaped character to be ignored when determining the extent of code blocks and definition lists., _(*31)

License

See LICENSE.txt, _(*32)