RFC 7764

Guidance on Markdown: Design Philosophies, Stability Strategies, and Select Registrations

📅 published March 2016, from ietf

Guidance on Markdown: Design Philosophies, Stability Strategies, and Select Registrations ✨

  • RFC number: 7764
  • Authors: S. Leonard, Penango, Inc. 🎀
  • Category: Informational (not a Standards Track spec, just here to share knowledge 🧚)
  • Date: March 2016
  • ISSN: 2070-1721
  • Obsoletes / Updates: Nothing. It doesn't obsolete or update any other RFCs, since none are listed in its header 💅

Abstract 🦋

okay so this doc goes deep on the text/markdown media type, which is the official label for Markdown, a family of plain-text formatting syntaxes that can optionally get converted into formal markup languages like HTML. it also covers background info, ways to store stuff locally, and some extra syntax registrations. iconic 💜

Status of This Memo 📝

not gonna lie, this part is a bit formal, but the gist is: this is not an Internet Standards Track spec. it's published purely for informational purposes 🌸

it IS a product of the Internet Engineering Task Force (IETF) 🫶 and it represents the consensus of the IETF community. it got public review and was approved for publication by the Internet Engineering Steering Group (IESG). not every IESG-approved doc is a candidate for any level of Internet Standard, so check Section 2 of RFC 5741 if you want the details 🤓

for the current status, any errata, and how to give feedback, peep http://www.rfc-editor.org/info/rfc7764 ✨

Copyright (c) 2016 IETF Trust and the persons identified as the document authors. All rights reserved. 🔒

this doc is subject to BCP 78 and the IETF Trust's Legal Provisions Relating to IETF Documents (http://trustee.ietf.org/license-info) as in effect on the date of publication. please actually read those, bestie, they spell out your rights and restrictions 📜 Code Components pulled out of this doc must include Simplified BSD License text as described in Section 4.e of the Trust Legal Provisions, and they come without warranty, as described in the Simplified BSD License 💅

Table of Contents 🗂️

1.  Dive into Markdown . . . . . . . . . . . . . . . . . . . . . .  3
  1.1. On Formats  . . . . . . . . . . . . . . . . . . . . . . . .  3
  1.2. Markdown Design Philosophy  . . . . . . . . . . . . . . . .  4
  1.3. Uses of Markdown  . . . . . . . . . . . . . . . . . . . . .  5
  1.4. Uses of Labeling Markdown Content as text/markdown  . . . .  6
  1.5. Definitions . . . . . . . . . . . . . . . . . . . . . . . .  6
2.  Strategies for Preserving Media Type and Parameters  . . . . .  7
  2.1. Map to Filename and Attributes  . . . . . . . . . . . . . .  7
  2.2. Store Headers in Adjacent File  . . . . . . . . . . . . . .  8
  2.3. "Arm" Content with MIME Headers . . . . . . . . . . . . . .  8
  2.4. Create a Local Batch Script . . . . . . . . . . . . . . . .  9
  2.5. Process the Markdown in Advance . . . . . . . . . . . . . .  9
  2.6. Rely on Context . . . . . . . . . . . . . . . . . . . . . .  9
  2.7. Specific Strategies . . . . . . . . . . . . . . . . . . . .  9
    2.7.1. Subversion  . . . . . . . . . . . . . . . . . . . . . .  9
    2.7.2. Git . . . . . . . . . . . . . . . . . . . . . . . . . . 10
3.  Registration Templates for Common Markdown Syntaxes  . . . . . 10
  3.1. MultiMarkdown . . . . . . . . . . . . . . . . . . . . . . . 10
  3.2. GitHub-Flavored Markdown  . . . . . . . . . . . . . . . . . 11
  3.3. Pandoc  . . . . . . . . . . . . . . . . . . . . . . . . . . 12
  3.4. Fountain (Fountain.io)  . . . . . . . . . . . . . . . . . . 14
  3.5. CommonMark  . . . . . . . . . . . . . . . . . . . . . . . . 14
  3.6. kramdown-rfc2629 (Markdown for RFCs)  . . . . . . . . . . . 15
  3.7. rfc7328 (Pandoc2rfc)  . . . . . . . . . . . . . . . . . . . 16
  3.8. PHP Markdown Extra  . . . . . . . . . . . . . . . . . . . . 16
4.  Examples for Common Markdown Syntaxes  . . . . . . . . . . . . 17
  4.1. MultiMarkdown . . . . . . . . . . . . . . . . . . . . . . . 17
  4.2. GitHub Flavored Markdown  . . . . . . . . . . . . . . . . . 18
  4.3. Pandoc  . . . . . . . . . . . . . . . . . . . . . . . . . . 19
  4.4. Fountain (Fountain.io)  . . . . . . . . . . . . . . . . . . 20
  4.5. CommonMark  . . . . . . . . . . . . . . . . . . . . . . . . 21
  4.6. kramdown-rfc2629 (Markdown for RFCs)  . . . . . . . . . . . 22
  4.7. rfc7328 (Pandoc2rfc)  . . . . . . . . . . . . . . . . . . . 25
5.  IANA Considerations  . . . . . . . . . . . . . . . . . . . . . 25
6. Security Considerations . . . . . . . . . . . . . . . . . . . . 26
7. References  . . . . . . . . . . . . . . . . . . . . . . . . . . 26
  7.1. Normative References  . . . . . . . . . . . . . . . . . . . 26
  7.2. Informative References  . . . . . . . . . . . . . . . . . . 26
Author's Address . . . . . . . . . . . . . . . . . . . . . . . . . 28

1. Dive into Markdown 💖

this doc is the informational companion to [RFC7763], which is the text/markdown media type registration. you should read them together, bestie 🫶

"Sometimes the truth of a thing is not so much in the think of
it, but in the feel of it." -- Stanley Kubrick

1.1. On Formats 🧚

okay so picture a whole continuum of ways computers store and process text. on one end you've got plain text: computer-encoded text that's just a sequence of code points from some standard, with no other formatting or structure info [UNICODE] 📄 plain text has some fixed formatting stuff (codes in the character set that mean something other than "draw this character on the output medium"), but none of it is very extensible 🥲 see Section 4.2.1 of [RFC6838] for comparison. applications can neuter these special characters by prohibiting them or ignoring what they're supposed to do, which is how modern apps handle most control characters in US-ASCII 💅 any text reader or editor that understands the character set can see or edit it. and if some characters get corrupted, the computer can usually still process the text, even if the human meaning changes 🙈

on the other end is binary data: a sequence of bits meant for some application to interpret and act on 🤖 binary formats are efficient for non-textual data (maybe no text at all, or only certain text for super specialized purposes) 💜 but an application has to be coded specifically for the format, so there's no partial interoperability 😭 and if even one bit gets corrupted, the app might not be able to process any of the data correctly 💀

in between those two extremes is formatted text: text that includes non-textual information coded in a particular way that changes how computer programs interpret it 🎀 it's different from plain text and binary because that non-textual info is encoded into regular textual characters that have specialized meanings beyond the character set. with a normal text editor and a standard keyboard, a user can type those characters to express non-textual meanings ⌨️ for example, a < isn't just "LESS-THAN SIGN" anymore. it means the start of a tag or element that affects the document somehow 👀

on the formal end of formatted text is markup, a family of languages for annotating a document so the annotations are syntactically distinguishable from the text 📚 markup languages are (reasonably) well-specified and tend to follow (mostly) standardized syntax rules. examples include Standard Generalized Markup Language (SGML), HTML, XML, and LaTeX 🌸 standardized rules mean markup processors can interoperate, but new (human) users have to learn those rules to do anything useful, and that makes markup less accessible for non-technical users (aka users who aren't willing or able to put in the skill development) 😤

  informal        /---------formatted text----------\        formal
  <------v-------------v-------------v-----------------------v---->
   plain text     informal markup   formal markup    binary format
                  (Markdown)        (HTML, XML, etc.)

Figure 1: Degrees of Formality in Data-Storage Formats for Text

on the informal end are lightweight markup languages 🍓 compared to formal markup like XML, lightweight markup has simple syntax and is designed to be easy for humans to type with basic text editors ✨ Markdown, the star of this doc, is an informal plain-text formatting syntax that's intentionally aimed at non-technical users (people who need little to no skill development) using unspecialized tools (aka plain text boxes) 🥰 Jeff Atwood once called these informal markup languages "humane" [HUMANE] 🫶

1.2. Markdown Design Philosophy 🌈

Markdown is a family of syntaxes based on the original work of John Gruber, with substantial contributions from Aaron Swartz, released in 2004 [MARKDOWN] 👑 ever since, a bunch of web (or web-facing) apps have built Markdown into their text-entry systems, often with custom extensions 🧩 people were fed up with how complicated and security-pitfall-y formal markup languages (e.g., HTML5) and proprietary binary formats (e.g., commercial word processors) were 😩 but they also didn't want to be stuck with plain text's limits, so lots of users turned to Markdown for document processing 💅 whole toolchains now exist for online and offline projects 🛠️

Informality is a bedrock premise of Gruber's design 🪨 he made Markdown after disastrous experiences with strict XML and XHTML processing of syndicated feeds 😵 in Mark Pilgrim's "thought experiment," several websites went down because one site included invalid XHTML in a blog post, which got automatically copied across other sites via trackbacks [DIN2MD] 🙀 these scenarios led Gruber to believe that clients (e.g., web browsers) SHOULD try to make sense of data they receive, rather than rejecting it just because it doesn't follow strict, unforgiving standards 🤍 (in [DIN2MD], Gruber compared Postel's Law [RFC793] with the XML standard, which says: "Once a fatal error is detected [...] the processor MUST NOT continue normal processing" [XML1.0-5] 💀) so as a result, there's no such thing as "invalid" Markdown, there's no standard demanding adherence to the Markdown syntax, and there's no governing body that guides or blocks its development 🦋 if the Markdown syntax doesn't give the "right" output (defined as the output the author wants, not output that matches some dictated system of rules), Gruber's view is that the author either should keep experimenting or should change the processor to fit their particular needs (see the [MARKDOWN] Readme and [MD102b8] perldoc; see also [CATPICS]) 🐱✨

1.3. Uses of Markdown 🦋

okay so Markdown has been absolutely iconic since it dropped in 2004 💅 and honestly the success is giving. It works for people for three big reasons. First, the markup written in plain text looks a lot like the markup it stands for, so the brain load to learn the syntax is low 🧠. Second, the real judge of the syntax's success is running code 💻. The tool that turns Markdown into something presentable decides whether a syntax element matters, and not a series of formal pronouncements by a standards body 🙈. Third, Markdown has become kind of an Internet meme [INETMEME], in that it gets received, reinterpreted, and reworked as more communities bump into it 🌈. People use it for scholarly writing [OCCASION], for screenplays [FOUNTAIN], and even for mathematical formulae [MATHDOWN] 🧮. Obviously a screenwriter has zero use for specialized Markdown syntax for mathematicians 💀, and mathematicians don't need to identify characters or props in common ways either. The overall gist is that all of these communities can take the common elements of Markdown (which are rooted in the common elements of HTML circa 2004) and build on them in ways that best fit their needs ✨.

1.4. Uses of Labeling Markdown Content as text/markdown 🏷️

The main purpose of an Internet media type is to label "content" on the Internet, as distinct from "files" 📦. Content is any computer-readable format that can be represented as a primary sequence of octets, along with type-specific metadata (parameters) and type-agnostic metadata (protocol dependent). So, ngl, slapping ".markdown" on the end of a filename is not a sufficient way to identify Markdown 🙅‍♀️. Filenames are properties of files in file systems, but Markdown often lives in databases or content management systems (CMSes) where the file metaphor doesn't apply. One CMS [RAILFROG] uses media types to pick the right processing, so a media type is necessary for the safe and interoperable use of Markdown 🔐.

Unlike complete HTML documents, [MDSYNTAX] provides no means to include metadata in the content stream. Several derivative flavors have invented metadata incorporation schemes (e.g., [MULTIMD]), but these schemes only address specific use cases. In general, the metadata has to be supplied via supplementary means in an encapsulating protocol, format, or convention. How the content and the metadata relate isn't directly addressed here or in [RFC7763]; however, by identifying Markdown with a media type, Markdown content can participate as a first-class citizen with a wide spectrum of metadata schemes 👑.

Finally, registering a media type through the IETF process is not trivial 😩. Markdown can no longer be considered a "vendor"-specific innovation, but the registration requirements even in the vendor tree have proven to be overly burdensome for most Markdown implementers. Moreover, registering hundreds of Markdown variants with distinct media types would impede interoperability: virtually all Markdown content can be processed by virtually any Markdown processor, with varying degrees of success. The goal of [RFC7763] is to reduce all of these burdens by having one media type that accommodates diversity and eases registration 🦋.

1.5. Definitions 📖

The key words "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT", "SHOULD", "SHOULD NOT", "RECOMMENDED", "MAY", and "OPTIONAL" in this document are to be interpreted as described in [RFC2119].

Since Markdown signifies a family of related formats with varying degrees of formal documentation and implementation, this specification uses the term "variant" to identify such formats 🧚.

2. Strategies for Preserving Media Type and Parameters 🎀

The purpose of this document and [RFC7763] is to promote interoperability between different Markdown-related systems, preserving the author's intent 💖. While [MARKDOWN] was designed by Gruber in 2004 as a simple way to write blog posts and comments, as of 2014 Markdown and its derivatives are rapidly becoming the formats of record for many communities and use cases. An individual member of (or software tool for) a community can probably look at some "Markdown" and declare its meaning intuitively obvious, but software systems in different communities (or different times) need help 🙏. [MDSYNTAX] does not have a signaling mechanism like <!DOCTYPE>, so tagging Markdown internally is simply out of the question 🚫. Once tags or metadata are introduced, the content is no longer "just" Markdown.

Some commentators have suggested that an in-band signaling mechanism, such as Markdown link definitions at the top of the content, could be used to signal the variant. Unfortunately, this signaling mechanism is incompatible with other Markdown variants (e.g., [PANDOC]) that expect their own kinds of metadata at the top of the file 😬. Markdown content is just a stream of text; the semantics of that text can only be furnished by context.

The media type and variant parameter in [RFC7763] furnish this missing context, while allowing for additional extensibility ✨. This section covers strategies for how an application might preserve metadata when it leaves the domain of IETF protocols.

[RFC7763] only defines two parameters: the charset parameter (required for all text/* media types) and the variant parameter. [RFC6657] provides guidance on character-set parameter handling. The variant parameter provides a simple identifier -- nothing less or more. Variants are allowed to define additional parameters when sent with the text/markdown media type; the variant can also introduce control information into the textual content stream (such as via a metadata block). Neither [RFC7763] nor this specification recommend any particular approach. However, the philosophy behind [RFC7763] is to preserve formats rather than create new ones, since supporting existing toolchains is more realistic than creating novel ones that lack traction in the Markdown community 🧰.

2.1. Map to Filename and Attributes 📁

This strategy is to map the media type, variant, and parameters to "attributes" or "forks" in the local convention. Firstly, Markdown content saved to a file should have an appropriate file extension ending in .md or .markdown, which serves to disambiguate it from other kinds of files. The character repertoire of variant identifiers in [RFC7763] is designed to be compatible with most filename conventions. Therefore, a recommended strategy is to record the variant identifier as the prefix to the file extension. For example, for [PANDOC] content, a file could be named "example.pandoc.markdown".

Many filesystems are case-sensitive or case-preserving; however, file extensions tend to be all lowercase. This document takes no position on whether variant identifiers should be case-preserved or all lowercase when Markdown content is written to a file. However, when the variant identifier is read to influence operational behavior, it needs to be compared case-insensitively 🔤.

Many modern filesystems support "extended attributes", "alternate data streams", or "resource forks". Some version control systems support named properties. If the variant defines additional parameters, these parameters should be stored in these resources, where the parameter name includes the name of the resource, and the parameter value is the value of the resource (data in the resource), preferably UTF-8 encoded (unless the parameter definition explicitly defines a different encoding or repertoire). The variant identifier itself should be stored in a resource with a name including the term "variant" (possibly including other decorations to avoid namespace collisions) 🗂️.

2.2. Store Headers in Adjacent File 📎

This strategy is to save the Markdown content in a first file and to save the metadata (specifically the Content-Type header) in a second file with a filename that is rationally related to the first filename. For example, if the first file is named "readme.markdown", the second file could be named "readme.markdown.headers". (If stored in a database, the analogy would be to store the metadata in a second table with a field that is a key to the first table.) This header file has the media type message/global-headers [RFC6533] (".u8hdr" suggestion notwithstanding) 🙃.

2.3. "Arm" Content with MIME Headers 🛡️

This strategy is to save the Markdown content along with its headers in a file, "arming" the content by prepending the MIME headers (specifically the Content-Type header). It should be appreciated that the file is no longer a "Markdown file"; rather, it is an Internet Message Format file (e.g., [RFC5322]) with a Markdown content part. Therefore, the file should have an Internet message extension (e.g., .eml, .msg, or .u8msg), not a Markdown extension (e.g., .md or .markdown) 💌.

2.4. Create a Local Batch Script 🍓

This strategy is to translate the processing instructions inferred from the Content-Type and other parameters (e.g., Content-Disposition) into a sequence of commands in the local convention, storing those commands in a batch script. For example, when a MIME-aware client stores some Markdown to disk, the client can save a Makefile in the same directory with commands that are appropriate (and safe) for the local system 🛠️.

2.5. Process the Markdown in Advance ⏩

This strategy is to process the Markdown into the formal markup, before a recipient receives it; this eliminates ambiguities. Once the Markdown is processed into (for example) valid XHTML, an application can save a file as "doc.xhtml" or can send MIME content as application/xhtml+xml with no further loss of metadata. While unambiguous, this process may not be reversible 🔄.

2.6. Rely on Context 🧭

This last strategy is to use or create context to determine how to interpret the Markdown. For example, Markdown content that is of the Fountain.io type [FOUNTAIN] could be saved with the filename "script.fountain" instead of "script.markdown". Alternatively, scripts could be stored in a "/screenplays" directory while other kinds of Markdown could be stored elsewhere. For reasons that should be intuitively obvious, this method is the most error-prone. "Context" can be easily lost over time, and the trend of passing Markdown between systems -- taking them out of context -- is increasing 😭.

2.7. Specific Strategies 🎬

2.7.1. Subversion 🌀

This subsection covers a preservation strategy in Subversion [SVN], a common client-server version control system.

Subversion supports named properties. The svn:mime-type property duplicates the entire Content-Type header, so parameters SHOULD be stored there (Section 2.1). The filename SHOULD be consistent with this Content-Type header, i.e., the extension SHOULD be the variant identifier plus ".markdown" (Section 2.1) 💜.

2.7.2. Git 🌸

okay bestie, this one is about Git [GIT], the super popular distributed version control system 💅 Real talk, Git doesn't natively do arbitrary metadata storage yet 🙈 but third-party projects bolt that on, so there's a whole ecosystem for it ✨

if you're using Git without a metadata storage service, the move is to put the variant identifier right in the filename (Section 2.1) 🎀 the default text encoding SHOULD be UTF-8 🫶 and for anything else or any different properties, a header file SHOULD be recorded alongside the Markdown file (Section 2.2) 📝

if you are using a metadata storage service with Git, just pick a convention that's most analogous to that service 🦋 for example, the "metastore" project emulates extended attributes (xattrs) of a POSIX-like system, so whatever "xattr" methodology gets developed would be usable with metastore and Git 💜

3. Registration Templates for Common Markdown Syntaxes ✨

okay so this section is where we register certain syntaxes in the "Markdown Variants" registry [RFC7763] 👑 these are the ones with really interesting use cases or the ones that are broadly useful to the whole Internet community, so they deserve the extra review that comes with being published as IETF documents 🔥

3.1. MultiMarkdown

Identifier: MultiMarkdown

Name: MultiMarkdown

Description: MultiMarkdown (MMD) is basically a superset of "Original" 💖 it adds a bunch of syntax features (tables, footnotes, and citations, to name a few) and it's built to output to all kinds of formats ✨ it also has "smart" typography for different languages, so you get proper left- and right-sided quotes and that kind of thing 💅

Additional Parameters: the options parameter is a string with zero or more of the following tokens, separated by whitespace (WSP) 🌈

"memoir" / "beamer"
"full" / "snippet"
"process-html"
"random-footnote-identifiers"
"accept"
"reject"
"nosmart"
"nonotes"
"nolabels"
"nomask"

the meanings of these tokens are defined in the MultiMarkdown documentation 📚

References: <http://fletcher.github.io/MultiMarkdown-4/syntax>

Contact Information: (individual) Fletcher T. Penney <fletcher@fletcherpenney.net> <http://fletcherpenney.net/multimarkdown/>

3.2. GitHub Flavored Markdown

Identifier: GFM

Name: GitHub Flavored Markdown

Description: GFM is "Original" with a glow-up 💖 here's what's different:

  1. multiple underscores inside words 🌸
  2. URL (URI) autolinking 🔗
  3. strikethrough 💀
  4. fenced code blocks 💻
  5. syntax highlighting 🌈
  6. tables, where - is for rows, | is for columns, and : is for alignment 🍓
  7. only some HTML is allowed, and sanitization is baked right into the format 🫶

References: <https://help.github.com/articles/github-flavored-markdown/> <https://github.com/github/markup/tree/master#html-sanitization>

Contact Information: (corporate) GitHub, Inc. <https://github.com/contact>

3.3. Pandoc

Identifier: pandoc

Name: Pandoc

Description: okay the whole point of Markdown is that it's easy to write AND easy to read ✨ the content should be publishable as-is, as plain text, without looking like it's covered in tags or formatting instructions 🦋 "Original" has HTML generation in mind, but pandoc is built for multiple output formats 🎀 so while pandoc does let you embed raw HTML, it discourages it, and gives you non-HTMLish ways to represent important document elements like definition lists, tables, mathematics, and footnotes 👑

Additional Parameters: the extensions parameter is a string with an optional starting syntax token, followed by a list of extension tokens delimited by "+" and "-" 💅 a "+" in front of an extension token turns that extension on, and a "-" turns it off 🔥 the starting syntax tokens are markdown, markdown_strict, markdown_phpextra, and markdown_github 🌈 if you don't give a starting syntax token, markdown is assumed 🧚 the extension tokens are below.

Extensions to turn off (these are on by default):

escaped_line_breaks
blank_before_header
header_attributes
auto_identifiers
implicit_header_references
blank_before_blockquote
fenced_code_blocks
fenced_code_attributes
line_blocks
fancy_lists
startnum
definition_lists
example_lists
table_captions
simple_tables
multiline_tables
grid_tables
pipe_tables
pandoc_title_block
yaml_metadata_block
all_symbols_escapable
intraword_underscores
strikeout
superscript
subscript
inline_code_attributes
tex_math_dollars
raw_html
markdown_in_html_blocks
native_divs
native_spans
raw_tex
latex_macros
implicit_figures
footnotes
inline_notes
citations

Extensions to turn on (these are off by default):

lists_without_preceding_blankline
hard_line_breaks
ignore_line_breaks
tex_math_single_backslash
tex_match_double_backslash
markdown_attribute
mmd_title_block
abbreviations
autolink_bare_uris
ascii_identifiers
link_attributes
mmd_header_identifiers
compact_definition_lists

Fragment Identifiers: pandoc defines fragment identifiers using the <id> in the {#<id> .class ...} production, which is the PHP Markdown Extra attribute block 🧁 this syntax works for Header Identifiers and Code Block Identifiers ✨

References: <http://johnmacfarlane.net/pandoc/README.html#pandocs-markdown>

Contact Information: (individual) Prof. John MacFarlane <jgm@berkeley.edu> <http://johnmacfarlane.net/>

3.4. Fountain (Fountain.io)

Identifier: Fountain

Name: Fountain

Description: Fountain is a simple markup syntax for writing, editing, and sharing screenplays in plain, human-readable text 🎬 you can work on your screenplay anywhere, on any computer or tablet, using any software that edits text files 💖

Fragment Identifiers: see <http://fountain.io/syntax#section-titlepage> and <http://fountain.io/syntax#section-sections> 🧚 in the fragment identifiers below, the <key> and <sec*> productions MUST have "/" characters percent-encoded 🚨

  • #/: Title Page, which acts as metadata.
  • #/<key>: Title Page, where <key> is the key string.
  • #<sec1> *("/" <secn>): a Section or subsection. The <sec1> through <secn> productions are the text of the Section line, with whitespace trimmed from both ends. Subsections (sections with multiple # characters at the beginning of the line in the source) are addressed hierarchically by putting the subsection after higher-order sections. If the section hierarchy "skips" (for example, # straight to ###), use a blank section name, like this: #Section/ACT%20I//PATIO%20SCENE

References: <http://fountain.io/syntax>

Contact Information: (individual) Stu Maschwitz <http://prolost.com/> (individual) John August <http://johnaugust.com/>

3.5. CommonMark

Identifier: CommonMark

Name: CommonMark

Description: CommonMark is a standard, unambiguous syntax spec for Markdown, plus a big suite of tests so you can check your Markdown implementation against it 🧪 the maintainers believe CommonMark is necessary, even essential, for the future of Markdown 💜

compared to "Original," CommonMark is way longer and in a few spots it contradicts "Original," based on seasoned experience 🙈 CommonMark doesn't mandate any particular encoding for the input content, but it pulls in more of Unicode, UTF-8, and HTML (including HTML5) than "Original" does 🌍

this registration always refers to the latest version or an unspecified version (receiver's choice) ✨ version 0.13 of the CommonMark specification was released 2014-12-10 🎂

References: <http://spec.commonmark.org/>

Contact Information: (individual) John MacFarlane <jgm@berkeley.edu> (individual) David Greenspan <david@meteor.com> (individual) Vicent Marti <vicent@github.com> (individual) Neil Williams <neil@reddit.com> (individual) Benjamin Dumke-von der Ehe <ben@stackexchange.com> (individual) Jeff Atwood <jatwood@codinghorror.com>

3.6. kramdown-rfc2629 (Markdown for RFCs)

Identifier: kramdown-rfc2629

Name: Markdown for RFCs

Description: kramdown is a Markdown parser by Thomas Leitner, and it has a bunch of backends for generating HTML, LaTeX, and Markdown again 🔁 kramdown-rfc2629 is an extra backend on top of that 💖 it lets you generate XML2RFC XML markup (originally known as RFC 2629 compliant markup, now documented in RFC 7749) 🦋

References: <https://github.com/cabo/kramdown-rfc2629>

Contact Information: (individual) Carsten Bormann <cabo@tzi.org>

3.7. rfc7328 (Pandoc2rfc)

Identifier: rfc7328

Name: Pandoc2rfc

Description: Pandoc2rfc lets authors write in "pandoc," which then gets transformed to XML and handed off to xml2rfc 🌀 the conversions are kinda hilarious tbh, because you start with (almost) plain text, go through elaborate XML, and end up with plain text again 😭

References: RFC 7328 <https://github.com/miekg/pandoc2rfc>

Contact Information: (individual) R. (Miek) Gieben <miek@google.com>

3.8. PHP Markdown Extra

Identifier: Extra

Name: Markdown Extra

Description: Markdown Extra is an extension to PHP Markdown that adds features the plain Markdown syntax doesn't have 🧁 it's available as a separate parser class in PHP Markdown Lib, and other implementations include Maruku (Ruby) and Python Markdown 🐍 it's also supported in several content management systems, including Drupal, TYPO3, and MediaWiki 💅

Fragment Identifiers: Markdown Extra defines fragment identifiers using the <id> in the {#<id> .class ...} production, which is the attribute block 🎀 this syntax works for headers, fenced code blocks, links, and images ✨

References: <https://michelf.ca/projects/php-markdown/extra/>

Contact Information: (individual) Michel Fortin <michel.fortin@michelf.ca>

4. Examples for Common Markdown Syntaxes 🧚

this section gives you examples of the variants from Section 3 💖

4.1. MultiMarkdown

here's a little MultiMarkdown example doc 🍓 it's got a title block, a header, a list, a footnote, and the whole vibe 🌸

Title:    Example of MultiMarkdown
Keywords: IETF, example, footnotes

# MultiMarkdown Example #

MultiMarkdown supports several cool features, as well as
several output formats:
*   HTML
*   PDF
*   OpenDocument
*   OPML
*   LaTeX

## Footnotes ##

Footnotes are described in the
MultiMarkdown Syntax Guide.[^somesamplefootnote]

4.2. GitHub-Flavored Markdown 🍓

okay so GFM is basically regular Markdown with a few extra features ✨. The big one is autolinking: a bare URL like http://www.example.com/ gets turned into a link automatically, no cap. You also get strike-through, so ~~This is strike-through text, demarked by the double tildes.~~ shows up crossed out. it's giving tidy 💅

Here's the whole example, verbatim, because it's iconic 👑

# Start Out #

GFM is like regular Markdown with a few extra features. For example,
http://www.example.com/ will get auto-linked. ~~This is strike-through
text, demarked by the double tildes.~~

function test() { return "notice this feature?"); }


# Table Alignments #

| Left      | Center  |  Right |
|:--------- |:-------:| ------:|
| cats      | Paxton  |  $1600 |
| dogs      |  Ruff   |    $30 |
| zebras    | Stripes | $20900 |

Figure 2: GitHub Flavored Markdown Example

4.3. Pandoc 🧚

Pandoc is a whole vibe 🌈. Its input is a document that carries a title block, and you can attach attributes to headers, which is sooo handy. Here's the example in full:

% Pandoc User's Guide
% John MacFarlane
% August 30, 2014

Synopsis {#syn}
========

pandoc [*options*] [*input-file*]...

Description {#desc}
===========

Pandoc is a [Haskell] library for converting from one markup format to
another, and a command-line tool that uses this library.

#### Extension: `header_attributes` #### {#ext-header-attributes}

Headers can be assigned attributes using this syntax at the end of the
line containing the header text:

    {#identifier .class .class key=value key=value}

Thus, for example, the following headers will all be assigned the
identifier `foo`:

    # My header {#foo}

    ## My header ##    {#foo}

    My other header   {#foo}
    ---------------

Figure 3: Pandoc Example

4.4. Fountain (Fountain.io) 🎬

Fountain is screenwriting markup, and the example is giving full dramatic main character energy 🎭 Mortimer is literally bleeding out in a moving boxcar, and it's so good 😭

INT. BOXCAR - MOVING - DAY
?AGENT MORTIMER lies bleeding in the corner. The car ROCKS gently.
Mortimer pulls out his cell phone and dials.

MORTIMER?
Come on. Pick up.

CUT TO:?
ext. hotel bar - day?
A fiercely gorgeous brunette sips the last of something from a
rocks glass. This is REBECCA.

Behind her, a dark FIGURE approaches. She seems not to notice.

REBECCA?(to Bartender)
Rittenhouse, neat.

FIGURE (O.S.) ^
Ritenhouse, neat.

She turns to find the source of the voice.

FIGURE
Excellent choice.

Before she can reply, her phone RINGS.?

> INTERCUT WITH:?

.THE BOXCAR

Where MORTIMER is just barely holding on to life.

Figure 4: Fountain Example

4.5. CommonMark 💜

CommonMark is like Markdown, bestie, just with its own rules 🦋 It lets you use entity names, has its own link-with-title syntax, and handles lists and fenced code blocks with tildes too. Here's the sample:

   CommonMark is like Markdown.

   Here are some entity names that you can use with CommonMark: `&nbsp;
   &amp; &copy; &AElig; &Dcaron; &frac34; &HilbertSpace; &DifferentialD;
   &ClockwiseContourIntegral;`

   You can see more at [the CommonMark website](http://commonmark.org/
   "CommonMark").

   - foo
   ***
   - bar

   Tildes can be used for fenced code blocks:

   ~~~
   <
    >
   ~~~

Figure 5: CommonMark Example

4.6. kramdown-rfc2629 (Markdown for RFCs) 🌸

This one is a whole RFC written in Markdown, so it's basically the meta moment of the century 🙈 The front matter sets the title, the author, and the category, and then the body has the abstract, the middle, and the back. Everything is copied exactly below, including the little figure markers:

---
title: STUN/TURN using PHP in Despair
abbrev: STuPiD-excerpt
docname: draft-hartke-xmpp-stupid-excerpt-00
date: 2009-07-05
category: info

ipr: trust200902
area: General
workgroup: XMPP Working Group
keyword: Internet-Draft

stand_alone: yes
pi: [toc, sortrefs, symrefs]

author:
 -
    ins: K. Hartke
    name: Klaus Hartke
    email: example@tzi.org

normative:
  RFC2119:

informative:
  RFC5389:
  STUNT:
    target: http://www.example.com/oob
    title: STUNT & out-of-band channels
    author:
      name: Robbie Hanson
      ins: R. Hanson
    date: 2007-09-17

--- abstract

NAT (Network Address Translator) Traversal may require TURN
(Traversal Using Relays around NAT) functionality in certain
cases that are not unlikely to occur.  There is little
incentive to deploy TURN servers, except by those who need
them&#x2014;who may not be in a position to deploy a new protocol
on an Internet-connected node, in particular not one with
deployment requirements as high as those of TURN.

--- middle
Introduction        {#problems}
============

"STUN/TURN using PHP in Despair" is a highly deployable protocol for
obtaining TURN-like functionality, while also providing the most
important function of STUN {{RFC5389}}.

The Need for Standardization   {#need}
----------------------------

Having one standard form of STuPiD service instead of one specific to
each kind of client also creates an incentive for optimized
implementations.

~~~~~~~~~~


        STuPiD   ```````````````````````````````,
        Script   <----------------------------. ,
                                              | ,
          ^ ,                                 | ,
          | ,                                 | ,
    (1)   | ,                                 | ,  (3)
    POST  | ,                                 | ,  GET
          | ,                                 | ,
          | v                                 | v

        Peer A   ----------------------->   Peer B
                           (2)
                       out-of-band
                       Notification
~~~~~~~~~~
{: #figops title="STuPiD Protocol Operation"}

Terminology          {#Terminology}
-----------
In this document, the key words "MUST", "MUST NOT", "REQUIRED",
"SHALL", "SHALL NOT", "SHOULD", "SHOULD NOT", "RECOMMENDED", "MAY",
and "OPTIONAL" are to be interpreted as described in BCP 14, RFC 2119
{{RFC2119}} and indicate requirement levels for compliant STuPiD
implementations.

--- back

Sample Implementation     {#impl}
=====================

~~~~~~~~~~
<?php
header("Cache-Control: no-cache, must-revalidate");
header("Expires: Sat, 26 Jul 1997 05:00:00 GMT");
header("Content-Type: application/octet-stream");

?>
~~~~~~~~~~
{: #figimpl title="STuPiD Sample Implementation"}

Figure 6: Markdown for RFCs Example

4.7. rfc7328 (Pandoc2rfc) ✨

Pandoc2rfc takes multiple files as input, so this figure is the example of middle.mkd, one of those files. It's a Pandoc document with <?rfc ...?> processing instructions up top and a few notes and links in the body 💖

# Introduction

<?rfc toc="yes"?>
<?rfc symrefs="yes"?>
<?rfc sortrefs="yes"?>
<?rfc subcompact="no"?>
<?rfc compact="yes"?>
<?rfc comments="yes"?>

This document presents a technique for using Pandoc syntax as a source
format for documents in the Internet-Drafts (I-Ds) and Request
for Comments (RFC) series.

This version is adapted to work with `xml2rfc` version 2.x.

Pandoc is an "almost plain text" format and therefore particularly
well suited for editing RFC-like documents.

> Note: this document is typeset in Pandoc.

> NB: this is mostly text to test Pandoc2rfc, the canonical
> documentation is [RFC 7328][p2r].

[p2r]: http://www.rfc-editor.org/info/rfc7328

# Pandoc to RFC

> Pandoc2rfc -- designed to do the right thing, until it doesn't.

When writing [](#RFC4641) we directly wrote the
XML. Needless to say it was tedious even though the XML of
[xml2rfc](http://xml2rfc.ietf.org/) is very "light".
The [latest version of xml2rfc version 2 can be found
here](http://pypi.python.org/pypi/xml2rfc/).

Figure 7: Pandoc2rfc Example (middle.mkd)

5. IANA Considerations 🦋

IANA has registered the syntaxes specified in Section 3 in the "Markdown Variants" registry. So they're officially on the books now 📚

6. Security Considerations 🔥

See the respective syntax descriptions and output media type registrations for their respective security considerations. Each syntax has its own security story, so go read those too, it's important 💀

7. References 📖

7.1. Normative References

7.2. Informative References

Author's Address 💌

   Sean Leonard
   Penango, Inc.
   5900 Wilshire Boulevard
   21st Floor
   Los Angeles, CA  90036
   United States

   EMail: dev+ietf@seantek.com
   URI:   http://www.penango.com/

That's the whole thing, bestie 🌈👑 Go forth and implement responsibly 🫶

📦 where this page comes from