Summary

  • RFC 7763, published in March 2016 as an IETF Informational RFC, registered text/markdown. Its registration requires charset; its optional variant parameter identifies the syntax the author intended.
  • The variant is a hint. The receiver may follow it, and may choose another interpretation. RFC 7764 documented several competing Markdown variants rather than one grammar.
  • IANA’s media-type registry now lists text/markdown, while its Markdown Variants registry keeps a separate roster of dialect names. The two registries solve two different identification problems.

A file with two possible pages inside

Picture a short README with rows separated by pipes. In an editor that understands a table extension, the rows become columns. In a stricter Markdown reader, they remain lines of punctuation and words. The file did not change on the trip. The interpreter changed. That small difference matters when a document moves from a code forge to an email attachment, a publishing system or an archive: a writer may have built an argument around a table that another reader never sees.

Markdown grew from John Gruber’s 2004 writing format into a family of related practices. The 2016 companion RFC named several of them: Original, GitHub Flavored Markdown, CommonMark, Pandoc, MultiMarkdown and others. Its description of GitHub Flavored Markdown includes tables, fenced code blocks and automatic URL links among the extensions. Those are observable reading rules, not decorative brand names. A pipe can divide a column in one system and sit in ordinary text in another.

The institutional temptation was to treat the word “Markdown” as if it already settled those choices. It did not. Programs had made their own decisions while writers enjoyed a forgiving plain-text surface. Once the text began crossing application boundaries, the omitted decisions became other people’s bugs. The document might be portable as bytes while its layout, links and implied structure were local to the software that first rendered it.

One name on the envelope, a dialect in the margin

RFC 7763 registered the media type text/markdown in March 2016. That was a practical address for the family: a mail client, server or editor could identify the payload as Markdown rather than generic plain text. The registration also required a charset parameter. Character encoding affects which characters the receiver reads before any Markdown rule gets a turn; the RFC gave this type no default charset.

The RFC supplied an optional variant parameter for the next question. Content-Type: text/markdown; charset=UTF-8; variant=Original identifies both the broad family and an intended reading. A different variant value can name a different grammar. The order matters: a program first has to read the characters, then decide which syntax those characters express. A label that says only text/markdown carries no variant hint. The receiver uses its own context.

Even a present variant is a request rather than a remote control. The RFC calls it a hint. A receiver may interpret the content as the named variant, but the specification leaves that choice with the receiver. It also advises senders to choose variants their recipients understand when preserving authorial intent matters. The writer can place a passport on the file. The border officer still needs to know the language printed inside.

The companion RFC 7764 explains the metadata problem once Markdown leaves a protocol that can carry a Content-Type header. A local .md file may retain its text while losing the parameter that described how to read it. The RFC discusses ways to preserve that context. RFC 7763 says implementations should record variant and other relevant parameters alongside content in such transfers. A filename extension is a thin receipt for a much thicker choice.

The registry kept the plurality visible

IANA records text/markdown under text media types. It separately maintains a Markdown Variants registry, using a First Come First Served procedure. Its current list includes Original, GFM, CommonMark and Pandoc, among other names. The register makes the plurality legible. It does not make every renderer implement every listed variant; the actual software remains the place where a feature either runs or fails.

The distinction is easy to miss because both registers look official. One answers, “What kind of content is this?” The other can answer, “Which Markdown reading did its author intend?” Neither can force a reader to honor an unsupported table, heading rule or link syntax. The practical contract is completed at the receiving endpoint, where a parser and its version finally turn marks into structure.

That arrangement is more honest than pretending a single type label erased ten years of local evolution. It lets a sender name a known dialect without making a global committee the owner of every future Markdown extension. It also exposes an uncomfortable fact for operators: a file that rendered correctly in one product can be corrupted in meaning by a silent change of parser elsewhere. The source remains intact; the page can still be wrong.

The test is the page the reader actually sees

An operator moving a Markdown collection can check three things. First, what exact Content-Type and charset travel with the content? Second, is a variant carried and retained after export? Third, does the destination parser support that variant and produce the tables, links, code blocks and headings the writer used? Those checks follow the chain from record to running behavior. A registry entry alone cannot answer the third question.

There is no deployment count in the four official records used here. Dated application manuals, source releases and captured response headers would show which products actually sent a variant parameter and which parsers honored it. Until then, the historical claim is narrower and sharper: the 2016 RFCs created a way to tell another machine what sort of Markdown arrived, while preserving the receiver’s choice about how to read it.