# Deployed Extensions

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

## Inline Markup Extensions

### Underlines

_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
• Recommendation: Allow optional different treatment of asterisk * (semantic) and underscore _ (presentational) when used as phrase affixes. Only then extend the presentational markup to underlines, using 4 underscores on each side. Also, define the meaning and parsing of more than 3 asterisks or underscores everywhere.

### Superscript

^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.

### Subscript

~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.

### Editorial

{-- removed content --}
{~~removed content~>ins~~}
{== 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--
==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
• Recommendation: Standardize an optional extension for collaboration, using double affixes (tilde ~~, plus ++ and equals ==) without curly braces.

### Font size

--small--
++big++ A single flavor uses different semantics for double plus and minus affixes, namely font size changes.

• Test font size syntax
• Recommendation: Ignore. Although <small> is in HTML5 for less important text, mere font size changes should be handled by stylesheets.

### Quotation

"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 quotation syntax
• Recommendation: Standardize an option extension with double double quotes "" for quotations and triple double quotes """ for citations. Single double quotes " may be replaced by language-dependent curly quotation marks, e.g. and . Alternatively double and triple angular brackets < and > could be used, mimicking guillemots.

### Comment

>>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
• Recommendation: Make it standard core behavior to pass through unaltered basic HTML comments with 2 dashes -- on both sides, but completely remove all HTML comments with 3 or more consecutive dashes --- on both sides. Visible, editorial comments should be part of the collaboration extension described above, using inverted double angular brackets >> and <<.

### Key press

[Alt]+[Q] A single implementation recognizes single roman letters and English standard keyboard abbreviations inside square brackets to properly mark them up as user input.

[[label]]
![[important label]] One flavor offers markup for inline badges and labels from the Bootstrap framework.

• Test badges and labels syntax
• Recommendation: Ignore for now. Such labels and badges are mostly used with content that is usually not made with markdown, they usually contain automatically generated or repetitive, pre-defined text.

## 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.

• Recommendation: Don’t require implementations to parse text for plain URLs, but don’t disallow it either. Reference the Web Addresses specification.

[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 parenthetic link title syntax
• Recommendation: Require implementations to finish reading an URL when they encounter a whitespace character. They must throw away everything that follows if they don’t know what to do with it. The first quoted or parenthesized string becomes the link title, more strings may follow with other extensions.

[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.

• Recommendation: Require support for the empty trailing square bracket notation in the core. As part of a highly recommended smart links module, standardize single bracket syntax [ and ] for shortcut links and make sure the inner pair of double bracket enclosures is used, too. Do not support the pipe syntax, i.e. the pipe would be considered part of the reference.

### Note

[^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
• Recommendation: Standardize a notes module with named and anonymous notes as shown above. Suggest to implementations that they let authors differentiate notes using numeric identifiers from those using textual or mixed ones, e.g. for footnotes vs. endnotes.

### Citation

[#id] ↩︎ …
[#id]: citation
(#id)
[@id]
[pages etc.][@id]
@id [pages etc.] 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 very basic way. For floats like tables and figures, there may be a difference between using square brackets and round parentheses in that one results in just a linked number, the other includes the number formatting as found in its target, e.g. enclosing parentheses.

• Test citation syntax
• Recommendation: As part of the smart links module and aligned with the notes module, use a unified syntax, possibly employing the at-sign @, to link to internal and external references.

### Abbreviation

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
• Recommendation: Handle within the smart links module or the module covering definition lists.

### Generic attributes

[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.

### Image size

![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
• Recommendation: Require implementations to finish reading an URL when they encounter a whitespace character. They must throw away everything that follows if they don’t know what to do with it. The first quoted or parenthesized string becomes the image title, more strings may be defined within the inclusion links module.

### Figure

↩︎↩︎ ![caption](figure.img) ↩︎↩︎
![](figure.img) ↩︎
: caption === [caption] ↩︎
![](figure.img) ↩︎
===
#Figure: 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 are made with a special fenced block that also contains the normal link. The caption can be taken from existing alt and title or it is found either as an attribute to the opening fence or in another line starting with a colon (and an optional label like Caption: or Figure: ). Equals signs as fences are problematic, though, because they certainly will be taken as heading underlines somewhere. Another flavor uses headings that start with an English keyword followed by a colon.

• Test figure syntax
• Recommendation: Strongly suggest that implementations should consider a paragraph containing nothing but images as a floating figure with caption. Explicit captions prefixed by a colon are also worth considering, the optional labels being turned into classes for styling in HTML output.

### Foreign media

@[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
• Recommendation: As part of an inclusion links module, select a prefix to normal links to mean embedding. This does not have to end up to be @.

### Processing instruction

{toc}
[toc]
[[toc]]
<!-- md-toc --> 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
• Recommendation: Do not adopt, but make a note that parsers should provide the user with an option to throw away paragraphs/lines that start and end with matching curly braces. Also allow profiles to overload the semantic meaning of horizontal rules ---, ___ and ***. If an output format supports document outlines based upon headings (which are basically TOCs), implementations should aid their generation.

### Transclusion

<<[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
• Recommendation: As part of an inclusion links module, select a prefix to normal links to mean transclusion. This does not have to end up to be <<.

### Generated image

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

• Test QR code syntax
• Recommendation: Do not support something like this at this point in time.

## Prefix-only and Symbol Extensions

#tag
!request

### Document info

% Markdown Extensions ↩︎ % Christoph Päper ↩︎ % 2015-07-03
--- ↩︎ Title: Markdown Extensions ↩︎ --- 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.
[%Title] One flavor even makes these metadata values accessible inside the text as template variables.

• Test dotted YAML syntax/dashed (Please note that Babelmark 2 is tailored to fragments, not documents.)
• Recommendation: Adopt YAML with mandatory dashed top and bottom fence --- (for better backwards compatibility than ...) in a metadata module. Only require support for a single instance at the very top of the document.

### Attributes

{: #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
• Recommendation: Don’t adopt, but make a note that parsers should provide the user with an option to throw away paragraphs/lines that start and end with matching curly braces.

## Table Extensions

There are several similar, but partially incompatible approaches to mark up tables. They variously use a combination of vertical pipe | and horizontal dash - with whitespace alignment to draw rows and columns, hence cells. Other characters like plus +, colon : and equals = are also frequently used. Tables may be split into head, body and foot, both horizontally and vertically, and cells may span several columns or rows or both, but only in a rectangular way, and they may contain multiple lines or proper block content – flavors differ in what they support of all this.