Guidance on Markdown: Design Philosophies, Stability Strategies, and Select Registrations
RFC 7764
Document Type RFC - Informational (March 2016; No errata)
Last updated 2016-03-22
Replaces draft-seantek-text-markdown-use-cases
Stream IETF
Formats plain text pdf html bibtex
Reviews
GENART Last Call Review (of -02): Ready with Nits
SECDIR Last Call Review (of -02): Has Issues
OPSDIR Last Call Review (of -02): Ready
Stream WG state Submitted to IESG for Publication (wg milestone: Apr 2015 - Publication requeste... )
Document shepherd Murray Kucherawy
Shepherd write-up Show (last changed 2015-04-13)
IESG IESG state RFC 7764 (Informational)
Consensus Boilerplate Yes
Telechat date
Responsible AD Barry Leiba
Send notices to (None)
IANA IANA review state Version Changed - Review Needed
IANA action state RFC-Ed-Ack
Email authors IPR References Referenced by Nits 
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
Show full document text
ISOC IETF Trust RFC Editor IRTF IESG IETF IAB IASA & IAOC IETF Tools IANA