text/markdown standardizes how Markdown travels across systems, APIs, and clients.
Key topics
- Media type registration and semantics.
- Variant handling across Markdown families.
- Interop expectations between producer and consumer.
Why a media type matters
Markdown files are often passed around as .md files, pasted into editors, uploaded to storage services, sent through APIs, attached to messages, or rendered in static site generators. In each case, software needs to know what kind of content it is handling. File extensions help humans, but protocols need media types. RFC 7763 registers text/markdown so systems can identify Markdown content in a standard way.
The media type does not magically solve all Markdown interoperability problems. It solves a narrower but important problem: it gives Markdown a recognized identity in MIME-based contexts. When an HTTP response says Content-Type: text/markdown, the client can understand that the payload is Markdown source, not HTML, plain text without markup, or arbitrary binary data. This is useful for APIs, document storage, import/export workflows, and content negotiation.
The subtle point is that text/markdown identifies the general class of content, not every detail of the dialect. Markdown is a family of related formats. A client that receives Markdown still needs to know whether the source is CommonMark, GitHub Flavored Markdown, Pandoc Markdown, or another variant. RFC 7763 therefore includes the idea of a variant parameter. That parameter gives producers a way to communicate more specific expectations.
Markdown, MIME, and interoperability
MIME types are not only about browsers. They are also about durable contracts between systems. If a storage API accepts Markdown uploads, it should be able to validate content type. If an export endpoint returns Markdown, it should label the response accurately. If a search indexer processes documents differently depending on format, text/markdown provides a clean signal.
This matters for Markdown because raw source and rendered output are different artifacts. A Markdown document may render to HTML, but it is not HTML. Sending Markdown as text/html is incorrect because it tells clients to treat source punctuation as browser-ready markup. Sending it as text/plain is safer, but loses the semantic hint that the text has Markdown structure. text/markdown sits between those two choices: it preserves source identity while acknowledging markup semantics.
Because text/* media types usually involve character encoding, charset handling also matters. Markdown source is text, and modern systems should use UTF-8 unless there is a strong reason not to. A mismatch between declared and actual encoding can break punctuation, non-ASCII prose, code examples, and link destinations. In a technical writing product, encoding errors are not cosmetic; they can corrupt source documents.
Variant as a dialect signal
The variant parameter is one of the most important ideas in RFC 7763. It recognizes that Markdown is not a single fully uniform syntax across all tools. A producer can identify content as Markdown and then supply additional information about which flavor is intended.
For example, a document written for GitHub Flavored Markdown may contain tables and task lists. A strict CommonMark renderer will not necessarily render those extensions as intended. If the document is sent only as generic text/markdown, the receiver may not know that GFM behavior is expected. A variant signal can reduce ambiguity, especially in controlled systems.
However, variants only help if both sides understand them. A robust Markdown platform should not depend entirely on external clients guessing correctly. It should document supported variants at the product level. If the app accepts only .md files but renders them using a particular parser, that parser choice is part of the content contract.
Practical API guidance
For upload APIs, accept Markdown as text/markdown where possible, but do not rely exclusively on the client-provided header. Clients can send incorrect content types. Validation should also check file extension, size limits, and product-specific rules. In a Markdown-only storage app, accepting .md files is a user-facing policy, while text/markdown is a protocol-level signal.
For download APIs, return Content-Type: text/markdown; charset=utf-8 when serving source Markdown. If the endpoint returns rendered HTML, use text/html instead. Do not blur these outputs. The user may want the source for editing, backup, or migration. Rendered HTML is a derived view.
For preview systems, keep the source media type conceptually separate from the rendering pipeline. The stored object can be Markdown, while the preview response can be HTML. If you expose both through an API, use different endpoints or clear content negotiation. This prevents accidental misuse by clients.
Security and content handling
Markdown can contain raw HTML in many dialects. Therefore, treating Markdown as harmless plain text can be dangerous if the system renders it into HTML without sanitization. The source media type tells you what the content is, but it does not guarantee safety. A secure renderer must decide what to do with HTML blocks, inline HTML, dangerous links, images, and embedded content.
This is another reason dialect identity matters. Some environments allow raw HTML. Some strip it. GitHub applies sanitization after rendering user content. A production system needs a policy that is clear to users and consistent across previews, exports, and public views.
Media type boundaries in APIs and storage systems
The media type boundary should match the artifact being transferred. A source download should expose Markdown source as text/markdown; a preview endpoint should expose rendered HTML as text/html; a JSON API that wraps Markdown metadata should use application/json and include the Markdown source as a field. Keeping those boundaries clear prevents clients from guessing whether they are receiving source text, rendered markup, or structured metadata.
This boundary also connects to CommonMark standardization. The media type identifies the source family, while the parser contract identifies the syntax rules. A durable Markdown system needs both layers: transport-level identity and language-level behavior.
For public tutorial pages like this series, the user-facing route serves rendered HTML. The source content lives as Markdown inside the project. That separation is healthy: authors write Markdown, the site renders structured HTML, and metadata such as canonical URLs and structured data are attached at the page level.
FAQ
What is text/markdown?
text/markdown is the registered media type for Markdown source documents. It tells clients that the payload is Markdown text rather than rendered HTML or unstructured plain text.
Is .md the same as text/markdown?
No. .md is a file extension. text/markdown is a media type used in protocols and metadata. They often refer to the same kind of content, but they operate in different layers.
Does text/markdown specify CommonMark?
No. It identifies Markdown generally. A variant parameter or external contract is needed to specify the intended dialect.
Should an API return Markdown as text/plain?
It can, but text/markdown; charset=utf-8 is more accurate when the response is Markdown source. Use text/html only for rendered output.
Can Markdown be unsafe?
Yes. Markdown can include raw HTML, links, and images depending on the dialect and renderer. Rendering user-provided Markdown requires sanitization and a clear security policy.
Related tutorials
- Connect media type identity to CommonMark Standardization.
- Understand source parsing in CommonMark Document Model.
- Review raw HTML behavior in Code Spans, Fenced Code Blocks, and Raw HTML.
- Compare variants in Markdown Dialects Compared.
- Apply transport rules in Designing Production Markdown Systems.
Continue with CommonMark Standardization.