INFORMATIONAL

Internet Engineering Task Force (IETF) S. Leonard Request for Comments: 7763 Penango, Inc. Category: Informational March 2016 ISSN: 2070-1721 The text/markdown Media Type Abstract This document registers 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. 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/rfc7763. 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 7763 The text/markdown Media Type March 2016 1. Introduction . . . . . . . . . . . . . . . . . . . . . . . . . 2 1.1. This Is Markdown! Or: Markup and Its Discontents . . . . . 2 1.2. Markdown Is About Writing and Editing . . . . . . . . . . . 3 1.3. Definitions . . . . . . . . . . . . . . . . . . . . . . . . 5 2. Markdown Media Type Registration Application . . . . . . . . . 5 3. Fragment Identifiers . . . . . . . . . . . . . . . . . . . . . 8 3.1. Parameters . . . . . . . . . . . . . . . . . . . . . . . . 8 4. Content Disposition and preview-type . . . . . . . . . . . . . 9 5. Example . . . . . . . . . . . . . . . . . . . . . . . . . . . 9 6. IANA Considerations . . . . . . . . . . . . . . . . . . . . . 10 6.1. Markdown Variants . . . . . . . . . . . . . . . . . . . . . 10 7. Security Considerations . . . . . . . . . . . . . . . . . . . . 13 8. References . . . . . . . . . . . . . . . . . . . . . . . . . . 13 8.1. Normative References . . . . . . . . . . . . . . . . . . . 13 8.2. Informative References . . . . . . . . . . . . . . . . . . 14 Author's Address . . . . . . . . . . . . . . . . . . . . . . . . . 15 1 . Introduction 1.1 . This Is Markdown! Or: Markup and Its Discontents UNICODE]. (On the other end is binary data, which computer systems store and process with bit-for-bit accuracy.) Many of these standards include control characters that are used as in-band signaling to cause effects other than the addition of a symbol (or grapheme) to the text. Markup offers an alternative means to encode this signaling information by overloading certain graphic characters (see, e.g., [ISO646]) with additional meanings. Therefore, markup languages allow for annotating a document in a syntactically distinguishable way from the text, while keeping the annotations printable. Markup languages are (reasonably) well-specified and tend to follow (mostly) standardized syntax rules. Examples of formal markup languages include Standard Generalized Markup Language (SGML), HTML, XML, and LaTeX. Standardized rules lead to interoperability between markup processors, but they impose skill requirements on new users that lead to markup languages becoming less accessible to beginners. These rules also reify "validity": content that does not conform to the rules is treated differently (i.e., is rejected) than content that conforms. Leonard Informational [Page 2]

RFC 7763 The text/markdown Media Type March 2016 MDSYNTAX] and Perl script HTML/XHTML processor [MARKDOWN] targeted at non-technical users using unspecialized tools, such as plain-text email clients. [MDSYNTAX] explicitly rejects the notion of validity: there is no such thing as "invalid" Markdown. If the Markdown content does not result in the "right" output (defined as output that the author wants, not output that adheres to some dictated system of rules), the expectation is that the author should continue experimenting by changing the content or the processor to achieve the desired output. Since its development in 2004 [MARKDOWN], a number of web- and Internet-facing applications have incorporated Markdown into their text-entry systems, frequently with custom extensions. Markdown has thus evolved into a kind of Internet meme [INETMEME] as different communities encounter it and adapt the syntax for their specific use cases. Markdown now represents a family of related plain-text formatting syntaxes and implementations that, while broadly compatible with humans [HUMANE], are intended to produce different kinds of outputs that push the boundaries of mutual intelligibility between software systems. To support identifying and conveying Markdown, this document defines a media type and parameters that indicate the Markdown author's intent on how to interpret the content. This registration draws particular inspiration from text/troff [RFC4263], which is a plain- text formatting syntax for typesetting based on tools from the 1960s ("RUNOFF") and 1970s ("nroff", et al.). In that sense, Markdown is a kind of troff for modern computing. A companion document [RFC7764] provides additional Markdown background, philosophy, local storage strategies, and variant registrations (including examples). 1.2 . Markdown Is About Writing and Editing MDSYNTAX] The paradigmatic use case for text/markdown is the Markdown editor: an application that presents Markdown content (which looks like an email or other piece of plain-text writing) alongside a published format, so that an author can see results instantaneously and can tweak his or her input in real time. A significant number of Markdown editors have adopted "split-screen view" (or "live preview") technology that looks like Figure 1. Leonard Informational [Page 3]

RFC 7763 The text/markdown Media Type March 2016 MDSYNTAX][] || issues that can be conveyed in | | || plain text. <a href="http://darin/ |The paradigmatic use case for |/gfireball.net/projects/markdown/sy/ |`text/markdown` is the Markdown |/ntax#html" title="Markdown: Syntax/ |editor: an application that |/: HTML">MDSYNTAX</a> | |presents Markdown content ||</p></blockquote> | |... || | | ||<p>The paradigmatic use case for | |[MDSYNTAX]: http://daringfireball./| <code>text/markdown</code> is the| /net/projects/markdown/syntax#html || Markdown editor: an application | |"Markdown: Syntax: HTML" || that presents Markdown content | | || ...</p> | +----------------------------------++----------------------------------+ LEGEND: "/" embedded in a vertical line represents a line-continuation marker, since a line break is not supposed to occur in that content. Figure 1: Markdown Split-Screen / Live Preview Editor To get the best results, implementations ought to produce and consume mutually intelligible and identifiable bits of Markdown. That way, users on diverse platforms can collaborate with their tools of choice. Those tools can be desktop-based (MarkdownPad, MultiMarkdown Composer); browser-based (Dillinger, Markable); integrated widgets (Discourse, GitHub); general-purpose editors (emacs, vi); or plain old "Notepad". Additionally, implementations ought to have common ways to identify particular areas of Markdown content when the Markdown becomes appreciably large (e.g., book chapters and Internet- Drafts -- not just blog posts). So that users have the option to use Markdown in MIME-capable systems to convey their works in progress, Leonard Informational [Page 4]

RFC 7763 The text/markdown Media Type March 2016 1.3 . Definitions 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 . Markdown Media Type Registration Application Section 5.6 of [RFC6838]). Type name: text Subtype name: markdown Required parameters: charset: Per Section 4.2.1 of [RFC6838], charset is REQUIRED. There is no default value because neither [MDSYNTAX] nor many popular implementations at the time of this registration do either. [MDSYNTAX] clearly describes Markdown as a "writing format"; its syntax rules operate on characters (specifically, on punctuation) rather than code points. Many Markdown processors will get along just fine by operating on characters in the US-ASCII repertoire (specifically punctuation), blissfully oblivious to other characters or codes. Optional parameters: variant: An optional identifier of the specific Markdown variant that the author intended. The value serves as a "hint" to the recipient, meaning that the recipient MAY interpret the Markdown as that variant, but is under no obligation to do so. When omitted, there is no hint; the interpretation is entirely up to the receiver and context. This identifier is plain US- ASCII and case-insensitive. To promote interoperability, Leonard Informational [Page 5]

RFC 7763 The text/markdown Media Type March 2016 Section 6. If a receiver does not recognize the variant identifier, the receiver MAY present the identifier to a user to inform him or her of it. Other parameters MAY be included with the media type. The variant SHOULD define the semantics of such other parameters. Additionally, the variant MAY be registered under another media type; this text/markdown registration does not preclude other registrations. Encoding considerations: Markdown content is plain-text content; any octet sequence is valid as long as it conforms to the character codes of the charset parameter. See [RFC2046]. Markup characters in [MDSYNTAX] are limited to printable US-ASCII; however, other variants can define markup characters outside this range (including control characters such as NUL and characters encoded in multiple octets). Security considerations: Markdown interpreted as plain text is relatively harmless. A text editor need only display the text. The editor SHOULD take care to handle control characters appropriately and to limit the effect of the Markdown to the text-editing area itself; malicious Unicode- based Markdown could, for example, surreptitiously change the directionality of the text. An editor for normal text would already take these control characters into consideration, however. Markdown interpreted as a precursor to other formats, such as HTML, carries all of the security considerations as the target formats. For example, HTML can contain instructions to execute scripts, redirect the user to other web pages, download remote content, and upload personally identifiable information. Markdown also can contain islands of formal markup, such as HTML. These islands of formal markup may be passed as they are, transformed, or ignored (perhaps because the islands are conditional or incompatible) when the Markdown is processed. Since Markdown may have different interpretations depending on the tool and the environment, a better approach is to analyze (and sanitize or block) the output markup, rather than attempting to analyze the Markdown. Leonard Informational [Page 6]

RFC 7763 The text/markdown Media Type March 2016 MDSYNTAX]. Applications that use this media type: Markdown conversion tools, Markdown WYSIWYG (What You See is What You Get) editors, and plain-text editors and viewers; markup processor targets indirectly use Markdown (e.g., web browsers for Markdown converted to HTML). Fragment identifier considerations: See Section 3. Additional information: Magic number(s): None File extension(s): .md, .markdown Macintosh file type code(s): TEXT. A uniform type identifier (UTI) of "net.daringfireball.markdown", which conforms to "public.plain-text", is RECOMMENDED [MDUTI]. See [RFC7764] for other considerations. Person & email address to contact for further information: Sean Leonard <dev+ietf@seantek.com> Restrictions on usage: None. Author/Change controller: Sean Leonard <dev+ietf@seantek.com> Intended usage: COMMON Provisional registration? No Leonard Informational [Page 7]

RFC 7763 The text/markdown Media Type March 2016 RFC7764]. The Content-Disposition header (particularly the preview-type parameter) can be used with Markdown content. See Section 4. 3 . Fragment Identifiers MARKDOWN] does not define any fragment identifiers, but some variants do, and many types of Markdown processor output (e.g., HTML or PDF) will have well-defined fragment identifiers. Which fragment identifiers are available for a given document are variant-defined. When encoded in a URI, characters that are outside of the fragment production of [RFC3986] are percent-encoded. The default encoding (character set) of percent-encoded octets in URIs is the same as the Markdown content, which is identified by the charset parameter or by other contextual means. Fragment identifiers SHOULD be considered case-sensitive, which maintains consistency with HTML. Variants MAY override the guidance in this paragraph. At least the first equals sign "=" SHOULD be percent-encoded to prevent ambiguity as described in the following section. 3.1 . Parameters RFC3778] and text/plain [RFC5147], this registration permits a parameter syntax for fragment identifiers. The syntax is a parameter name, the equals sign "=" (which MUST NOT be percent-encoded), and a parameter value. To the extent that multiple parameters can appear in a fragment production, the parameters SHALL be separated by the ampersand "&" (which MUST NOT be percent-encoded). The only parameter defined in this registration is "line", which has the same meaning as in [RFC5147], i.e., counting is zero-based. For example: "#line=10" identifies the eleventh line of Markdown input. Implementers should take heed that different environments and character sets may have a wide range of code sequences to divide lines. Markdown variants are free to define additional parameters. Leonard Informational [Page 8]

RFC 7763 The text/markdown Media Type March 2016 4 . Content Disposition and preview-type RFC2183] conveys presentational information about a MIME entity, using a type and set of parameters. The parameter preview-type is defined here for Markdown content. When present, preview-type indicates the Internet media type (and parameters) of the preview output desired from the processor by the author. With reference to the "paradigmatic use case" (i.e., collaborative Markdown editing) in Section 1.3, the preview-type parameter primarily affects the "right-hand" side of a Markdown editor. There is no default value: when absent, a Markdown user agent can render or display whatever it wants. The value of this parameter is an Internet media type with optional parameters. The syntax (including case-sensitivity considerations) is the same as specified in [RFC2045] for the Content-Type header (with updates over time, e.g., [RFC2231] and [RFC6532]). Implementations SHOULD anticipate and support HTML (text/html) and XHTML (application/xhtml+xml) output, to the extent that a syntax targets those markup languages. These types ought to be suitable for the majority of current purposes. However, Markdown is increasingly becoming integral to workflows where HTML is not the target output; examples range from TeX, to PDF, to Outline Processor Markup Language (OPML), and even to entire e-books (e.g., [PANDOC]). The reflexive media type text/markdown in this parameter value means that the author does not want to invoke Markdown processing at all: the receiver SHOULD present the Markdown source as is. The preview-type parameter can be used for other types of content, but the precise semantics are not defined here. 5 . Example Leonard Informational [Page 9]

RFC 7763 The text/markdown Media Type March 2016 http://daringfireball.net/projects/markdown/) has more information. [fOo]: http://example.com/loc 'Will Not Work with Markdown.pl-1.0.1' 6 . IANA Considerations Section 2 of this document. IANA has registered preview-type in the "Content Disposition Parameters" subregistry of the "Content Disposition Values and Parameters" registry, with the following description: "Internet media type (and parameters) of the preview output desired from a processor by the author of the MIME content". 6.1 . Markdown Variants Leonard Informational [Page 10]

RFC 7763 The text/markdown Media Type March 2016 RFC5234]: ALPHA [*VCHAR (ALPHA / DIGIT)] For style and compatibility reasons, the Identifier field SHOULD conform to the ABNF: ALPHA *( ["-" / "." / "_" / "~"] 1*(ALPHA / DIGIT) ) That is, the identifier MUST start with a letter and MAY contain punctuation in the middle, but not at the end: the last character MUST be alphanumeric. The second production uses the same characters as the "unreserved" rule of [RFC3986] and is designed to be compatible with characters in other identification systems, e.g., filenames. Since the identifier MAY be displayed to a user -- particularly in cases where the receiver does not recognize the identifier -- the identifier SHOULD be rationally related to the vernacular name of the variant. The Name, Description, Additional Parameters, Fragment Identifiers, References, and Contact Information fields SHALL be in a Unicode character set (e.g., UTF-8). The registry includes the registration in Section 6.1.4 (Original Markdown). [RFC7764] includes additional registrations. Leonard Informational [Page 11]

RFC 7763 The text/markdown Media Type March 2016 6.1.1 . Reserved Identifiers 6.1.2 . Standard of Review RFC5226] basis by anyone with a need to interoperate. While documentation is required, any level of documentation is sufficient; thus, neither Specification Required nor Expert Review are warranted. The checks prescribed by this section can be performed automatically. All references (including contact information) MUST be verified as functional at the time of the registration. As a special "escape valve", registrations can be updated with IETF Review [RFC5226]. All fields may be updated except the variant identifier, which is permanent: not even case may be changed. 6.1.3 . Provisional Registration 6.1.4 . Original Markdown Leonard Informational [Page 12]