Skip to content

Deployed Extensions

Jump to bottom Edit New page
Christoph Päper edited this page Jul 24, 2015 · 13 revisions

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.

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

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

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

"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
  • 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.

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

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

((badge))
!((important badge))
[[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.

  • Test direct link syntax
  • 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.

  • Test shortcut/implicit link 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.

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

[#id] ↩︎ …
  [#id]: citation
[@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.

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

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.

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

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

=== [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
  • Recommendation: Strongly suggest that implementations should consider a paragraph containing nothing but images as a floating figure with caption.

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

{toc}
[toc]
[[toc]]
@[toc](heading)
<!-- 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.

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

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

@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. Note that dollar sign is also used for inline math markup and tilde is also used for subscripts and strike-outs.

  • Test mentions and tag syntax
  • Recommendation: Standardize, as part of an optional smart links module, the at @ and hash # affixes with suffixes being optional. Make the target either explicit with a reference line or implicit, hence site-specific and user-defined. Suggest to implementations that authors may want different behavior for numeric identifiers (tag vs. bug).

: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 &auml; &#228; &#xE4; Some implementations – flavors are usually quiet 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
  • Recommendation: The core spec should require implementations to normalize SGML-like entity references to UTF-encoded characters, with some exceptions as required by the target markup language. This includes all named character entities from HTML5 and all numeric (decimal or hexadecimal) references. The named emoji syntax with English-only designators is not well suited in an international context and therefore cannot be required behavior, even within a module. An optional art module should list emoticons that do not clash with Commonmark syntax and have conventional meaning.

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
  • Recommendation: There absolutely should be support, in either a lists module or a scientific writing module or the table module, for lists with keys instead of or in addition to bullets, but there is no recommendation yet for a definite 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
  • Test alternate numbered lists syntax
  • Test automatically numbered list syntax
  • Recommendation: Only standardize support for decimal, alphabetic and automatic numbering, but not roman numerals. Alphabetic counters may be divided into upper and lower case. The spec should reference CSS Counter Styles for details (e.g. aa, ab, ac vs. aa, bb, cc). Auto-enumeration should also be part of the core, but – depending on backwards compatibility – may be achieved by leaving out the digit or letter completely instead of replacing it by the number sign #.

+ 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
  • Recommendation: Require support for +, - and * list bullets in the core specification. Handle checkboxes etc. in an optional (pseudo) forms module. Specific profiles may assign narrower semantics, such as “task list”, to certain syntax patterns, but this should not be part of the core or the syntax extension modules. The same goes for “pro-con lists”, “release notes”, “diff” etc.

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
[[ alert ]]
[[ Important: error ]]
[[ Info: info ]]
[[ Hint: success ]] 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
  • Recommendation: This may be handled by the info string module, but no final recommendation is given here.

> (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
  • Recommendation: No final recommendation is provided. It would be at least as useful to parse the line or paragraph above the block quote if it ends with a colon :. Another common pattern to specify sources is a line introduced by 2 dashes -- that is placed immediately after the block quote.

### ↩︎ jumbotron. hero unit ↩︎ ###
!!! lede paragraph A single implementation that is much inspired by Bootstrap classes adds markup for special header blocks and lede paragraphs (probably reusable as abstract).

  • Test Bootstrap syntax
  • Recommendation: There may be a need for a header syntax which could use fences, but no exact recommendation is given yet.

> %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
  • Recommendation: Reuse existing backtick or tilde fences for this, employing the info string module.

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
  • Recommendation: As part of the smart links module, adopt a method to assign automatic and arbitrary identifiers to blocks so they can be referenced, and also specify a syntactically related way to reference these of course – this may employ the at-sign @. As part of a list module, make the counter of certain enumerated lists continuous throughout the document, a pair of parentheses () instead of just a closing one ) seems like a reasonable indicator for that.

| 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
  • Recommendation: As part of a table module, special-case single-column tables to support this, but make support for it optional.

~~~markdown ↩︎ … ~~~
~~~(markdown) ↩︎ … ~~~
~~~math ↩︎ … ~~~
~~~poem ↩︎ … ~~~
~~~art ↩︎ … ~~~ Fenced blocks (with three backticks ` or tildes ~) 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
  • Recommendation: Make only tilde fences optionally evaluated, i.e. backtick fences are always displayed verbatim (except for color, font and other style changes). Create an optional info string module that lists recognized code languages and other identifiers with expected rendering.

$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
  • Recommendation: Use fenced syntax above for math blocks, e.g. a full proof. Standardize single dollar affixes for inline math in a dedicated math module. As a part of this, invent numbered equation/formula syntax, e.g. ($) line prefix.

Metadata Extensions

% 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 document metadata syntax
  • 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.

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

Details to be added soon

  • Recommendation:
Add a custom footer
Add a custom sidebar
Clone this wiki locally