Features in Detail

Digging Deeper

Compatible

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.

Fast

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
(chars)
MarkdownSharp
(ms)
MarkdownDeep
(ms)
Factor
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 window.

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>
</div>

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.
  2. The user clicks on the edit link which takes them to a page to edit that section.
  3. 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.
  4. The user edits the section.
  5. 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.