README.markdown

PHP Markdown Extra Extended

An fork of the PHP Markdown (Extra) project (PME), extended with extra syntax, especially focused on adding support for more HTML attributes to outputted HTML, and for outputting HTML5.

Changes to syntax from PHP Markdown (Extra)

Unless explicitly specified, existing Markdown markup works exactly as it did before. The orginal syntax is documentated here:

• Markdown syntax
• Markdown Extra syntax

Line break generates a <br />

In PME, when you want to insert a <br /> break tag using Markdown, you end a line with two or more spaces, then type return. This turned out to be more annoying than helpful in my projects, so now you just have to type return. This is also how Markdown works with GFM.

Two returns does not insert a <br />, but instead creates a new paragraph as usual.

Support for cite attribute on blockquotes

It is now possible to add the optional cite attribute to the blockquote element.

The new, optional, syntax is:

> (cite url) Cited content follows ...

Example:

> (http://www.whatwg.org/) Content inside a blockquote must be quoted 
> from another source, whose address, if it has one, 
> may be cited in the `cite` attribute.

Will result in the following HTML:

<blockquote cite="http://www.whatwg.org/">
<p>Content inside a blockquote must be quoted 
from another source, whose address, if it has one, 
may be cited in the `cite` attribute.</p>
</blockquote>

Breaking changes from PME

The existing rules for and formatting options for blockquotes still apply. There is one small breaking changes with this addition. If your quote starts with ( you have two have at least two spaces between the initial > and the (. E.g.:

>  (Ut brisket flank salami.) Cow cupidatat ex t-bone sirloin id. 
> Sunt flank pastrami spare ribs sint id, nulla nisi.

Will result in the following HTML:

<blockquote>
  <p>(Ut brisket flank salami.) Cow cupidatat ex t-bone sirloin id.<br>
  Sunt flank pastrami spare ribs sint id, nulla nisi.</p>
</blockquote>

Fenced code block with language support and alternating fence markers (```)

It is now possible to specify the language type of a code block, and use an alternatinge fence markers (```), enabling the same syntax as that of GFM.

This addition follows the suggested way to specify language by W3C.

Example:

~~~html
<p>Ut brisket flank salami.  Cow cupidatat ex t-bone sirloin id.</p>
~~~

Using alternative fence markers:

```html
<p>Ut brisket flank salami.  Cow cupidatat ex t-bone sirloin id.</p>
```

Both will output the following HTML:

<pre><code class="language-html">
<p>Ut brisket flank salami.  Cow cupidatat ex t-bone sirloin id.</p>
</code></pre>

Usage

You need both the markdown.php and the markdown_extended.php files, but only needs to include markdown_extended.php.

require_once('markdown_extended.php');

// Convert markdown formatted text in $markdown to HTML
$html = MarkdownExtended($markdown);

There are some new settings that can be applied to the parser.

Defining default CSS classes for all tags of a specific type

It is now possible to append default CSS classes to all tags of a specific type, unless they are nested inside a <code> tag. Existing CSS classes will not be overwritten.

It is done through the second argument to the MarkdownExtended function:

$html = MarkdownExtended($markdown, array('tag' => 'css classes', 'anotherTag' => 'css classes'));

In the following example we add support for Googles Javascript code prettifier by adding the prettyprint class to all <pre> tags.

// Always add a 'prettyprint' to <pre> elements
$html = MarkdownExtended($markdown, array('pre' => 'prettyprint'));