    Internet Engineering Task Force (IETF)                        S. Leonard
    Request for Comments: 7764                                 Penango, Inc.
    Category: Informational                                       March 2016
    ISSN: 2070-1721

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

    Abstract

       This document elaborates upon the text/markdown media type for use
       with Markdown, a family of plain-text formatting syntaxes that
       optionally can be converted to formal markup languages such as HTML.
       Background information, local storage strategies, and additional
       syntax registrations are supplied.

    Status of This Memo

       This document is not an Internet Standards Track specification; it is
       published for informational purposes.

       This document is a product of the Internet Engineering Task Force
       (IETF).  It represents the consensus of the IETF community.  It has
       received public review and has been approved for publication by the
       Internet Engineering Steering Group (IESG).  Not all documents
       approved by the IESG are a candidate for any level of Internet
       Standard; see Section 2 of RFC 5741.

       Information about the current status of this document, any errata,
       and how to provide feedback on it may be obtained at
       http://www.rfc-editor.org/info/rfc7764.

    Copyright Notice

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

       This document is subject to BCP 78 and the IETF Trust's Legal
       Provisions Relating to IETF Documents
       (http://trustee.ietf.org/license-info) in effect on the date of
       publication of this document.  Please review these documents
       carefully, as they describe your rights and restrictions with respect
       to this document.  Code Components extracted from this document must
       include Simplified BSD License text as described in Section 4.e of
       the Trust Legal Provisions and are provided without warranty as
       described in the Simplified BSD License.

    Leonard                       Informational                     [Page 1]

    RFC 7764         Guidance on Markdown and text/markdown       March 2016

    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

    Leonard                       Informational                     [Page 2]

    RFC 7764         Guidance on Markdown and text/markdown       March 2016

    1.  Dive into Markdown

       This document serves as an informational companion to [RFC7763], the
       text/markdown media type registration.  It should be considered
       jointly with [RFC7763].

             "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

       In computer systems, textual data is stored and processed using a
       continuum of techniques.  On the one end is plain text: computer-
       encoded text that consists only of a sequence of code points from a
       given standard, with no other formatting or structural information
       [UNICODE].  Plain text provides /some/ fixed facilities for
       formatting instructions (namely, codes in the character set that have
       meanings other than "represent this character graphically on the
       output medium"); however, these facilities are not particularly
       extensible.  Compare with Section 4.2.1 of [RFC6838].  Applications
       may neuter the effects of these special characters by prohibiting
       them or by ignoring their dictated meanings, as is the case with how
       modern applications treat most control characters in US-ASCII.  On
       this end, any text reader or editor that interprets the character set
       can be used to see or manipulate the text.  If some characters are
       corrupted, the corruption is unlikely to affect the ability of a
       computer system to process the text (even if the human meaning is
       changed).

       On the other end is binary data: a sequence of bits intended for some
       computer application to interpret and act upon.  Binary formats are
       flexible in that they can store non-textual data efficiently (perhaps
       storing no text at all, or only storing certain kinds of text for
       very specialized purposes).  Binary formats require an application to
       be coded specifically to handle the format; no partial
       interoperability is possible.  Furthermore, if even one bit is
       corrupted in a binary format, it may prevent an application from
       processing any of the data correctly.

       Between these two extremes lies formatted text, i.e., text that
       includes non-textual information coded in a particular way, that
       affects the interpretation of the text by computer programs.
       Formatted text is distinct from plain text and binary data in that
       the non-textual information is encoded into textual characters that
       are assigned specialized meanings not defined by the character set.
       With a regular text editor and a standard keyboard (or other standard
       input mechanism), a user can enter these textual characters to
       express the non-textual meanings.  For example, a character like "<"

    Leonard                       Informational                     [Page 3]

    RFC 7764         Guidance on Markdown and text/markdown       March 2016

       no longer means "LESS-THAN SIGN"; it means the start of a tag or
       element that affects the document in some way.

       On the formal end of the formatted text spectrum is markup, a family
       of languages for annotating a document in such a way that the
       annotations are syntactically distinguishable from the text.  Markup
       languages are (reasonably) well-specified and tend to follow (mostly)
       standardized syntax rules.  Examples of markup languages include
       Standard Generalized Markup Language (SGML), HTML, XML, and LaTeX.
       Standardized rules lead to interoperability between markup
       processors, but a skill requirement for new (human) users of the
       language that they learn these rules in order to do useful work.
       This imposition makes markup less accessible for non-technical users
       (i.e., users who are unwilling or unable to invest in the requisite
       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 of the spectrum are lightweight markup languages.
       In comparison with formal markup like XML, lightweight markup uses
       simple syntax, and is designed to be easy for humans to enter with
       basic text editors.  Markdown, the subject of this document, is an
       /informal/ plain-text formatting syntax that is intentionally
       targeted at non-technical users (i.e., users upon whom little to no
       skill development is imposed) using unspecialized tools (i.e., text
       boxes).  Jeff Atwood once described these informal markup languages
       as "humane" [HUMANE].

    1.2.  Markdown Design Philosophy

       Markdown specifically is a family of syntaxes that are based on the
       original work of John Gruber with substantial contributions from
       Aaron Swartz, released in 2004 [MARKDOWN].  Since its release, a
       number of web or web-facing applications have incorporated Markdown
       into their text-entry systems, frequently with custom extensions.
       Fed up with the complexity and security pitfalls of formal markup
       languages (e.g., HTML5) and proprietary binary formats (e.g.,
       commercial word-processing software), yet unwilling to be confined to
       the restrictions of plain text, many users have turned to Markdown
       for document processing.  Whole toolchains now exist to support
       Markdown for online and offline projects.

    Leonard                       Informational                     [Page 4]

    RFC 7764         Guidance on Markdown and text/markdown       March 2016

       Informality is a bedrock premise of Gruber's design.  Gruber created
       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 was automatically copied via
       trackbacks across other sites [DIN2MD].  These scenarios led Gruber
       to believe that clients (e.g., web browsers) SHOULD try to make sense
       of data that they receive, rather than rejecting data simply because
       it fails to adhere to 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].) As a result, there is no
       such thing as "invalid" Markdown, there is no standard demanding
       adherence to the Markdown syntax, and there is no governing body that
       guides or impedes its development.  If the Markdown syntax does not
       result in the "right" output (defined as output that the author
       wants, not output that adheres to some dictated system of rules),
       Gruber's view is that the author either should keep on experimenting
       or should change the processor to address the author's particular
       needs (see [MARKDOWN] Readme and [MD102b8] perldoc; see also
       [CATPICS]).

    1.3.  Uses of Markdown

       Since its introduction in 2004, Markdown has enjoyed remarkable
       success.  Markdown works for users for three key reasons.  First, the
       markup instructions (in text) look similar to the markup that they
       represent; therefore, the cognitive burden to learn the syntax is
       low.  Second, the primary arbiter of the syntax's success is *running
       code*.  The tool that converts the Markdown to a presentable format,
       and not a series of formal pronouncements by a standards body, is the
       basis for whether syntactic elements matter.  Third, Markdown has
       become something of an Internet meme [INETMEME], in that Markdown
       gets received, reinterpreted, and reworked as additional communities
       encounter it.  There are communities that are using Markdown for
       scholarly writing [OCCASION], for screenplays [FOUNTAIN], and even
       for mathematical formulae [MATHDOWN].  Clearly, a screenwriter has no
       use for specialized Markdown syntax for mathematicians; likewise,
       mathematicians do not need to identify characters or props in common
       ways.  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.

    Leonard                       Informational                     [Page 5]

    RFC 7764         Guidance on Markdown and text/markdown       March 2016

    1.4.  Uses of Labeling Markdown Content as text/markdown

       The primary 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).  From this description, it is
       apparent that appending ".markdown" to the end of a filename is not a
       sufficient means to identify Markdown.  Filenames are properties of
       files in file systems, but Markdown frequently exists in databases or
       content management systems (CMSes) where the file metaphor does not
       apply.  One CMS [RAILFROG] uses media types to select appropriate
       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 must be supplied via supplementary means in an encapsulating
       protocol, format, or convention.  The relationship between the
       content and the metadata is not 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.

    Leonard                       Informational                     [Page 6]

    RFC 7764         Guidance on Markdown and text/markdown       March 2016

    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.  While an individual
       member of (or software tool for) a community can probably look at
       some "Markdown" and declare its meaning intuitively obvious, 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 in 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

    Leonard                       Informational                     [Page 7]

    RFC 7764         Guidance on Markdown and text/markdown       March 2016

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

    Leonard                       Informational                     [Page 8]

    RFC 7764         Guidance on Markdown and text/markdown       March 2016

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

    Leonard                       Informational                     [Page 9]

    RFC 7764         Guidance on Markdown and text/markdown       March 2016

    2.7.2.  Git

       This subsection covers a preservation strategy in Git [GIT], a common
       distributed version control system.

       Versions of Git as of the time of this writing do not support
       arbitrary metadata storage; however, third-party projects add this
       support.

       If Git is used without a metadata storage service, then a reasonable
       strategy is to include the variant identifier in the filename
       (Section 2.1).  The default text encoding SHOULD be UTF-8.  For other
       or different properties, a header file SHOULD be recorded alongside
       the Markdown file (Section 2.2).

       If a metadata storage service is used with Git, then use a convention
       that is most analogous to the service.  For example, the "metastore"
       project emulates extended attributes (xattrs) of a POSIX-like system,
       so whatever "xattr" methodology is developed would be usable with
       metastore and Git.

    3.  Registration Templates for Common Markdown Syntaxes

       The purpose of this section is to register certain syntaxes in the
       "Markdown Variants" registry [RFC7763] because they illustrate
       particularly interesting use cases or are broadly applicable to the
       Internet community; thus, these syntaxes would benefit from the level
       of review associated with publication as IETF documents.

    3.1.  MultiMarkdown

       Identifier: MultiMarkdown

       Name: MultiMarkdown

       Description:
          MultiMarkdown (MMD) is a superset of "Original".  It adds multiple
          syntax features (tables, footnotes, and citations, to name a few)
          and is intended to output to various formats.  Additionally, it
          builds in "smart" typography for various languages (proper left-
          and right-sided quotes, for example).

    Leonard                       Informational                    [Page 10]

    RFC 7764         Guidance on Markdown and text/markdown       March 2016

       Additional Parameters:
          options: String with zero or more of the following tokens
          delimited 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:
          "Original" with the following differences:
          1. Multiple underscores in words
          2. URL (URI) autolinking
          3. Strikethrough
          4. Fenced code blocks
          5. Syntax highlighting
          6. Tables (- for rows; | for columns; : for alignment)
          7. Only some HTML allowed; sanitization is integral to 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>

    Leonard                       Informational                    [Page 11]

    RFC 7764         Guidance on Markdown and text/markdown       March 2016

    3.3.  Pandoc

       Identifier: pandoc

       Name: Pandoc

       Description:
          Markdown is designed to be easy to write and to read: the content
          should be publishable as-is, as plain text, without looking like
          it has been marked up with tags or formatting instructions.  Yet
          whereas "Original" has HTML generation in mind, pandoc is designed
          for multiple output formats.  Thus, while pandoc allows the
          embedding of raw HTML, it discourages it, and provides other, non-
          HTMLish ways of representing important document elements like
          definition lists, tables, mathematics, and footnotes.

       Additional Parameters:
          extensions: String with an optional starting syntax token,
                      followed by a "+" and "-" delimited list of extension
                      tokens.  "+" preceding an extension token turns the
                      extension on; "-" turns the extension off.  The
                      starting syntax tokens are "markdown",
                      "markdown_strict", "markdown_phpextra", and
                      "markdown_github".  If no starting syntax token is
                      given, "markdown" is assumed.  The extension tokens
                      include:

                      Extensions to turn off (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

    Leonard                       Informational                    [Page 12]

    RFC 7764         Guidance on Markdown and text/markdown       March 2016

                      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 (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 (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/>

    Leonard                       Informational                    [Page 13]

    RFC 7764         Guidance on Markdown and text/markdown       March 2016

    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.  Fountain
          allows you to 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 following
          fragment identifiers, the <key> and <sec*> productions MUST have
          "/" characters percent-encoded.

          #/       Title Page (acts as metadata).
          #/<key>  Title Page; <key> is the key string.
          #<sec1> *("/" <secn>)
                Section or subsection.  The <sec1>..<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 preceding the subsection with higher-order
                sections.  If the section hierarchy "skips", e.g., # to ###,
                use a blank section name, e.g.,
                #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 specification for
          Markdown, along with a suite of comprehensive tests to validate

    Leonard                       Informational                    [Page 14]

    RFC 7764         Guidance on Markdown and text/markdown       March 2016

          Markdown implementations against this specification.  The
          maintainers believe that CommonMark is necessary, even essential,
          for the future of Markdown.

          Compared to "Original", CommonMark is much longer and in a few
          instances contradicts "Original" based on seasoned experience.
          Although CommonMark specifically does not mandate any particular
          encoding for the input content, CommonMark draws in more of
          Unicode, UTF-8, and HTML (including HTML5) than "Original".

          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; it has a number
          of backends for generating HTML, LaTeX, and Markdown again.
          kramdown-rfc2629 is an additional backend to that: It allows the
          generation of XML2RFC XML markup (originally known as markup that
          is RFC 2629 compliant, now documented in RFC 7749).

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

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

    Leonard                       Informational                    [Page 15]

    RFC 7764         Guidance on Markdown and text/markdown       March 2016

    3.7.  rfc7328 (Pandoc2rfc)

       Identifier: rfc7328

       Name: Pandoc2rfc

       Description:
          Pandoc2rfc allows authors to write in "pandoc" that is then
          transformed to XML and given to xml2rfc.  The conversions are, in
          a way, amusing, as we start off with (almost) plain text, use
          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 implementing some
       features currently not available with the plain Markdown syntax.
       Markdown Extra is available as a separate parser class in PHP
       Markdown Lib.  Other implementations include Maruku (Ruby) and Python
       Markdown.  Markdown Extra is 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 (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>

    Leonard                       Informational                    [Page 16]

    RFC 7764         Guidance on Markdown and text/markdown       March 2016

    4.  Examples for Common Markdown Syntaxes

       This section provides examples of the variants in Section 3.

    4.1.  MultiMarkdown

    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]

    [^somesamplefootnote]: Here is the text of the footnote itself.

                        Figure 1: MultiMarkdown Example

    Leonard                       Informational                    [Page 17]

    RFC 7764         Guidance on Markdown and text/markdown       March 2016

    4.2.  GitHub-Flavored Markdown

    # 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

    Leonard                       Informational                    [Page 18]

    RFC 7764         Guidance on Markdown and text/markdown       March 2016

    4.3.  Pandoc

    % 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

    Leonard                       Informational                    [Page 19]

    RFC 7764         Guidance on Markdown and text/markdown       March 2016

    4.4.  Fountain (Fountain.io)

    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

    Leonard                       Informational                    [Page 20]

    RFC 7764         Guidance on Markdown and text/markdown       March 2016

    4.5.  CommonMark

       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

    Leonard                       Informational                    [Page 21]

    RFC 7764         Guidance on Markdown and text/markdown       March 2016

    4.6.  kramdown-rfc2629 (Markdown for RFCs)

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

    Leonard                       Informational                    [Page 22]

    RFC 7764         Guidance on Markdown and text/markdown       March 2016

    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}
    =====================

    ~~~~~~~~~~

    Leonard                       Informational                    [Page 23]

    RFC 7764         Guidance on Markdown and text/markdown       March 2016

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

    Leonard                       Informational                    [Page 24]

    RFC 7764         Guidance on Markdown and text/markdown       March 2016

    4.7.  rfc7328 (Pandoc2rfc)

       Pandoc2rfc expects multiple files as input.  The following figure is
       example of "middle.mkd".

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

    Leonard                       Informational                    [Page 25]

    RFC 7764         Guidance on Markdown and text/markdown       March 2016

    6.  Security Considerations

       See the respective syntax descriptions and output media type
       registrations for their respective security considerations.

    7.  References

    7.1.  Normative References

       [MARKDOWN] Gruber, J., "Daring Fireball: Markdown", December 2004,
                  <http://daringfireball.net/projects/markdown/>.

       [MDSYNTAX] Gruber, J., "Daring Fireball: Markdown Syntax
                  Documentation",
                  <http://daringfireball.net/projects/markdown/syntax>.

       [RFC2119]  Bradner, S., "Key words for use in RFCs to Indicate
                  Requirement Levels", BCP 14, RFC 2119,
                  DOI 10.17487/RFC2119, March 1997,
                  <http://www.rfc-editor.org/info/rfc2119>.

       [RFC5322]  Resnick, P., Ed., "Internet Message Format", RFC 5322,
                  DOI 10.17487/RFC5322, October 2008,
                  <http://www.rfc-editor.org/info/rfc5322>.

       [RFC6657]  Melnikov, A. and J. Reschke, "Update to MIME regarding
                  "charset" Parameter Handling in Textual Media Types",
                  RFC 6657, DOI 10.17487/RFC6657, July 2012,
                  <http://www.rfc-editor.org/info/rfc6657>.

       [RFC7763]  Leonard, S., "The text/markdown Media Type", RFC 7763,
                  DOI 10.17487/RFC7763, March 2016,
                  <http://www.rfc-editor.org/info/rfc7763>.

    7.2.  Informative References

       [UNICODE]  The Unicode Consortium, "The Unicode Standard, Version
                  8.0", (Mountain View, CA: The Unicode Consortium, 2015.
                  ISBN 978-1-936213-10-8),
                  <http://www.unicode.org/versions/Unicode8.0.0/>.

       [HUMANE]   Atwood, J., "Is HTML a Humane Markup Language?", May 2008,
                  <http://blog.codinghorror.com/
                  is-html-a-humane-markup-language/>.

       [DIN2MD]   Gruber, J., "Dive Into Markdown", March 2004,
                  <http://daringfireball.net/2004/03/dive_into_markdown>.

    Leonard                       Informational                    [Page 26]

    RFC 7764         Guidance on Markdown and text/markdown       March 2016

       [MD102b8]  Gruber, J., "Subject: [ANN] Markdown.pl 1.0.2b8", message
                  to the markdown-discuss mailing list, 9 May 2007,
                  <http://six.pairlist.net/pipermail/markdown-discuss/
                  2007-May/000615.html>,
                  <http://daringfireball.net/projects/downloads/
                  Markdown_1.0.2b8.tbz>.

       [CATPICS]  Gruber, J. and M. Arment, "The Talk Show: Ep. 88: 'Cat
                  Pictures' (Side 1)", July 2014,
                  <http://daringfireball.net/thetalkshow/2014/07/19/ep-088>.

       [INETMEME] Solon, O., "Richard Dawkins on the internet's hijacking of
                  the word 'meme'", June 2013,
                  <http://www.wired.co.uk/news/archive/2013-06/20/
                  richard-dawkins-memes>,
                  <http://www.webcitation.org/6HzDGE9Go>.

       [MULTIMD]  Penney, F., "MultiMarkdown",
                  <http://fletcherpenney.net/multimarkdown/>.

       [PANDOC]   MacFarlane, J., "Pandoc",
                  <http://johnmacfarlane.net/pandoc/>.

       [RAILFROG] Railfrog Team, "Railfrog", April 2009,
                  <http://railfrog.com/>.

       [RFC793]   Postel, J., "Transmission Control Protocol", STD 7,
                  RFC 793, DOI 10.17487/RFC0793, September 1981,
                  <http://www.rfc-editor.org/info/rfc793>.

       [RFC6533]  Hansen, T., Ed., Newman, C., and A. Melnikov,
                  "Internationalized Delivery Status and Disposition
                  Notifications", RFC 6533, DOI 10.17487/RFC6533, February
                  2012, <http://www.rfc-editor.org/info/rfc6533>.

       [RFC6838]  Freed, N., Klensin, J., and T. Hansen, "Media Type
                  Specifications and Registration Procedures", BCP 13,
                  RFC 6838, DOI 10.17487/RFC6838, January 2013,
                  <http://www.rfc-editor.org/info/rfc6838>.

       [XML1.0-5] Bray, T., Paoli, J., Sperberg-McQueen, M., Maler, E., and
                  F. Yergeau, "Extensible Markup Language (XML) 1.0 (Fifth
                  Edition)", W3C Recommendation REC-xml-20081126, November
                  2008, <http://www.w3.org/TR/2008/REC-xml-20081126>.

    Leonard                       Informational                    [Page 27]

    RFC 7764         Guidance on Markdown and text/markdown       March 2016

       [OCCASION] Shieber, S., "Switching to Markdown for scholarly article
                  production", August 2014,
                  <http://blogs.law.harvard.edu/pamphlet/2014/08/29/
                  switching-to-markdown-for-scholarly-article-production/>.

       [FOUNTAIN] Maschwitz, S. and J. August, "Fountain | A markup language
                  for screenwriting.", <http://fountain.io/>.

       [MATHDOWN] Cherniavsky-Paskin, B., "math in markdown",
                  <https://github.com/cben/mathdown/wiki/math-in-markdown>.

       [SVN]      Apache Subversion, December 2015,
                  <https://subversion.apache.org/>.

       [GIT]      Git, <http://git-scm.com/>.

    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/

    Leonard                       Informational                    [Page 28]