Skip to main content

Eggmarkdown Syntax Guide

This document is intended as an in-depth guide to the motivation behind and syntax of Eggmarkdown. If you want more information...

Introduction​

What Is Markdown?​

Markdown is a plain text format for writing structured documents developed by John Gruber, with help from Aaron Swartz, and released in 2004.

What distinguishes Markdown from many other lightweight markup syntaxes is its readability. As Gruber wrote:

The overriding design goal for Markdown's formatting syntax is to make it as readable as possible. The idea is that a Markdown-formatted document should be publishable as-is, as plain text, without looking like it's been marked up with tags or formatting instructions. (http://daringfireball.net/projects/markdown/)

What Is Eggmarkdown?​

Since Markdown's initial release, dozens of Markdown implementations were developed, in many languages. Some implementations extended the original Markdown syntax with conventions for footnotes, tables, and other document elements; some allowed Markdown documents to be rendered in formats other than HTML.

Eggmarkdown is an implementation of Markdown that's designed to minimize the pain of coding a responsive email. With Eggmarkdown, we try to stay as close as possible to the most common Markdown implementations (roughly the feature set of Github-flavored Markdown), with a few extensions that are helpful for email.

The Eggmarkdown syntax is intended to make it easy and straightforward to express your desired content and layout — and the Eggmail engine and design library generates high-quality, responsive HTML that's compliant with web and email best practices, and the state of the art in email client rendering.

Eggmarkdown and eggmail are designed to handle the complexity of responsive email design, while exposing precise control and full expressivity.

What Is This Document?​

This document attempts to specify Eggmarkdown syntax unambiguously.

Definitions​

Characters and Lines​

For the purposes of this spec,

Any sequence of characters is a valid Eggmarkdown document.

A character is a Unicode code point, encoded as UTF-8.

A line is a sequence of zero or more characters, excluding line feed (U+000A) and carriage return (U+000D), followed by a line ending or by the end of file.

A line ending is a line feed (U+000A), a carriage return (U+000D) not followed by a line feed, or a carriage return followed by a line feed.

A line containing no characters, or a line containing only spaces (U+0020) or tabs (U+0009), is called a blank line.

A Unicode whitespace character is any code point in the Unicode Zs general category, or a tab (U+0009), line feed (U+000A), form feed (U+000C), or carriage return (U+000D).

Unicode whitespace is a sequence of one or more [Unicode whitespace characters].

A tab is U+0009.

A space is U+0020.

An ASCII control character is a character from U+0000 to U-001F (inclusive) or U+007F.

An ASCII punctuation character is !, ", #, $, %, &, ', (, ), *, +, ,, -, ., / (U+0021–2F), :, ;, <, =, >, ?, @ (U+003A–0040), [, \, ], ^, _, ` (U+005B–0060), {, |, }, or ~ (U+007B–007E).

A Unicode punctuation character is an ASCII punctuation character or anything in the general Unicode categories Pc, Pd, Pe, Pf, Pi, Po, or Ps.

Tabs​

Tabs in lines are not expanded to spaces. However, in contexts where spaces help to define block structure, tabs behave as if they were replaced by spaces with a tab stop of 4 characters.

For example, a tab can be used instead of four spaces to denote an indented code block. (Note, though, that tabs inside the code block are passed through as tabs, not expanded into spaces.)

→foo→baz→→bim
.
<pre><code>foo→baz→→bim
</code></pre>
  →foo→baz→→bim
.
<pre><code>foo→baz→→bim
</code></pre>
    a→a
    ὐ→a
.
<pre><code>a→a
ὐ→a
</code></pre>

In the following example, a continuation paragraph of a list item is indented with a tab; this has exactly the same effect as indentation with four spaces would:

  - foo

→bar
.
<ul>
<li>
<p>foo</p>
<p>bar</p>
</li>
</ul>
- foo

→→bar
.
<ul>
<li>
<p>foo</p>
<pre><code>  bar
</code></pre>
</li>
</ul>

Normally the > that begins a block quote may be followed optionally by a space, which is not considered part of the content. In the following case > is followed by a tab, which is treated as if it were expanded into three spaces. Since one of these spaces is considered part of the delimiter, foo is considered to be indented six spaces inside the block quote context, so we get an indented code block starting with two spaces.

>→→foo
.
<blockquote>
<pre><code>  foo
</code></pre>
</blockquote>
-→→foo
.
<ul>
<li>
<pre><code>  foo
</code></pre>
</li>
</ul>
    foo
→bar
.
<pre><code>foo
bar
</code></pre>
 - foo
   - bar
→ - baz
.
<ul>
<li>foo
<ul>
<li>bar
<ul>
<li>baz</li>
</ul>
</li>
</ul>
</li>
</ul>
#→Foo
.
<h1>Foo</h1>
*→*→*→
.
<hr />

Insecure Characters​

For security reasons, the Unicode character U+0000 must be replaced with the REPLACEMENT CHARACTER (U+FFFD).

Backslash Escapes​

Any ASCII punctuation character may be backslash-escaped:

\!\"\#\$\%\&\'\(\)\*\+\,\-\.\/\:\;\<\=\>\?\@\[\\\]\^\_\`\{\|\}\~
.
<p>!&quot;#$%&amp;'()*+,-./:;&lt;=&gt;?@[\]^_`{|}~</p>

Backslashes before other characters are treated as literal backslashes:

\→\A\a\ \3\φ\«
.
<p>\→\A\a\ \3\φ\«</p>

Escaped characters are treated as regular characters and do not have their usual Markdown meanings:

\*not emphasized*
\<br/> not a tag
\[not a link](/foo)
\`not code`
1\. not a list
\* not a list
\# not a heading
\[foo]: /url "not a reference"
\&ouml; not a character entity
.
<p>*not emphasized*
&lt;br/&gt; not a tag
[not a link](/foo)
`not code`
1. not a list
* not a list
# not a heading
[foo]: /url &quot;not a reference&quot;
&amp;ouml; not a character entity</p>

If a backslash is itself escaped, the following character is not:

\\*emphasis*
.
<p>\<em>emphasis</em></p>

A backslash at the end of the line is a hard line break:

foo\
bar
.
<p>foo<br />
bar</p>

Backslash escapes do not work in code blocks, code spans, autolinks, or raw HTML:

`` \[\` ``
.
<p><code>\[\`</code></p>
    \[\]
.
<pre><code>\[\]
</code></pre>
~~~
\[\]
~~~
.
<pre><code>\[\]
</code></pre>
<http://example.com?find=\*>
.
<p><a href="http://example.com?find=%5C*">http://example.com?find=\*</a></p>
<a href="/bar\/)">
.
<a href="/bar\/)">

But they work in all other contexts, including URLs and link titles, link references, and info strings in fenced code blocks:

[foo](/bar\* "ti\*tle")
.
<p><a href="/bar*" title="ti*tle">foo</a></p>
[foo]

[foo]: /bar\* "ti\*tle"
.
<p><a href="/bar*" title="ti*tle">foo</a></p>
``` foo\+bar
foo
```
.
<pre><code class="language-foo+bar">foo
</code></pre>

Entity and Numeric Character References​

Valid HTML entity references and numeric character references can be used in place of their corresponding Unicode character, with these exceptions:

  • Entity and character references are not recognized in code blocks and code spans.

  • Entity and character references cannot stand in place of special characters that define structural elements in Eggmarkdown. For example, even though &#42; can be used in place of a literal * character, &#42; cannot replace * in emphasis delimiters, bullet list markers, or thematic breaks.

Entity references consist of & + any of the valid HTML5 entity names + ;. The document https://html.spec.whatwg.org/entities.json is used as an authoritative source for the valid entity references and their corresponding code points.

&nbsp; &amp; &copy; &AElig; &Dcaron;
&frac34; &HilbertSpace; &DifferentialD;
&ClockwiseContourIntegral; &ngE;
.
<p>  &amp; © Æ Ď
¾ ℋ ⅆ
∲ ≧̸</p>

Decimal numeric character references consist of &# + a string of 1--7 Arabic digits + ;. A numeric character reference is parsed as the corresponding Unicode character. Invalid Unicode code points will be replaced by the REPLACEMENT CHARACTER (U+FFFD). For security reasons, the code point U+0000 will also be replaced by U+FFFD.

&#35; &#1234; &#992; &#0;
.
<p># Ӓ Ϡ �</p>

Here are some nonentities:

&nbsp &x; &#; &#x;
&#87654321;
&#abcdef0;
&ThisIsNotDefined; &hi?;
.
<p>&amp;nbsp &amp;x; &amp;#; &amp;#x;
&amp;#87654321;
&amp;#abcdef0;
&amp;ThisIsNotDefined; &amp;hi?;</p>

Strings that are not on the list of HTML5 named entities are not recognized as entity references either:

&MadeUpEntity;
.
<p>&amp;MadeUpEntity;</p>

Entity and numeric character references are recognized in any context besides code spans or code blocks, including URLs, link titles, and fenced code block info strings:

<a href="&ouml;&ouml;.html">
.
<a href="&ouml;&ouml;.html">
[foo](/f&ouml;&ouml; "f&ouml;&ouml;")
.
<p><a href="/f%C3%B6%C3%B6" title="föö">foo</a></p>
[foo]

[foo]: /f&ouml;&ouml; "f&ouml;&ouml;"
.
<p><a href="/f%C3%B6%C3%B6" title="föö">foo</a></p>
``` f&ouml;&ouml;
foo
```
.
<pre><code class="language-föö">foo
</code></pre>

Entity and numeric character references are treated as literal text in code spans and code blocks:

`f&ouml;&ouml;`
.
<p><code>f&amp;ouml;&amp;ouml;</code></p>
    f&ouml;f&ouml;
.
<pre><code>f&amp;ouml;f&amp;ouml;
</code></pre>

Entity and numeric character references cannot be used in place of symbols indicating structure.

&#42;foo&#42;
*foo*
.
<p>*foo*
<em>foo</em></p>
&#42; foo

* foo
.
<p>* foo</p>
<ul>
<li>foo</li>
</ul>
foo&#10;&#10;bar
.
<p>foo

bar</p>
&#9;foo
.
<p>→foo</p>
[a](url &quot;tit&quot;)
.
<p>[a](url &quot;tit&quot;)</p>

Blocks and Inlines