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 bund
Installs: 142
Dependents: 1
Suggesters: 0
Security: 0
Stars: 0
Watchers: 2
Forks: 92
Language:JavaScript
This package is auto-updated.
Last update: 2024-01-16 05:23:51 UTC
README
#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.
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.
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.
// 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:
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.
If you want, you can choose to use only a subset of the extensions currently supported:
Markdown.Extra.init(converter, {extensions: ["tables", "fenced_code_gfm", "def_list"]});
See the Extension/Option Reference below for a complete list.
Tables
The following markdown:
| 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:
Item | Value | Qty |
---|---|---|
Computer | $1600 | 5 |
Phone | $12 | 12 |
Pipe | $1 | 234 |
You can also specify a class for the generated tables using
Markdown.Extra.init(converter, {table_class: "table table-striped"})
for instance.
Span-level markdown inside of table cells will also be converted.
Fenced Code Blocks
Fenced code blocks are supported à la GitHub. This markdown:
```
var x = 2;
```
Will be transformed into:
<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:
// 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:
```javascript
var x = 2;
```
Would generate the following html:
<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:
<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.
Footnotes
Here is a footnote[^footnote]. [^footnote]: Here is the *text* of the **footnote**.
becomes:
<p>Here is a footnote<a href="#fn:footnote" id="fnref:footnote" title="See footnote" class="footnote">1</a>.</p> <div class="footnotes"> <hr> <ol> <li id="fn:footnote">Here is the <em>text</em> of the <strong>footnote</strong>. <a href="#fnref:footnote" title="Return to article" class="reversefootnote">↩</a></li> </ol> </div>
Special Attributes
You can add class and id attributes to headers and gfm fenced code blocks.
``` {#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:
ASCII | HTML | |
---|---|---|
Single backticks | 'Isn't this fun?' |
‘Isn’t this fun?’ |
Quotes | "Isn't this fun?" |
“Isn’t this fun?” |
Dashes | This -- is an en-dash and this --- is an em-dash |
This – is an en-dash and this — is an em-dash |
Newlines
Newlines à la GitHub (without the need of two white spaces):
Roses are red Violets are blue
becomes:
<p>Roses are red <br> Violets are blue</p>
Strikethrough
Strikethrough à la GitHub:
~~Mistaken text.~~
becomes:
<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.
Extension | Description |
---|---|
fenced_code_gfm | GFM fenced code blocks |
tables | Pretty tables! |
def_list | Definition lists |
attr_list | Special attributes list for headers and fenced code blocks |
footnotes | Footnotes |
smartypants | SmartyPants |
newlines | GFM newlines |
strikethrough | GFM strikethrough |
smart_strong | No strong emphasis in the middle of words |
abbr | Abbreviations |
fenced_code | PHP Markdown Extra fenced code blocks |
Option | Description |
---|---|
table_class | Class added to all markdown tables. Useful when using frameworks like bootstrap. |
highlighter | Code highlighter. Must be one of highlight and prettify for now |
Italicized extensions are planned, and will be added in roughly the order shown
See PHP Markdown Extra's documentation 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.
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.
##License
See LICENSE.txt