MarkdownDeep - Features In Detail

Digging Deeper


MarkdownDeep implements all the features defined by Markdown, and

includes a comprehensive set of unit test cases to ensure this compatiblity is maintained.

Although MarkdownDeep produces equivalent HTML to other Markdown implementations, it makes no

attempt to match the whitespace of those implementations. Also, it may escape some HTML entities

differently (eg: " instead of actual quote characters), but in the end the output

is equivalent.


The .NET version of MarkdownDeep is fast - typically 15x faster than MarkdownSharp.

The following benchmarks compare MarkdownDeep and MarkdownSharp. The same input files and iterations counts were used in both cases. The benchmark program and input files are included in the MarkdownDeep source code repository.

These tests are the same as those included in the MarkdownSharp code base however the iterations counts have been increased on the larger tests to get a more accurate measure. Also, an even larger, plain text (no markdown syntax) file has been added to the test.

Test Input Length
markdown-example-short-1.text 475 0.721 0.071 x10.1
markdown-example-medium-1.text 2,356 2.755 0.164 x16.8
markdown-example-long-2.text 27,737 30.2 1.58 x19.11
markdown-readme.text 11,416 14.3 1.3 x11.0
markdown-readme.8.text 91,342 114.7 6.2 x18.5
markdown-readme.32.text 365,374 450.0 26.2 x17.2
long_plain_text.text 698,880 453.8 29.1 x15.6

Machine spec: 2009 13" MacBook Pro (Core 2 Duo), 4GB RAM, Windows 7 x64.

JavaScript Edition

The JavaScript port of MarkdownDeep is 100% compatible with the .NET edition, effectively

eliminating the problem of different results on server and client.

Performance of the JavaScript edition is highly dependant on the browser in question. In Chrome,

Safara and Firefox performance is comparable to Showdown. In the current release of Internet

Explorer, the performance is considerably worse but for typical usage performance is more than

adequate. The technology preview of IE9 addresses these performance issues and initial testing

shows MarkdownDeep performs similarly to the other browsers.

The JavaScript edition comes in both full source code and a minifed version at about 30k (minification

by MiniME of course).

Client Side Editor

In addition to the JavaScript port of the text transformation library, MarkdownDeep also includes

a client side editor with real-time preview, toolbar, short-cut keys, help, resizer bar, auto-indent

and tab/shift-tab block indent.

The editor comes in two parts:

  • MarkdownDeepEditor - the core editor functionality that implements preview generation, editor commands and keyboard shortcuts.

  • MarkdownDeepEditorUI - a jQuery based toolbar, popup help and resize bar.

To see the editor in action, click here.

Markdown Extra Enhancements

MarkdownDeep optionally supports all of the PHP Markdown Extra extensions, including:

  • Markdown in HTML blocks

  • Fenced code blocks

  • Header id attributes

  • Simple tables

  • Definition lists

  • Footnotes

  • Abbreviations

Safe Mode

MarkdownDeep includes optional built-in support for sanitized HTML output.

Markdown is an excellent format for user entered rich content. Unfortunately allowing

complete support for Markdown creates security risks and opens one's site to the risk of

XSS scripting attacks.

Normally this would be addressed by post-processing the output with a separate HTML

sanitizer. With MarkdownDeep, this support is built-in and saves making another pass

over the generated content.

MarkdownDeep uses a built-in white list of allowable HTML tags. All other HTML tags

will be automatically escaped.

Markdown is an excellent format for authoring blog articles. However, generating RSS

feeds that work with all readers requires replacing relative URL links with

fully qualified links.

By supplying a base URL, MarkdownDeep can automatically qualify these relative links.

MarkdownDeep can automatically add target="_blank" to links so they open in a new

window or tab.

This can be enabled for fully-qualified links only. In this mode

relative links to your own site open in-place whereas links to other sites open in a new


New window links are also useful when generating previews during editing. By having

all links in a preview open in a new window an author can check her links work without

actually leaving the page on which she's editing her post.

MarkdownDeep can optionally add rel="nofollow" to all links. Use this when accepting

user entered Markdown to reduce the benefits comment spam.

Image Size Attributes

Markdown doesn't provide a way to specify the dimensions of embedded images (at least not

without resorting to HTML).

MarkdownDeep can automatically get the dimensions of images that are on the local machine

  • either automatically by providing a folder location in which to look for the images, or

by writing a custom handler that supplies image sizes for a specified URL.

Use this to prevent your page's text jumping around while the images load.

Titled Images

Often when authoring content with Markdown it's desirable to embed an image that's centered

and has a caption or title below it. Markdown itself doesn't provide support for this and

simply wraps the img tag in a regular paragraph that can't be styled with CSS.

MarkdownDeep has a feature where a paragraph that contains just an image

can be automatically wrapped in a div with a specified class name. Also, in this mode if the

image has a title it is displayed in a paragraph below the image.

So this Markdown:

![Image Alt Text](image.png "Image Caption")

can be rendered as:

<div class="figure">

    <img src="image.png" alt="Image Alt Text" title="Image Caption" />

    <p>Image Caption</p>


and styled with:

div.figure {}

div.figure img {}

div.figure p {}

Section Splitting

MarkdownDeep can split Markdown content into sections for easier editing. This functionality comes in two parts:

  • The ability to split a Markdown document at each heading (and support for rejoining the

    split content after editing).

  • The ability to render additional content before or after each section.

This works as follows:

  1. When the page is in edit mode, each heading is prefixed by a link to edit that section. The link can

include a section number that will be calculated by MarkdownDeep as it renders the page.

  1. The user clicks on the edit link which takes them to a page to edit that section.

  2. The server uses MarkdownDeep to split the original Markdown content into sections and uses the link's

section number to extract the Markdown to be edited.

  1. The user edits the section.

  2. On saving the section, the original content is split into sections again, and the section being edited

is replaced with the new content.

MarkdownDeep creates new sections at top-level h1, h2 and h3 headings. Headings within other

block level constructs are not used for section breaks.