Markdown is a lightweight markup language that uses plain text formatting syntax (such as asterisks for emphasis, hashes for headings, and brackets for links) to create formatted documents that are easy to read in raw form and can be converted to HTML and other formats.
Markdown
Markdown is a lightweight markup language that turns plain-text conventions — # for headings, * for emphasis, [text](url) for links — into formatted documents that stay readable in their raw form and convert cleanly to HTML. John Gruber and Aaron Swartz created it in 2004 to let people write for the web without hand-authoring tags, and the later CommonMark specification pinned down its once-ambiguous rules. It has since become the default writing surface for developers.
- Human-readable source - The raw file is legible on its own, so it diffs, reviews, and versions in Git as easily as code.
- Deterministic conversion - CommonMark gives it a precise grammar, so the same source renders the same way across parsers and tooling.
- Everywhere in developer workflows - README files, issue trackers, static-site generators, and chat tools all speak Markdown natively.
- Extensible in practice - Flavors like GitHub Flavored Markdown add tables, task lists, and fenced code without breaking the base syntax.
In API operations Markdown is the connective tissue of documentation: it is where OpenAPI descriptions get narrated, where changelogs and guides live, and where docs generators like Slate render reference material. Because it is plain text it flows through the same review and CI pipelines as the API definitions themselves, and in the agentic turn it is increasingly the format models both read and emit — making well-structured Markdown a quiet prerequisite for machine-readable, agent-consumable API content.
Referenced on the API Evangelist blog
Where this standard shows up across sixteen years of my writing at apievangelist.com — how it fits into API design, governance, and the agentic turn.
HTML to Markdown API
2013-09-22
