draft-ietf-appsawg-text-markdown-12.txt   rfc7763.txt 
Applications Area Working Group S. Leonard Internet Engineering Task Force (IETF) S. Leonard
Internet-Draft Penango, Inc. Request for Comments: 7763 Penango, Inc.
Intended Status: Informational October 17, 2015 Category: Informational March 2016
Expires: April 19, 2016 ISSN: 2070-1721
The text/markdown Media Type The text/markdown Media Type
draft-ietf-appsawg-text-markdown-12
Abstract Abstract
This document registers the text/markdown media type for use with This document registers the text/markdown media type for use with
Markdown, a family of plain text formatting syntaxes that optionally Markdown, a family of plain-text formatting syntaxes that optionally
can be converted to formal markup languages such as HTML. can be converted to formal markup languages such as HTML.
Status of this Memo Status of This Memo
This Internet-Draft is submitted in full conformance with the This document is not an Internet Standards Track specification; it is
provisions of BCP 78 and BCP 79. published for informational purposes.
Internet-Drafts are working documents of the Internet Engineering This document is a product of the Internet Engineering Task Force
Task Force (IETF). Note that other groups may also distribute (IETF). It represents the consensus of the IETF community. It has
working documents as Internet-Drafts. The list of current Internet- received public review and has been approved for publication by the
Drafts is at http://datatracker.ietf.org/drafts/current/. 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.
Internet-Drafts are draft documents valid for a maximum of six months Information about the current status of this document, any errata,
and may be updated, replaced, or obsoleted by other documents at any and how to provide feedback on it may be obtained at
time. It is inappropriate to use Internet-Drafts as reference http://www.rfc-editor.org/info/rfc7763.
material or to cite them other than as "work in progress."
Copyright Notice Copyright Notice
Copyright (c) 2015 IETF Trust and the persons identified as the Copyright (c) 2016 IETF Trust and the persons identified as the
document authors. All rights reserved. document authors. All rights reserved.
This document is subject to BCP 78 and the IETF Trust's Legal This document is subject to BCP 78 and the IETF Trust's Legal
Provisions Relating to IETF Documents Provisions Relating to IETF Documents
(http://trustee.ietf.org/license-info) in effect on the date of (http://trustee.ietf.org/license-info) in effect on the date of
publication of this document. Please review these documents publication of this document. Please review these documents
carefully, as they describe your rights and restrictions with respect carefully, as they describe your rights and restrictions with respect
to this document. Code Components extracted from this document must to this document. Code Components extracted from this document must
include Simplified BSD License text as described in Section 4.e of include Simplified BSD License text as described in Section 4.e of
the Trust Legal Provisions and are provided without warranty as the Trust Legal Provisions and are provided without warranty as
described in the Simplified BSD License. described in the Simplified BSD License.
Table of Contents Table of Contents
1. Introduction . . . . . . . . . . . . . . . . . . . . . . . . . 2 1. Introduction . . . . . . . . . . . . . . . . . . . . . . . . . 2
1.1. This Is Markdown! Or: Markup and Its Discontents . . . . . 2 1.1. This Is Markdown! Or: Markup and Its Discontents . . . . . 2
1.2. Markdown Is About Writing and Editing . . . . . . . . . . . 3 1.2. Markdown Is About Writing and Editing . . . . . . . . . . . 3
1.3. Definitions . . . . . . . . . . . . . . . . . . . . . . . . 5 1.3. Definitions . . . . . . . . . . . . . . . . . . . . . . . . 5
2. Markdown Media Type Registration Application . . . . . . . . . 5 2. Markdown Media Type Registration Application . . . . . . . . . 5
3. Fragment Identifiers . . . . . . . . . . . . . . . . . . . . . 8 3. Fragment Identifiers . . . . . . . . . . . . . . . . . . . . . 8
3.1. Parameters . . . . . . . . . . . . . . . . . . . . . . . . 8 3.1. Parameters . . . . . . . . . . . . . . . . . . . . . . . . 8
4. Content Disposition and preview-type . . . . . . . . . . . . . 8 4. Content Disposition and preview-type . . . . . . . . . . . . . 9
5. Example . . . . . . . . . . . . . . . . . . . . . . . . . . . 9 5. Example . . . . . . . . . . . . . . . . . . . . . . . . . . . 9
6. IANA Considerations . . . . . . . . . . . . . . . . . . . . . 10 6. IANA Considerations . . . . . . . . . . . . . . . . . . . . . 10
6.1. Markdown Variants . . . . . . . . . . . . . . . . . . . . . 10 6.1. Markdown Variants . . . . . . . . . . . . . . . . . . . . . 10
7. Security Considerations . . . . . . . . . . . . . . . . . . . . 12 7. Security Considerations . . . . . . . . . . . . . . . . . . . . 13
8. References . . . . . . . . . . . . . . . . . . . . . . . . . . 12 8. References . . . . . . . . . . . . . . . . . . . . . . . . . . 13
8.1. Normative References . . . . . . . . . . . . . . . . . . . 13 8.1. Normative References . . . . . . . . . . . . . . . . . . . 13
8.2. Informative References . . . . . . . . . . . . . . . . . . 14 8.2. Informative References . . . . . . . . . . . . . . . . . . 14
Author's Address . . . . . . . . . . . . . . . . . . . . . . . . . 15 Author's Address . . . . . . . . . . . . . . . . . . . . . . . . . 15
1. Introduction 1. Introduction
1.1. This Is Markdown! Or: Markup and Its Discontents 1.1. This Is Markdown! Or: Markup and Its Discontents
In computer systems, textual data is stored and processed using a In computer systems, textual data is stored and processed using a
continuum of techniques. On the one end is plain text: computer- continuum of techniques. On the one end is plain text: computer-
encoded text that consists only of a sequence of code points from a encoded text that consists only of a sequence of code points from a
given standard, with no other formatting or structural information given standard, with no other formatting or structural information
[UNICODE]. (On the other end is binary data, which computer systems [UNICODE]. (On the other end is binary data, which computer systems
store and process with bit-for-bit accuracy.) Many of these standards store and process with bit-for-bit accuracy.) Many of these standards
include control characters that are used as in-band signaling to include control characters that are used as in-band signaling to
cause effects other than the addition of a symbol (or grapheme) to cause effects other than the addition of a symbol (or grapheme) to
the text. the text.
Markup offers an alternative means to encode this signaling Markup offers an alternative means to encode this signaling
information by overloading certain graphic characters (see, e.g., information by overloading certain graphic characters (see, e.g.,
[ISO646]) with additional meanings. Therefore, markup languages allow [ISO646]) with additional meanings. Therefore, markup languages
for annotating a document in a syntactically distinguishable way from allow for annotating a document in a syntactically distinguishable
the text, while keeping the annotations printable. Markup languages way from the text, while keeping the annotations printable. Markup
are (reasonably) well-specified and tend to follow (mostly) languages are (reasonably) well-specified and tend to follow (mostly)
standardized syntax rules. Examples of formal markup languages standardized syntax rules. Examples of formal markup languages
include SGML, HTML, XML, and LaTeX. Standardized rules lead to include Standard Generalized Markup Language (SGML), HTML, XML, and
interoperability between markup processors, but impose skill LaTeX. Standardized rules lead to interoperability between markup
requirements on new users that lead to markup languages becoming less processors, but they impose skill requirements on new users that lead
accessible to beginners. These rules also reify "validity": content to markup languages becoming less accessible to beginners. These
that does not conform to the rules is treated differently (i.e., is rules also reify "validity": content that does not conform to the
rejected) than content that conforms. rules is treated differently (i.e., is rejected) than content that
conforms.
In contrast to formal markup languages, lightweight markup languages In contrast to formal markup languages, lightweight markup languages
use simple syntaxes; they are designed to be easy for humans to enter use simple syntaxes; they are designed to be easy for humans to enter
and understand with basic text editors. Markdown, the subject of this and understand with basic text editors. Markdown, the subject of
document, began as an /informal/ plain text formatting syntax this document, began as an /informal/ plain-text formatting syntax
[MDSYNTAX] and Perl script HTML/XHTML processor [MARKDOWN] targeted [MDSYNTAX] and Perl script HTML/XHTML processor [MARKDOWN] targeted
at non-technical users using unspecialized tools, such as plain text at non-technical users using unspecialized tools, such as plain-text
e-mail clients. [MDSYNTAX] explicitly rejects the notion of validity: email clients. [MDSYNTAX] explicitly rejects the notion of validity:
there is no such thing as "invalid" Markdown. If the Markdown content there is no such thing as "invalid" Markdown. If the Markdown
does not result in the "right" output (defined as output that the content does not result in the "right" output (defined as output that
author wants, not output that adheres to some dictated system of the author wants, not output that adheres to some dictated system of
rules), the expectation is that the author should continue rules), the expectation is that the author should continue
experimenting by changing the content or the processor to achieve the experimenting by changing the content or the processor to achieve the
desired output. desired output.
Since its development in 2004 [MARKDOWN], a number of web- and Since its development in 2004 [MARKDOWN], a number of web- and
Internet-facing applications have incorporated Markdown into their Internet-facing applications have incorporated Markdown into their
text entry systems, frequently with custom extensions. Markdown has text-entry systems, frequently with custom extensions. Markdown has
thus evolved into a kind of Internet meme [INETMEME] as different thus evolved into a kind of Internet meme [INETMEME] as different
communities encounter it and adapt the syntax for their specific use communities encounter it and adapt the syntax for their specific use
cases. Markdown now represents a family of related plain text cases. Markdown now represents a family of related plain-text
formatting syntaxes and implementations that, while broadly formatting syntaxes and implementations that, while broadly
compatible with humans [HUMANE], are intended to produce different compatible with humans [HUMANE], are intended to produce different
kinds of outputs that push the boundaries of mutual intelligibility kinds of outputs that push the boundaries of mutual intelligibility
between software systems. between software systems.
To support identifying and conveying Markdown, this document defines To support identifying and conveying Markdown, this document defines
a media type and parameters that indicate the Markdown author's a media type and parameters that indicate the Markdown author's
intent on how to interpret the content. This registration draws intent on how to interpret the content. This registration draws
particular inspiration from text/troff [RFC4263], which is a plain particular inspiration from text/troff [RFC4263], which is a plain-
text formatting syntax for typesetting based on tools from the 1960s text formatting syntax for typesetting based on tools from the 1960s
("RUNOFF") and 1970s ("nroff", et. al.). In that sense, Markdown is a ("RUNOFF") and 1970s ("nroff", et al.). In that sense, Markdown is a
kind of troff for modern computing. A companion document [MDMTGUID] kind of troff for modern computing. A companion document [RFC7764]
provides additional Markdown background, philosophy, local storage provides additional Markdown background, philosophy, local storage
strategies, and variant registrations (including examples). strategies, and variant registrations (including examples).
1.2. Markdown Is About Writing and Editing 1.2. Markdown Is About Writing and Editing
"HTML is a *publishing* format; Markdown is a *writing* format. "HTML is a *publishing* format; Markdown is a *writing* format.
Thus, Markdown's formatting syntax only addresses issues Thus, Markdown's formatting syntax only addresses issues that can
that can be conveyed in plain text." [MDSYNTAX] be conveyed in plain text." [MDSYNTAX]
The paradigmatic use case for text/markdown is the Markdown editor: The paradigmatic use case for text/markdown is the Markdown editor:
an application that presents Markdown content (which looks like an e- an application that presents Markdown content (which looks like an
mail or other piece of plain text writing) alongside a published email or other piece of plain-text writing) alongside a published
format, so that an author can see results instantaneously and can format, so that an author can see results instantaneously and can
tweak his or her input in real-time. A significant number of Markdown tweak his or her input in real time. A significant number of
editors have adopted "split-screen view" (or "live preview") Markdown editors have adopted "split-screen view" (or "live preview")
technology that looks like Figure 1: technology that looks like Figure 1.
+----------------------------------------------------------------------+ +----------------------------------------------------------------------+
| File Edit (Cloud Stuff) (Fork Me on GitHub) Help | | File Edit (Cloud Stuff) (Fork Me on GitHub) Help |
+----------------------------------------------------------------------+ +----------------------------------------------------------------------+
| [ such-and-such identifier ] [ useful statistics] | | [ such-and-such identifier ] [ useful statistics] |
+----------------------------------++----------------------------------+ +----------------------------------++----------------------------------+
| (plain text, with || (text/html, likely | | (plain text, with || (text/html, likely |
| syntax highlighting) || rendered to screen) | | syntax highlighting) || rendered to screen) |
| || | | || |
|# Introduction ||<h1>Introduction</h1> | |# Introduction ||<h1>Introduction</h1> |
skipping to change at page 4, line 40 skipping to change at page 4, line 40
| ||<p>The paradigmatic use case for | | ||<p>The paradigmatic use case for |
|[MDSYNTAX]: http://daringfireball./| <code>text/markdown</code> is the| |[MDSYNTAX]: http://daringfireball./| <code>text/markdown</code> is the|
/net/projects/markdown/syntax#html || Markdown editor: an application | /net/projects/markdown/syntax#html || Markdown editor: an application |
|"Markdown: Syntax: HTML" || that presents Markdown content | |"Markdown: Syntax: HTML" || that presents Markdown content |
| || ...</p> | | || ...</p> |
+----------------------------------++----------------------------------+ +----------------------------------++----------------------------------+
LEGEND: "/" embedded in a vertical line represents a line-continuation LEGEND: "/" embedded in a vertical line represents a line-continuation
marker, since a line break is not supposed to occur in that content. marker, since a line break is not supposed to occur in that content.
Figure 1: Markdown Split-Screen/Live Preview Editor Figure 1: Markdown Split-Screen / Live Preview Editor
To get the best results, implementations ought to produce and consume To get the best results, implementations ought to produce and consume
mutually intelligible and identifiable bits of Markdown. That way, users mutually intelligible and identifiable bits of Markdown. That way,
on diverse platforms can collaborate with their tools of choice. Those users on diverse platforms can collaborate with their tools of
tools can be desktop-based (MarkdownPad, MultiMarkdown Composer), choice. Those tools can be desktop-based (MarkdownPad, MultiMarkdown
browser-based (Dillinger, Markable), integrated widgets (Discourse, Composer); browser-based (Dillinger, Markable); integrated widgets
GitHub), general-purpose editors (emacs, vi), or plain old "Notepad". (Discourse, GitHub); general-purpose editors (emacs, vi); or plain
Additionally, implementations ought to have common ways to identify old "Notepad". Additionally, implementations ought to have common
particular areas of Markdown content when the Markdown becomes ways to identify particular areas of Markdown content when the
appreciably large (e.g., book chapters and Internet-Drafts--not just Markdown becomes appreciably large (e.g., book chapters and Internet-
blog posts). So that users have the option to use Markdown in MIME- Drafts -- not just blog posts). So that users have the option to use
capable systems to convey their works in progress, not just their Markdown in MIME-capable systems to convey their works in progress,
finished products (for which full-blown markups ranging from text/html not just their finished products (for which full-blown markups
to application/pdf are appropriate), implementations ought to label such ranging from text/html to application/pdf are appropriate),
Markdown content with a common media type: text/markdown. This implementations ought to label such Markdown content with a common
registration facilitates interoperability between these Markdown editors media type: text/markdown. This registration facilitates
by conveying the syntax of the particular Markdown variant and the interoperability between these Markdown editors by conveying the
desired output format. syntax of the particular Markdown variant and the desired output
format.
1.3. Definitions 1.3. Definitions
The key words "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT", The key words "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT",
"SHOULD", "SHOULD NOT", "RECOMMENDED", "MAY", and "OPTIONAL" in this "SHOULD", "SHOULD NOT", "RECOMMENDED", "MAY", and "OPTIONAL" in this
document are to be interpreted as described in [RFC2119]. document are to be interpreted as described in [RFC2119].
Since Markdown signifies a family of related formats with varying Since Markdown signifies a family of related formats with varying
degrees of formal documentation and implementation, this degrees of formal documentation and implementation, this
specification uses the term "variant" to identify such formats. specification uses the term "variant" to identify such formats.
2. Markdown Media Type Registration Application 2. Markdown Media Type Registration Application
This section provides the media type registration application for the This section provides the media type registration application for the
text/markdown media type (see [RFC6838], Section 5.6). text/markdown media type (see Section 5.6 of [RFC6838]).
Type name: text Type name: text
Subtype name: markdown Subtype name: markdown
Required parameters: Required parameters:
charset: Per Section 4.2.1 of [RFC6838], charset is REQUIRED. There charset: Per Section 4.2.1 of [RFC6838], charset is REQUIRED.
is no default value because neither [MDSYNTAX] nor many popular There is no default value because neither [MDSYNTAX] nor many
implementations at the time of this registration do either. popular implementations at the time of this registration do
[MDSYNTAX] clearly describes Markdown as a "writing format"; its either. [MDSYNTAX] clearly describes Markdown as a "writing
syntax rules operate on characters (specifically, on punctuation) format"; its syntax rules operate on characters (specifically,
rather than code points. Many Markdown processors will get along on punctuation) rather than code points. Many Markdown
just fine by operating on characters in the US-ASCII repertoire processors will get along just fine by operating on characters
(specifically punctuation), blissfully oblivious to other in the US-ASCII repertoire (specifically punctuation),
characters or codes. blissfully oblivious to other characters or codes.
Optional parameters: Optional parameters:
variant: An optional identifier of the specific Markdown variant variant: An optional identifier of the specific Markdown variant
that the author intended. The value serves as a "hint" to the that the author intended. The value serves as a "hint" to the
recipient, meaning that the recipient MAY interpret the Markdown recipient, meaning that the recipient MAY interpret the
as that variant, but is under no obligation to do so. When Markdown as that variant, but is under no obligation to do so.
omitted, there is no hint; the interpretation is entirely up to When omitted, there is no hint; the interpretation is entirely
the receiver and context. This identifier is plain US-ASCII and up to the receiver and context. This identifier is plain US-
case-insensitive. To promote interoperability, identifiers can be ASCII and case-insensitive. To promote interoperability,
registered in the registry defined in Section 6. If a receiver identifiers can be registered in the registry defined in
does not recognize the variant identifier, the receiver MAY Section 6. If a receiver does not recognize the variant
present the identifier to a user to inform him or her of it. 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 Other parameters MAY be included with the media type. The
SHOULD define the semantics of such other parameters. Additionally, variant SHOULD define the semantics of such other parameters.
the variant MAY be registered under another media type; this Additionally, the variant MAY be registered under another media
text/markdown registration does not preclude other registrations. type; this text/markdown registration does not preclude other
registrations.
Encoding considerations: Encoding considerations:
Markdown content is plain text content; any octet sequence is valid Markdown content is plain-text content; any octet sequence is
as long as it conforms to the character codes of the charset valid as long as it conforms to the character codes of the charset
parameter. See [RFC2046]. Markup characters in [MDSYNTAX] are parameter. See [RFC2046]. Markup characters in [MDSYNTAX] are
limited to printable US-ASCII; however, other variants can define limited to printable US-ASCII; however, other variants can define
markup characters outside this range (including control characters markup characters outside this range (including control characters
such as NUL and characters encoded in multiple octets). such as NUL and characters encoded in multiple octets).
Security considerations: Security considerations:
Markdown interpreted as plain text is relatively harmless. A text Markdown interpreted as plain text is relatively harmless. A text
editor need only display the text. The editor SHOULD take care to editor need only display the text. The editor SHOULD take care to
handle control characters appropriately, and to limit the effect of handle control characters appropriately and to limit the effect of
the Markdown to the text editing area itself; malicious Unicode- the Markdown to the text-editing area itself; malicious Unicode-
based Markdown could, for example, surreptitiously change the based Markdown could, for example, surreptitiously change the
directionality of the text. An editor for normal text would already directionality of the text. An editor for normal text would
take these control characters into consideration, however. already take these control characters into consideration, however.
Markdown interpreted as a precursor to other formats, such as HTML, Markdown interpreted as a precursor to other formats, such as
carries all of the security considerations as the target formats. HTML, carries all of the security considerations as the target
For example, HTML can contain instructions to execute scripts, formats. For example, HTML can contain instructions to execute
redirect the user to other webpages, download remote content, and scripts, redirect the user to other web pages, download remote
upload personally identifiable information. Markdown also can content, and upload personally identifiable information. Markdown
contain islands of formal markup, such as HTML. These islands of also can contain islands of formal markup, such as HTML. These
formal markup may be passed as-is, transformed, or ignored (perhaps islands of formal markup may be passed as they are, transformed,
because the islands are conditional or incompatible) when the or ignored (perhaps because the islands are conditional or
Markdown is processed. Since Markdown may have different incompatible) when the Markdown is processed. Since Markdown may
interpretations depending on the tool and the environment, a better have different interpretations depending on the tool and the
approach is to analyze (and sanitize or block) the output markup, environment, a better approach is to analyze (and sanitize or
rather than attempting to analyze the Markdown. block) the output markup, rather than attempting to analyze the
Markdown.
Interoperability considerations: Interoperability considerations:
Markdown variations (some might say "innovations") are designed to Markdown variations (some might say "innovations") are designed to
be broadly compatible with humans ("humane"), but not necessarily be broadly compatible with humans ("humane"), but not necessarily
with each other. Therefore, syntax in one Markdown derivative may with each other. Therefore, syntax in one Markdown derivative may
be ignored or treated differently in another derivative. The be ignored or treated differently in another derivative. The
overall effect is a general degradation of the output that overall effect is a general degradation of the output that
increases with the quantity of variant-specific Markdown used in increases with the quantity of variant-specific Markdown used in
the text. When it is desirable to reflect the author's intent in the text. When it is desirable to reflect the author's intent in
the output, stick with the variant identified in the variant the output, stick with the variant identified in the variant
parameter, i.e., receivers SHOULD only accept Markdown variants parameter, i.e., receivers SHOULD only accept Markdown variants
that they explicitly know about, and senders SHOULD avoid use of that they explicitly know about, and senders SHOULD avoid use of
variants that intended recipients are not known to understand. variants that intended recipients are not known to understand.
Published specification: This specification; [MDSYNTAX]. Published specification: This specification; [MDSYNTAX].
Applications that use this media type: Applications that use this media type:
Markdown conversion tools, Markdown WYSIWYG editors, and plain text Markdown conversion tools, Markdown WYSIWYG (What You See is What
editors and viewers; markup processor targets indirectly use You Get) editors, and plain-text editors and viewers; markup
Markdown (e.g., web browsers for Markdown converted to HTML). processor targets indirectly use Markdown (e.g., web browsers for
Markdown converted to HTML).
Fragment identifier considerations: Fragment identifier considerations:
See Section 3. See Section 3.
Additional information: Additional information:
Magic number(s): None Magic number(s): None
File extension(s): .md, .markdown File extension(s): .md, .markdown
Macintosh file type code(s): Macintosh file type code(s):
TEXT. A uniform type identifier (UTI) of TEXT. A uniform type identifier (UTI) of
"net.daringfireball.markdown", which conforms to "public.plain- "net.daringfireball.markdown", which conforms to
text", is RECOMMENDED [MDUTI]. See [MDMTGUID] for other "public.plain-text", is RECOMMENDED [MDUTI]. See [RFC7764] for
considerations. other considerations.
Person & email address to contact for further information: Person & email address to contact for further information:
Sean Leonard <dev+ietf@seantek.com> Sean Leonard <dev+ietf@seantek.com>
Restrictions on usage: None. Restrictions on usage: None.
Author/Change controller: Sean Leonard <dev+ietf@seantek.com> Author/Change controller: Sean Leonard <dev+ietf@seantek.com>
Intended usage: COMMON Intended usage: COMMON
Provisional registration? No Provisional registration? No
Implementations SHOULD record the value of the variant parameter (and Implementations SHOULD record the value of the variant parameter (and
other parameters if defined by the variant) along with the Markdown other parameters if defined by the variant) along with the Markdown
content when the content leaves the domain of Internet media type- content when the content leaves the domain of formats that are
capable formats. Strategies for doing so are discussed in [MDMTGUID]. Internet media type capable. Strategies for doing so are discussed
in [RFC7764].
The Content-Disposition header (particularly the preview-type The Content-Disposition header (particularly the preview-type
parameter) can be used with Markdown content. See Section 4. parameter) can be used with Markdown content. See Section 4.
3. Fragment Identifiers 3. Fragment Identifiers
[MARKDOWN] does not define any fragment identifiers, but some [MARKDOWN] does not define any fragment identifiers, but some
variants do, and many types of Markdown processor output (e.g., HTML variants do, and many types of Markdown processor output (e.g., HTML
or PDF) will have well-defined fragment identifiers. Which fragment or PDF) will have well-defined fragment identifiers. Which fragment
identifiers are available for a given document are variant-defined. identifiers are available for a given document are variant-defined.
When encoded in a URI, characters that are outside of the fragment When encoded in a URI, characters that are outside of the fragment
production of [RFC3986] are percent-encoded. The default encoding production of [RFC3986] are percent-encoded. The default encoding
(character set) of percent-encoded octets in URIs is the same as the (character set) of percent-encoded octets in URIs is the same as the
Markdown content, which is identified by the charset parameter or by Markdown content, which is identified by the charset parameter or by
other contextual means. Fragment identifiers SHOULD be considered other contextual means. Fragment identifiers SHOULD be considered
case-sensitive, which maintains consistency with HTML. Variants MAY case-sensitive, which maintains consistency with HTML. Variants MAY
override the guidance in this paragraph. override the guidance in this paragraph.
At least the first equals sign "=" SHOULD be percent-encoded to At least the first equals sign "=" SHOULD be percent-encoded to
prevent ambiguity as described in the following section. prevent ambiguity as described in the following section.
3.1. Parameters 3.1. Parameters
Similar to application/pdf [RFC3778] and text/plain [RFC5147], this Similar to application/pdf [RFC3778] and text/plain [RFC5147], this
registration permits a parameter syntax for fragment identifiers. The registration permits a parameter syntax for fragment identifiers.
syntax is a parameter name, the equals sign "=" (which MUST NOT be The syntax is a parameter name, the equals sign "=" (which MUST NOT
percent-encoded), and a parameter value. To the extent that multiple be percent-encoded), and a parameter value. To the extent that
parameters can appear in a fragment production, the parameters SHALL multiple parameters can appear in a fragment production, the
be separated by the ampersand "&" (which MUST NOT be percent- parameters SHALL be separated by the ampersand "&" (which MUST NOT be
encoded). percent-encoded).
The only parameter defined in this registration is "line", which has The only parameter defined in this registration is "line", which has
the same meaning as [RFC5147] (i.e., counting is zero-based). For the same meaning as in [RFC5147], i.e., counting is zero-based. For
example: "#line=10" identifies the eleventh line of Markdown input. example: "#line=10" identifies the eleventh line of Markdown input.
Implementers should take heed that different environments and Implementers should take heed that different environments and
character sets may have a wide range of code sequences to divide character sets may have a wide range of code sequences to divide
lines. lines.
Markdown variants are free to define additional parameters. Markdown variants are free to define additional parameters.
4. Content Disposition and preview-type 4. Content Disposition and preview-type
The Content-Disposition header [RFC2183] conveys presentational The Content-Disposition header [RFC2183] conveys presentational
information about a MIME entity, using a type and set of parameters. information about a MIME entity, using a type and set of parameters.
The parameter "preview-type" is defined here for Markdown content. The parameter preview-type is defined here for Markdown content.
When present, "preview-type" indicates the Internet media type (and When present, preview-type indicates the Internet media type (and
parameters) of the preview output desired from the processor by the parameters) of the preview output desired from the processor by the
author. With reference to the "paradigmatic use case" (i.e., author. With reference to the "paradigmatic use case" (i.e.,
collaborative Markdown editing) in Section 1.3, the preview-type collaborative Markdown editing) in Section 1.3, the preview-type
parameter primarily affects the "right-hand" side of a Markdown parameter primarily affects the "right-hand" side of a Markdown
editor. There is no default value: when absent, a Markdown user agent editor. There is no default value: when absent, a Markdown user
can render or display whatever it wants. agent can render or display whatever it wants.
The value of this parameter is an Internet media type with optional The value of this parameter is an Internet media type with optional
parameters. The syntax (including case sensitivity considerations) is parameters. The syntax (including case-sensitivity considerations)
the same as specified in [RFC2045] for the Content-Type header (with is the same as specified in [RFC2045] for the Content-Type header
updates over time, e.g., [RFC2231] and [RFC6532]). (with updates over time, e.g., [RFC2231] and [RFC6532]).
Implementations SHOULD anticipate and support HTML (text/html) and Implementations SHOULD anticipate and support HTML (text/html) and
XHTML (application/xhtml+xml) output, to the extent that a syntax XHTML (application/xhtml+xml) output, to the extent that a syntax
targets those markup languages. These types ought to be suitable for targets those markup languages. These types ought to be suitable for
the majority of current purposes. However, Markdown is increasingly the majority of current purposes. However, Markdown is increasingly
becoming integral to workflows where HTML is not the target output; becoming integral to workflows where HTML is not the target output;
examples range from TeX, to PDF, to OPML, and even to entire e-books examples range from TeX, to PDF, to Outline Processor Markup Language
(e.g., [PANDOC]). (OPML), and even to entire e-books (e.g., [PANDOC]).
The reflexive media type "text/markdown" in this parameter value The reflexive media type text/markdown in this parameter value means
means that the author does not want to invoke Markdown processing at that the author does not want to invoke Markdown processing at all:
all: the receiver SHOULD present the Markdown source as-is. the receiver SHOULD present the Markdown source as is.
The "preview-type" parameter can be used for other types of content, The preview-type parameter can be used for other types of content,
but the precise semantics are not defined here. but the precise semantics are not defined here.
5. Example 5. Example
The following is an example of Markdown as an e-mail attachment: The following is an example of Markdown as an email attachment:
MIME-Version: 1.0 MIME-Version: 1.0
Content-Type: text/markdown; charset=UTF-8; variant=Original Content-Type: text/markdown; charset=UTF-8; variant=Original
Content-Disposition: attachment; filename=readme.md; Content-Disposition: attachment; filename=readme.md;
preview-type="application/xhtml+xml" preview-type="application/xhtml+xml"
Sample HTML 4 Markdown Sample HTML 4 Markdown
============= =============
This is some sample Markdown. [Hooray!][foo] This is some sample Markdown. [Hooray!][foo]
skipping to change at page 10, line 18 skipping to change at page 10, line 27
More Information More Information
----------- -----------
[.markdown, .md](http://daringfireball.net/projects/markdown/) [.markdown, .md](http://daringfireball.net/projects/markdown/)
has more information. has more information.
[fOo]: http://example.com/loc 'Will Not Work with Markdown.pl-1.0.1' [fOo]: http://example.com/loc 'Will Not Work with Markdown.pl-1.0.1'
6. IANA Considerations 6. IANA Considerations
IANA is asked to register the media type text/markdown using the IANA has registered the media type text/markdown using the
application provided in Section 2 of this document. application provided in Section 2 of this document.
IANA is asked to register "preview-type" in the Content Disposition IANA has registered preview-type in the "Content Disposition
Parameters subregistry of the Content Disposition Values and Parameters" subregistry of the "Content Disposition Values and
Parameters registry, with the following description: "Internet media Parameters" registry, with the following description: "Internet media
type (and parameters) of the preview output desired from a processor type (and parameters) of the preview output desired from a processor
by the author of the MIME content". by the author of the MIME content".
6.1. Markdown Variants 6.1. Markdown Variants
IANA is also asked to establish a registry called "Markdown IANA has established a registry called "Markdown Variants". While
Variants". While the registry is being created in the context of the the registry has been created in the context of the text/markdown
text/markdown media type, the registry is intended for broad media type, the registry is intended for broad community use, so
community use, so protocols and systems that do not rely on Internet protocols and systems that do not rely on Internet media types can
media types can still tag Markdown content with a common variant still tag Markdown content with a common variant identifier. Each
identifier. Each entry in this registry shall consist of basic entry in this registry shall consist of basic information about the
information about the variant: variant:
Identifier: unique identifier for the variant Identifier: unique identifier for the variant
Name: the commonly known name of the variant Name: the commonly known name of the variant
Description: a prose description of the variant, Description: a prose description of the variant, including
including how it differs from other how it differs from other variants such as
variants such as Original Original
Additional Parameters*: additional Content-Type parameters Additional Parameters*: additional Content-Type parameters
Fragment Identifiers*: additional fragment identifier Fragment Identifiers*: additional fragment identifier syntaxes and
syntaxes and semantics semantics
References: URIs or other references to documentation References: URIs or other references to documentation
Contact Information: whom to contact (email, URI, phone, Contact Information: whom to contact (email, URI, phone, address,
address, etc.) etc.)
Expiration Date^: when this provisional Expiration Date^: when this provisional registration expires
registration expires
* (optional) * (optional)
^ (if provisional) ^ (if provisional)
While the variant parameter is "plain US-ASCII" (see registration While the variant parameter is "plain US-ASCII" (see registration
template), the Identifier field (and by implication, all registered template), the Identifier field (and by implication, all registered
identifiers) SHALL conform to the ABNF [RFC5234]: identifiers) SHALL conform to the ABNF [RFC5234]:
ALPHA [*VCHAR (ALPHA / DIGIT)] ALPHA [*VCHAR (ALPHA / DIGIT)]
For style and compatibility reasons, the Identifier field SHOULD For style and compatibility reasons, the Identifier field SHOULD
conform to the ABNF: conform to the ABNF:
ALPHA *( ["-" / "." / "_" / "~"] 1*(ALPHA / DIGIT) ) ALPHA *( ["-" / "." / "_" / "~"] 1*(ALPHA / DIGIT) )
I.e., the identifier MUST start with a letter and MAY contain That is, the identifier MUST start with a letter and MAY contain
punctuation in the middle, but not at the end: the last character punctuation in the middle, but not at the end: the last character
MUST be alphanumeric. The second production uses the same characters MUST be alphanumeric. The second production uses the same characters
as the "unreserved" rule of [RFC3986], and is designed to be as the "unreserved" rule of [RFC3986] and is designed to be
compatible with characters in other identification systems, e.g., compatible with characters in other identification systems, e.g.,
filenames. Since the identifier MAY be displayed to a user-- filenames. Since the identifier MAY be displayed to a user --
particularly in cases where the receiver does not recognize the particularly in cases where the receiver does not recognize the
identifier--the identifier SHOULD be rationally related to the identifier -- the identifier SHOULD be rationally related to the
vernacular name of the variant. vernacular name of the variant.
The Name, Description, Additional Parameters, Fragment Identifiers, The Name, Description, Additional Parameters, Fragment Identifiers,
References, and Contact Information fields SHALL be in a Unicode References, and Contact Information fields SHALL be in a Unicode
character set (e.g., UTF-8). character set (e.g., UTF-8).
The registry includes the registration in Section 6.1.4 (Original The registry includes the registration in Section 6.1.4 (Original
Markdown). [MDMTGUID] includes additional registrations. Markdown). [RFC7764] includes additional registrations.
6.1.1. Reserved Identifiers 6.1.1. Reserved Identifiers
The registry has the following identifiers RESERVED, as they have The registry has the following identifiers RESERVED, as they have
engendered some controversy in the Markdown community. No one is engendered some controversy in the Markdown community. No one is
allowed to register them (or any case variations of them). These allowed to register them (or any case variations of them). These
identifiers are not and cannot be registered: identifiers are not and cannot be registered:
Standard Standard
Common Common
Markdown Markdown
The registry includes the following text in the note field: The registry includes the following text in the note field:
The variant names Standard, Common, and Markdown are reserved and The variant names Standard, Common, and Markdown are reserved and
cannot be registered. cannot be registered.
6.1.2. Standard of Review 6.1.2. Standard of Review
Registrations are made on a First-Come, First-Served [RFC5226] basis Registrations are made on a First Come, First Served [RFC5226] basis
by anyone with a need to interoperate. While documentation is by anyone with a need to interoperate. While documentation is
required, any level of documentation is sufficient; thus, neither required, any level of documentation is sufficient; thus, neither
Specification Required nor Expert Review are warranted. The checks Specification Required nor Expert Review are warranted. The checks
prescribed by this section can be performed automatically. prescribed by this section can be performed automatically.
All references (including contact information) MUST be verified as All references (including contact information) MUST be verified as
functional at the time of the registration. functional at the time of the registration.
As a special "escape valve", registrations can be updated with IETF As a special "escape valve", registrations can be updated with IETF
Review [RFC5226]. All fields may be updated except the variant Review [RFC5226]. All fields may be updated except the variant
identifier, which is permanent: not even case may be changed. identifier, which is permanent: not even case may be changed.
6.1.3. Provisional Registration 6.1.3. Provisional Registration
Any registrant may make a provisional registration to reserve a Any registrant may make a provisional registration to reserve a
variant identifier. Only the variant identifier and contact variant identifier. Only the variant identifier and contact
information fields are required; the rest are optional. Provisional information fields are required; the rest are optional. Provisional
registrations expire after three months, after which time the variant registrations expire after three months, after which time the variant
identifier may be reused. To make a registration permanent, a identifier may be reused. To make a registration permanent, a
registrant simply needs to complete a permanent registration with the registrant simply needs to complete a permanent registration with the
same identifier as the provisional registration. same identifier as the provisional registration.
6.1.4. Original Markdown 6.1.4. Original Markdown
The registry includes this initial variant. A conforming The registry includes this initial variant. A conforming
implementation that processes the variant parameter MUST recognize implementation that processes the variant parameter MUST recognize
this variant (although the processing behavior is not defined here). this variant (although the processing behavior is not defined here).
Identifier: Original Identifier: Original
Name: Markdown Name: Markdown
Description: Description:
Gruber's original Markdown syntax. Gruber's original Markdown syntax.
References: References:
[MARKDOWN] [MARKDOWN]
[MDSYNTAX] [MDSYNTAX]
Contact Information: Contact Information:
(individual) John Gruber <http://daringfireball.net/> (individual) John Gruber <http://daringfireball.net/>
<comments@daringfireball.net> <comments@daringfireball.net>
7. Security Considerations 7. Security Considerations
See the Security considerations entry in Section 2. See the Security considerations entry in Section 2.
8. References 8. References
8.1. Normative References
8.1. Normative References
[MARKDOWN] Gruber, J., "Daring Fireball: Markdown", December 2004, [MARKDOWN] Gruber, J., "Daring Fireball: Markdown", December 2004,
<http://daringfireball.net/projects/markdown/>. <http://daringfireball.net/projects/markdown/>.
[MDSYNTAX] Gruber, J., "Daring Fireball: Markdown Syntax [MDSYNTAX] Gruber, J., "Daring Fireball: Markdown Syntax
Documentation", December 2004, Documentation", December 2004,
<http://daringfireball.net/projects/markdown/syntax>. <http://daringfireball.net/projects/markdown/syntax>.
[MDUTI] Gruber, J., "Daring Fireball: Uniform Type Identifier for [MDUTI] Gruber, J., "Daring Fireball: Uniform Type Identifier for
Markdown", August 2011, Markdown", August 2011,
<http://daringfireball.net/linked/2011/08/05/markdown- <http://daringfireball.net/linked/2011/08/05/
uti>. markdown-uti>.
[RFC2045] Freed, N. and N. Borenstein, "Multipurpose Internet Mail [RFC2045] Freed, N. and N. Borenstein, "Multipurpose Internet Mail
Extensions (MIME) Part One: Format of Internet Message Extensions (MIME) Part One: Format of Internet Message
Bodies", RFC 2045, November 1996. Bodies", RFC 2045, DOI 10.17487/RFC2045, November 1996,
<http://www.rfc-editor.org/info/rfc2045>.
[RFC2119] Bradner, S., "Key words for use in RFCs to Indicate [RFC2119] Bradner, S., "Key words for use in RFCs to Indicate
Requirement Levels", BCP 14, RFC 2119, March 1997. Requirement Levels", BCP 14, RFC 2119,
DOI 10.17487/RFC2119, March 1997,
<http://www.rfc-editor.org/info/rfc2119>.
[RFC2183] Troost, R., Dorner, S., and K. Moore, Ed., "Communicating [RFC2183] Troost, R., Dorner, S., and K. Moore, Ed., "Communicating
Presentation Information in Internet Messages: The Presentation Information in Internet Messages: The
Content-Disposition Header Field", RFC 2183, August 1997. Content-Disposition Header Field", RFC 2183,
DOI 10.17487/RFC2183, August 1997,
<http://www.rfc-editor.org/info/rfc2183>.
[RFC2231] Freed, N. and K. Moore, "MIME Parameter Value and Encoded [RFC2231] Freed, N. and K. Moore, "MIME Parameter Value and Encoded
Word Extensions: Character Sets, Languages, and Word Extensions: Character Sets, Languages, and
Continuations", RFC 2231, November 1997. Continuations", RFC 2231, DOI 10.17487/RFC2231, November
1997, <http://www.rfc-editor.org/info/rfc2231>.
[RFC3778] Taft, E., Pravetz, J., Zilles, S., and L. Masinter, "The [RFC3778] Taft, E., Pravetz, J., Zilles, S., and L. Masinter, "The
application/pdf Media Type", RFC 3778, May 2004. application/pdf Media Type", RFC 3778,
DOI 10.17487/RFC3778, May 2004,
<http://www.rfc-editor.org/info/rfc3778>.
[RFC3986] Berners-Lee, T., Fielding, R., and L. Masinter, "Uniform [RFC3986] Berners-Lee, T., Fielding, R., and L. Masinter, "Uniform
Resource Identifier (URI): Generic Syntax", STD 66, RFC Resource Identifier (URI): Generic Syntax", STD 66,
3986, January 2005. RFC 3986, DOI 10.17487/RFC3986, January 2005,
<http://www.rfc-editor.org/info/rfc3986>.
[RFC5147] Wilde, E. and M. Duerst, "URI Fragment Identifiers for the [RFC5147] Wilde, E. and M. Duerst, "URI Fragment Identifiers for the
text/plain Media Type", RFC 5147, April 2008. text/plain Media Type", RFC 5147, DOI 10.17487/RFC5147,
April 2008, <http://www.rfc-editor.org/info/rfc5147>.
[RFC5226] Narten, T., and H. Alvestrand, "Guidelines for Writing an [RFC5226] Narten, T. and H. Alvestrand, "Guidelines for Writing an
IANA Considerations Section in RFCs", RFC 5226, May 2008. IANA Considerations Section in RFCs", BCP 26, RFC 5226,
DOI 10.17487/RFC5226, May 2008,
<http://www.rfc-editor.org/info/rfc5226>.
[RFC5234] Crocker, D., Ed., and P. Overell, "Augmented BNF for [RFC5234] Crocker, D., Ed., and P. Overell, "Augmented BNF for
Syntax Specifications: ABNF", STD 68, RFC 5234, January Syntax Specifications: ABNF", STD 68, RFC 5234,
2008. DOI 10.17487/RFC5234, January 2008,
<http://www.rfc-editor.org/info/rfc5234>.
[RFC6532] Yang, A., Steele, S., and N. Freed, "Internationalized [RFC6532] Yang, A., Steele, S., and N. Freed, "Internationalized
Email Headers", RFC 6532, February 2012. Email Headers", RFC 6532, DOI 10.17487/RFC6532, February
2012, <http://www.rfc-editor.org/info/rfc6532>.
[RFC6838] Freed, N., Klensin, J., and T. Hansen, "Media Type [RFC6838] Freed, N., Klensin, J., and T. Hansen, "Media Type
Specifications and Registration Procedures", BCP 13, RFC Specifications and Registration Procedures", BCP 13,
6838, January 2013. RFC 6838, DOI 10.17487/RFC6838, January 2013,
<http://www.rfc-editor.org/info/rfc6838>.
8.2. Informative References
[RFC2046] Freed, N. and N. Borenstein, "Multipurpose Internet Mail
Extensions (MIME) Part Two: Media Types", RFC 2046,
November 1996.
[UNICODE] The Unicode Consortium, "The Unicode Standard, Version
8.0.0", The Unicode Consortium, August 2015.
[ISO646] International Organization for Standardization, 8.2. Informative References
"Information technology - ISO 7-bit coded character set
for information interchange", ISO Standard 646, 1991.
[HUMANE] Atwood, J., "Is HTML a Humane Markup Language?", May 2008, [HUMANE] Atwood, J., "Is HTML a Humane Markup Language?", May 2008,
<http://blog.codinghorror.com/is-html-a-humane-markup- <http://blog.codinghorror.com/
language/>. is-html-a-humane-markup-language/>.
[INETMEME] Solon, O., "Richard Dawkins on the internet's hijacking of [INETMEME] Solon, O., "Richard Dawkins on the internet's hijacking of
the word 'meme'", June 2013, the word 'meme'", June 2013,
<http://www.wired.co.uk/news/archive/2013-06/20/richard- <http://www.wired.co.uk/news/archive/2013-06/20/
dawkins-memes>, <http://www.webcitation.org/6HzDGE9Go>. richard-dawkins-memes>,
<http://www.webcitation.org/6HzDGE9Go>.
[MDMTGUID] Leonard, S., "Guidance on Markdown: Design Philosophies, [ISO646] International Organization for Standardization,
Stability Strategies, and Select Registrations", draft- "Information technology - ISO 7-bit coded character set
ietf-appsawg-text-markdown-use-cases-07 (work in for information interchange", ISO Standard 646, 1991.
progress), September 2015.
[PANDOC] MacFarlane, J., "Pandoc", 2014, [PANDOC] MacFarlane, J., "Pandoc", 2014,
<http://johnmacfarlane.net/pandoc/>. <http://johnmacfarlane.net/pandoc/>.
[RFC2046] Freed, N. and N. Borenstein, "Multipurpose Internet Mail
Extensions (MIME) Part Two: Media Types", RFC 2046,
DOI 10.17487/RFC2046, November 1996,
<http://www.rfc-editor.org/info/rfc2046>.
[RFC4263] Lilly, B., "Media Subtype Registration for Media Type [RFC4263] Lilly, B., "Media Subtype Registration for Media Type
text/troff", RFC 4263, January 2006. text/troff", RFC 4263, DOI 10.17487/RFC4263, January 2006,
<http://www.rfc-editor.org/info/rfc4263>.
[RFC7764] Leonard, S., "Guidance on Markdown: Design Philosophies,
Stability Strategies, and Select Registrations", RFC 7764,
DOI 10.17487/RFC7764, March 2016,
<http://www.rfc-editor.org/info/rfc7764>.
[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/>.
Author's Address Author's Address
Sean Leonard Sean Leonard
Penango, Inc. Penango, Inc.
5900 Wilshire Boulevard 5900 Wilshire Boulevard
21st Floor 21st Floor
Los Angeles, CA 90036 Los Angeles, CA 90036
USA United States
EMail: dev+ietf@seantek.com Email: dev+ietf@seantek.com
URI: http://www.penango.com/ URI: http://www.penango.com/
 End of changes. 120 change blocks. 
292 lines changed or deleted 317 lines changed or added

This html diff was produced by rfcdiff 1.44. The latest version is available from http://tools.ietf.org/tools/rfcdiff/