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

• Status
• IESG evaluation record
• IESG writeups
• Email expansions
• History

• Versions
• 00
• 01
• 02
• 03
• 04
• 05
• 06
• 07

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