Markdown Processor

Overview

Steelkilt contains a unique Markdown processor that was written with high performance and syntax flexibility in mind.

Steelkilt supports the original Markdown syntax, which is documented at the website hosted by John Gruber, the inventor of the Markdown publishing format:

https://daringfireball.net/projects/markdown/syntax

But note the following differences, outlined below.

Differences

Original FeatureSteelkilt Implementation
Markdown formatting syntax is not processed within block-level HTML tags.You can use Markdown formatting syntax inside block-level HTML tags.
Automatic escaping for special characters, using named HTML entities.

Example:

AT&T will be translated to AT&T
Named HTML entities are not supported in EPUB.

Special characters will be escaped using decimal-numbered HTML entities.

Example:

AT&T will be translated to AT&T
SETEXT-style headers supported.

Example:

This is an H1
===========
Not supported.

Use open/unterminated ATX-style headers instead.

Example:

# This is an H1
Closed/terminated ATX-style headers supported.

Example:

# This is an H1 #
Not supported.

Use open/unterminated ATX-style headers instead.

Example:

# This is an H1
Blockquotes nested with > >.
Blockquotes can be nested with:

> > (including separating space)
>> (no separating space)
Randomized decimal and hex-entity encoding for email addresses.Not supported.

Not necessary for EPUBs.
No Markdown syntax for the HTML <del> tag.Steelkilt builds on the original Markdown syntax by adding support for the HTML <del> tag, used to indicate a deleted portion of a document.

Wrap deleted text in single tildes (~) or double tildes (~~) to indicate deleted text.

Example:

This line contains ~deleted text~ and ~~deleted text~~.

Will become:

<p>This line contains <del>deleted text</del> and <del>deleted text</del></p>

But note that use of single and double tildes must be balanced, such that ~ and ~~ must be used in matching pairs. For example:

This line contains ~deleted text~~ and ~~deleted text~.

Markdown Syntax and the Steelkilt Text Editor

Text Editor will change the appearance of the Document or Chapter text when Markdown syntax or HTML tags are used:

  • Valid Markdown tags are displayed in red
  • Heading 1 to 6 will be shown in bold, with a proportional increase in point size
  • Bold text will be shown in bold
  • Emphasized text will be shown in italics
  • Deleted text will be shown in strikethrough
  • Indented and inline code will be shown in the current Code Editor font and color scheme
  • HTML tags will be shown in the current Code Editor font and color scheme

Tip

Always terminate Markdown structures (such as lists, blockquotes and tag groups) with two carriage returns.

This is necessary because these structures can contain empty lines — and subsequent content, such as text and headings, may be unnecessary grouped with the proceeding structure if all that separates it from the structure is a single carriage return.

Markdown Processing

Markdown appearing in Text Editor is processed into XHTML (with all non-EPUB-friendly symbols HTML encoded) automatically during EPUB Generation.

HTML tags in Text Editor are not re-processed during EPUB Generation.

If you do not want to use Markdown in your text, you can disable Markdown processing in Document and Chapter Settings.


Related Topics