text/markdown Markdown Common
Identifies Markdown-formatted text — the lightweight markup language standard for READMEs, docs, and content authoring.
What it's for
text/markdown identifies content written in Markdown — the lightweight, plain-text-based markup syntax that's become the de facto standard for documentation, README files, comments on developer platforms (GitHub, GitLab, and countless others), and general lightweight content authoring where full HTML would be overkill. Markdown was deliberately designed to be readable as plain text even before rendering, which is part of why it's succeeded so broadly as a "write once, render nicely, still readable raw" format.
Registered officially in RFC 7763, though in practice this MIME type matters most in API contexts (content negotiation, file storage metadata) — most everyday Markdown consumption happens through platform-specific rendering (GitHub's README display, a CMS's Markdown editor) without the HTTP-level MIME type being a meaningful factor in the actual user experience.
Format & syntax
Content-Type: text/markdown
Content-Type: text/markdown; charset=utf-8
Markdown itself has no single, universally strict specification — the original Markdown syntax by John Gruber established the baseline, but numerous "flavors" (GitHub Flavored Markdown, CommonMark, and others) have added extensions (tables, task lists, strikethrough, and more) with varying levels of compatibility between them, which is genuinely worth knowing since content written for one flavor doesn't always render identically in another.
How it's used in practice
- README files and repository documentation — the standard format for
README.mdand other documentation files across essentially every code hosting platform, rendered automatically into formatted HTML for display. - API responses returning documentation or user-generated content — APIs that store or return Markdown-formatted content (comments, articles, documentation) sometimes explicitly set this Content-Type, particularly in contexts where the consuming client needs to know to render it as Markdown rather than treating it as plain text or HTML.
- Static site generators and content management — many modern content workflows author content in Markdown, which then gets compiled/rendered to HTML at build time or request time, keeping the authoring format simple while producing rich final output.
- Chat and messaging platform formatting — many developer-focused chat tools (Slack, Discord, and others) support a Markdown-like subset for message formatting, though this is typically handled at the application layer rather than through HTTP Content-Type negotiation.
Common mistakes & gotchas
- Assuming all Markdown flavors render identically — GitHub Flavored Markdown's tables, task lists, and certain other extensions aren't part of strict original Markdown or even CommonMark by default, so content written assuming one flavor's features can render incorrectly or lose formatting when processed by a parser targeting a different flavor.
- Confusing "it's Markdown" with "it's safe to render as HTML directly" — Markdown parsers typically convert to HTML, and if the Markdown source includes raw HTML (which most Markdown flavors permit embedding) or the parser doesn't sanitize output, user-submitted Markdown can be a real XSS vector if not handled carefully in any context accepting Markdown from untrusted users.
- Not distinguishing between serving raw Markdown vs. rendered HTML — an API or endpoint needs to be clear about whether it's returning the raw Markdown source (
text/markdown) or the already-rendered HTML output (text/html) — conflating these leads to either double-rendering bugs or content displaying as raw, unformatted Markdown syntax to end users. - CommonMark vs. original Markdown ambiguity affecting edge cases — CommonMark was created specifically to resolve ambiguities and inconsistencies in the original Markdown specification, but not every Markdown processor has fully adopted CommonMark, meaning genuinely edge-case syntax can still render differently across different tools.
Comparison & FAQ
| Type | Purpose | Key difference from text/markdown |
|---|---|---|
| text/html | Already-rendered markup | The final rendered output; text/markdown is the unrendered source syntax that gets converted to this |
| text/plain | No markup semantics at all | Markdown implies content should be parsed and rendered as formatted text, unlike plain text's purely literal display |
Is Markdown a strictly standardized format?
Not entirely — while CommonMark exists specifically to reduce ambiguity, and RFC 7763 registers the MIME type, various "flavors" (GitHub Flavored Markdown being especially common) add extensions with different levels of compatibility, meaning Markdown syntax doesn't always render 100% identically across every tool.
Is it safe to render user-submitted Markdown directly?
Not without care — most Markdown flavors permit embedding raw HTML, and unsanitized rendering of user-submitted Markdown containing malicious HTML/scripts is a real XSS risk; sanitizing the rendered HTML output (or restricting which Markdown features are allowed) is important for any untrusted-content context.
Should my API return raw Markdown or rendered HTML?
Depends on what the consuming client needs — if the client will render Markdown itself, return raw text/markdown; if the client just needs to display the content directly, returning already-rendered text/html avoids requiring the client to implement its own Markdown parser.
Why does my Markdown table not render on some platforms?
Tables are a GitHub Flavored Markdown extension, not part of original Markdown or guaranteed in every CommonMark-compliant parser — if you're seeing inconsistent table rendering across platforms, it's likely a flavor-support gap rather than a syntax error on your part.