Deployed Extensions

This is a list of syntax extensions to standard Markdown/Commonmark found in the documentation of these Markdown Flavors.

Inline Markup Extensions

_italic_ __bold__ ___bold italic___ ____underlined____ Some implementations go the Textile? way of differentiating semantic (strong) emphasis from presentational italic and boldface markup. Over there, the latter is achieved by doubling asterisk * or underscore _, markdown flavors instead choose the underscore, single and double, for the purely stylistic meaning and they add another layer with four underscores rendering the enclosed text with an underline, which was the reason for using the underscore in the first place. Fallback for the latter is surprisingly unsatisfactory, though, because some implementations will parse four underscores neither as double bold nor as open and immediate close bold, but something more strange. Test underline syntax

^superscript^
^^superscript^^
^(superscript) ^s Superscript text, i.e. positioned above the baseline and usually smaller, can be meaningful, although in many cases, such as chemical molecule formula notation, normal size and position is unambiguous, too. The circumflex or caret character ^ is used for that in TeX and elsewhere already, so it has been adopted in markdown flavors as well, but implementations differ as to whether they require one or two carets as affixes and some even try to make do with just a prefix – at least for single superscript characters, longer runs are then put in parenthesis to avoid ambiguity, e.g. with footnotes. Test superscript syntax

~subscript~
~~subscript~~
~(subscript) ~s
_(subscript) _s Much like superscript, subscript indices etc. may be semantic. TeX and some other languages use the underscore as a prefix (and maybe suffix), so that would be a good choice for markdown, too, had it not been used for emphasis instead. Some implementations try to use it nevertheless, with parentheses as mentioned above. More common, however, is the use of the tilde character ~ akin to the underscore. Note that the (double) tilde is used for deleted or stricken text elsewhere. Test subscript syntax

{-- removed content --}
{~~removed content~>ins~~}
{++ added content ++}
{== highlighted ==} Critic Markup is an orthogonal spec to markdown that can be used to annotate text with editorial comments and track changes. It consistently uses curly braces and double-character affixes which may also markup whitespace.
~~removed content~~ --removed content--
++added content++
==highlighted== ???highlighted??? Several implementations, sometimes by way of plugins, adapt syntax extensions from this, leaving out the braces. The plus ++ for additions and equals == for highlighted parts are unproblematic, but double ´hyphen-minus -- is frequently used to stand in for an en (or sometimes em) dash ‘–’/‘—’, which is why the tilde ~~ is employed instead, although it itself may also clash – with subscript notation. Shorthand replacement markup with ~> infix is not inherited from CriticMarkup. One implementation that does not mark up additions and removals has a different affix for highlights, three question marks ??? which may be unambiguous but also unintuitive. Test editorial syntax

"short quote"
""cited title"" """cited title""" Inline quotations and cites of titles, names or terms are rarely considered for extensions, but if so they are marked up with quotation marks. Usually, double-quote affixes ar replaced by “curly” quotation marks by (integrated) typographic preprocessors, but it’s just as intuitive to use HTML <q> instead. Cited instances are surrounded by either doubled or tripled marks. Test quote syntax

>>stripped comment<< <!--- stripped comment ---> {::COMMENT}stripped comment{:/COMMENT} Some authors want to add comments to source documents that shall not appear at all in the output – or vice versa. No conventional syntax has been established for this. The best backwards compatibility is provided by special HTML comments. Some implementations may employ a generic markup addition, which are discouraged. Test comment syntax

Link and Reference Markup Extensions

http://example.com Automatic URL detection and hyperlink generation is implemented often, but implementations differ in the details, i.e. which valid or invalid addresses are recognized and which are not. Usually, at least the colon and the double slashes are required ´, except for email addresses. Some implementations only auto-convert for known (and safe) protocol schemes. Test direct link syntax

[myid]: http://example.com (Example site) The optional title in reference-style links follows the address, but it needs to be enclosed somehow. Standard implementations support surrounding single or double quotation marks '/", some flavor extend this with round parenthesis. This may be relevant for future extensions that would add even more metadata to links or embedded media. Test parethetic link title syntax

[mnemonic target][]
[mnemonic target]
[[mnemonic target]]
[[mnemonic target|text]] Shortcut or implicit links – where the address or identifier can be derived from the title in a straightforward manner – are quite common, too, but the exact syntax differs a bit. Leaving the second pair of square brackets empty is the most common approach (while the reverse is seen nowhere). Leaving them out altogether is even more author-friendly, but it is also prone to become ambiguous or being unintended (hence leading nowhere). Doubling opening and closing brackets is an alternative that has been inherited from wiki syntax, MediaWiki in particular, but its different syntax for link text, which employs a pipe character as separator, is probably not worth consideration, because that can already be done with existing markdown syntax. Test shortcut/implicit link syntax

[^id] ↩︎ …
[^id]: note ^[note] Named and anonymous footnotes or endnotes are implemented the same way everywhere (if at all) and build upon shortcut link markup. The characteristic mark is the circumflex ^ which either precedes the reference identifier or the anonymous inline note inside square brackets. Test footnote syntax

[#id] ↩︎ …
  [#id]: citation
[@id]
[pages etc.][@id] For scientific citations, there are two approaches found in markdown flavors. The first works just like reference footnotes, except that it uses a hash character # as identifer prefix. The citation is found verbatim in the document instead of the web address (URL). The second approach uses the at-sign @ instead and relies on an external biography database. The latter one also supports location/page info in a ery basic way. Test citation syntax

ACRO ↩︎ …
  *[ACRO]: expansion For abbreviations and acronyms, possibly general technical terms, too, there is a convention that uses reference definitions, too, but finds inline uses automatically. Another difference is that the marker, an asterisk *, goes in front of the square brackets in the reference line, which probably was intended to improve fallback, because the abbreviation “glossary” might be rendered as a bullet list this way.
[abbr](abbr:expansion) Another approach reuses anonymous inline link syntax by introducing a pseudo-scheme abbr for URLs. That should also be possible with reference links, of course. Test abbreviation syntax

[text](class:myclassname)
[text](id:myidentifier) One flavor also adds pseudo-schemes for generic classes and identifiers. This should fall back nicely, except where URLs are checked deeper for validity, i.e. parsers that will only accept known protocol schemes. Test generic classes and identifiers

![alt](example.img =640x480)
![alt](example.img "image title" =640x480)
![alt](example.img =640x480 "image title") Optional image size may be supplied in some variants after – or before? documentation seems to mismatch implementation – the title, preceded by an equals sign we find width and height in pixels separated by an x. Sadly, this breaks badly in several implementations. Test image size syntax

=== [caption] ↩︎
![](figure.img) ↩︎
===
↩︎↩︎ ![caption](figure.img) ↩︎↩︎ Figures, i.e. floating image blocks, with caption can either be derived from standard paragraphs, that contain nothing but a picture link, or with a special fenced block that also contains the normal link. The caption can either be taken from existing alt and title or it is found as an attribute to the opening fence. Equals signs as fences are problematic, though, ecause they certainly will be taken as heading underlines somewhere. Test figure syntax

@[youtube](crypticid) There have been various proposals on how to embed videos and other media from external services easily, but only one was found documented in an actual implementation. It just uses an at-sign @ in place of the exclamation mark of image links. Since it does not accept full URLs as parameters, the fallback to a normal link is not helpful at all. Test embeded foreign media syntax

{toc}
[toc]
[[toc]]
@[toc](heading) Many implementations assign unique identifiers to all headings and maybe to other output elements as well. It‘s a simple step from there to supply an automatically generated table of contents, although viewers for output formats like PDF have built-in support for document structure. There are several variants to markup the English keyword toc to place this TOC at a certain position inside the document. One flavor uses the same link-based syntax with at-sign @ as for media embeds. The other variants often align with similar processing instructions as well.
{frontmatter} {half-title} {series-title} {title-page} {copyright} {dedication} {epigraph} {figures} {tables} {foreword} {preface} {acknowledgments} {introduction} {abbr} {chronology}
{mainmatter} {pagebreak}
{backmatter} {appendices} {notes} {glossary} {bibliography} {contributors}
{illustration-credits} {index} Two related flavors intended for book publishing include a number of English named processing instructions besides one for the TOC. Test processing instruction syntax

<<[transclude](file.ext)
<<(file.ext)
{{file.ext}} Transclusion of external files is helpful for larger projects and with source code. Few flavors support it, though, and syntax differs. One uses embedded link syntax with double less-than < instead of the exclamation mark, another employs MediaWiki template syntax with double curly braces. Test transclusion syntax

[-[ QR code ]-] A single implementation offers the exotic possibility to generate quick-response codes inline. Test QR code syntax

Prefix-only and Symbol Extensions

@username
#tag
!request
$snippet
~label Twitter-like hash-tags and username mentions are encountered frequently in comment use cases. Sometimes they are not part of the flavor itself, though, but are added by a custom pre or post-processor which knows about the local address structure – for mentions with at-sign, this is basically the same as the respective citation syntax, just with works instead of users. Sometimes user names include group names or special keywords like @all and tags are used with a specific meaning, e.g. @issue or @bug. Test mentions and tag syntax

:emoji:
:-) ;) )-: <3 (!) … Western-style image or text emoticons (and symbols) use mini character art, where some cases could be ambiguous which makes a curated collection required. Japanese-style Unicode emoji are almost always referenced by name inside colon affixes instead. Test emoticon, emoji and ASCII art+%3A)+)-%3A+%0A%3C3+!3+(!)%0A.oO(thought)) ä ä ä Some implementations – flavors are usually quite on this – normalize all named and numeric entity references. Test entity normalization \"a \to TeX-style character macros are usually only supported inside a respective math mode. Test character macro syntax

List Extensions

term ↩︎ : definition
term ↩︎   ~ definition
=term= ↩︎     definition Glossaries and other applications of definition lists seem popular, but there are at least three syntactic variants for them. The definition follows the term in a separate line, often indented or separated by an optional or mandatory blank line or both. While the term lines are left without a prefix in two variants, a colon : – most popular – or tilde ~ precedes the definition lines. In another variant, the term is marked with equals = affixes instead. Test definition list syntax

2. item with start value
4. item with fix value
A) upper alpha
a) lower alpha
I) upper roman
i) lower roman
#) automatic number In enumerated lists, various flavors honor the first numerator value as a start value for output (auto-numbers continue afterwards), others accept author-defined values for all entries. Some flavors recognize alternate “number” formats, like alphabetic or roman numerals, and may try to keep them in the output. Usually, digit one ‘1’ followed by either dot . or close parentheses ) can be used for each and every enumerated list item to get automatic numbering, the number sign # can be used for the same effect in some flavors, which should be more intuitive, but this will be misinterpreted as a top-level heading in some other implementations. Test explicit numbered list syntax+two%0A4)+four) Test alternate numbered lists syntax+lower+alpha%0A%0A____%0A%0AI.+upper+roman+or+9th+alpha%0A%0A____%0A%0Ai)+lower+roman%0Aii)+to+dismabiguate) Test automatically numbered list syntax+automatic+number%0A%0A____%0A%0A%23.+again%0A)

+ bullet list item
- [ ] to do: open task list item
- [X] done: closed task list item Besides dash - and asterisk *, the plus sign can be used in many flavors for bullet-point lists. Some flavors tailored to development and collaboration feature (non-interactive) task lists, where the bullet character is followed by a pair of square brackets that is either empty, i.e. just has (optional) whitespace inside, or is checked with an X or certain other characters (e.g. plus sign + or asterisk *). Test bullet list syntax Test nested list syntax Test task list syntax

Paragraph and Block Extensions

>! spoiler
-> center <- C> center
A> aside D> discussion E> error I> information Q> question T> tip W> warning X> exercise
B> blurp G> generic Some flavors add predefined paragraph types and they overload blockquote syntax in one way or the other to do so. An additional mark (or letter) after the greater-than sign will probably have better backwards compatibility than one before it. The selection of paragraph types will always leave some people wanting, so maybe (only) a generic mechanism to add custom classes would be better. Spoiler paragraphs reveal their textual content on hover. Test paragraph type syntax

> (http://example.com/source) quote One flavor adds the possibility to add a URL reference to block quotations. It is put in parentheses directly after the first line prefix >. Test sourced blockquote syntax

> %class% ↩︎ > prefixed block
::: class ↩︎ fenced block ↩︎ :::
!!! class ↩︎ indented block Generic blocks of text with author-defined classes allow much freedom. There is no consensus among flavors how to deal with them, though. One implementation uses special-cased block quotation markup, another has proprietary colon : fences (without good fallback behavior) and the third one introduces indented lines with a special, ! fence-like header (falling back to code). Test generic block syntax

Scientific and Other Extensions

(@) anonymous numbered example
(@id) named numbered example Some texts, e.g. linguistic articles, use paragraph-like examples that are numbered consecutively throughout the whole document; they are reference by number within the surrounding text frequently. One flavor adds list-like syntax for this, with an at-sign (inside parentheses) which may be followed by an identifier. References are made with this, too, which aligns nicely with the respective citation syntax. Test numbered examples syntax

| line-based text Some kinds and pieces of text have meaningful linebreaks and may also use semantic indentation, e.g. poems and postal addresses. One implementation uses the pipe | line prefix for these, although that may be interpreted as single-column table in other flavors. Test pre-wrap block syntax

```math   
```poem 
```art 

Fenced blocks were introduced to markup code listings and they can be tagged with the name of the programming language used to faciliate colorful highlighting for enhanced readability. Some flavors extend this to other types as well which may be interpreted to render differently, e.g. mathematical formulas, poems (see also above) or character art and diagrams. Look directly above and below for alternate, specialized syntax. Test fenced content syntax

$math$ \(math\) \\(math\\) {$$}math{/$$}
$$math$$
\[math\]
\\[math\\] Many flavor allow math to be embedded. Since these formulas often use TeX-like code (less often ASCIImath or MathML), it is reasonable to use TeX-inspired affixes, most with leading backslash, to mark it up. Both inline and block math (equations) is usually possible. Test math syntax

Metadata Extensions

% Markdown Extensions ↩︎ % Christoph Päper ↩︎ % 2015-07-03
--- ↩︎ key: value ↩︎ --- or ... When markdown is used to produce a complete document instead of just fragments of one, it proves useful to be able to assign some metadata to it that is not necessarily shown directly to the reader, although that would not harm either. One custom approach has three percent-prefixed lines for title, author and date, which is enough to generate the most basic title pages. Another allows embedding YAML metadata in key-value pairs, where values may be of various types. The latter employs dashed lines as fences, which nicely render as horizontal rules in non-supporting implementations.
[%key] One flavor even makes these metadata values accessible inside the text as template variables. Test document metadata syntax Test dotted YAML syntax/dashed (Please note that Babelmark 2 is tailored to fragments, not documents.)

{: #id .class attr="value"}
{#id .class attr="value"} Several flavors satisfy authors’ desire to assign unique identifiers, classes and arbitrary key-value attributes to blocks or even any marked-up span. They all employ curly braces for this, but differ in positions allowed. One implementation tries to be more unambiguous (though less intuitive) by requiring a colon : as the first character inside the braces. Identifers are prefixed with a hash mark #, class names with a period . – just like in CSS selectors. There usually is an equals sign =, not a colon, between key and value, the latter may be required to be put in quote marks, at least if cobtaining whitespace or equal signs. The order inside the braces is usually keft to the author’s taste, although id-classes-attributes seems most common and logical. Test generic attribute syntax