Markdown is a lightweight text formatting language that converts plain text into HTML. Created by John Gruber in 2004, it is now the standard for developer documentation, README files, AI prompts, and content management systems worldwide.
John Gruber and Aaron Swartz created Markdown in 2004 with a single goal: to write in an easy-to-read, easy-to-write plain text format that could be converted to structurally valid HTML. The name is a play on HTML markup, inverting the idea of marking up with complex tags into the simpler concept of marking down with readable symbols.
What started as a Perl script for bloggers has become the dominant format for technical writing. GitHub adopted it for READMEs in 2008, Stack Overflow uses it for question and answer formatting, and virtually every modern documentation platform accepts Markdown as a first-class input format.
Markdown uses simple punctuation characters to denote formatting. You write plain text and add a few special characters where you want structure. Here is the core syntax every Markdown writer needs to know.
Hash symbols at the start of a line create headings. One hash is H1, two hashes is H2, and so on up to H6. This mirrors the HTML heading hierarchy.
Wrap text in single asterisks for italic emphasis. Double asterisks create bold. Both can be combined for bold-italic formatting.
Unordered lists use a hyphen, asterisk, or plus sign at the start of each line. Ordered lists use a number followed by a period. Indent by four spaces or a tab to create nested lists.
Links use square brackets for the display text followed by the URL in parentheses. Images follow the same pattern but start with an exclamation mark.
Inline code uses single backticks. Fenced code blocks use three backticks, optionally followed by the language name for syntax highlighting.
Tables use pipe characters to separate columns and dashes to create the header separator row. This pipe-table syntax was not in the original Markdown specification but is universally supported through the CommonMark and GitHub Flavored Markdown extensions.
Markdown beat out alternatives like reStructuredText, AsciiDoc, and plain HTML for developer documentation for several reasons. First, the learning curve is minimal. A developer who has never seen Markdown before can understand and write it correctly within minutes. Second, Markdown files are plain text, so they are version-controlled with standard Git workflows, diffed line by line, and merged like code.
Third, Markdown converts to HTML, PDF, Word, and dozens of other formats. A single source Markdown file can power a documentation website, a PDF export, and an ebook simultaneously. The ecosystem of tools that accept Markdown as input is vast and growing.
Markdown has taken on a new significance in the AI era. Large language models are trained on massive corpora of text, much of which is Markdown. Models like GPT-4, Claude, and Gemini natively understand Markdown syntax and respond in Markdown by default. When you provide context to an AI in Markdown, the model interprets headings, lists, and tables correctly, improving both comprehension and output quality.
For developers building AI applications, Markdown is the preferred format for system prompts, retrieved context, and output. Converting documents to Markdown before inserting them into prompts reduces token count compared to raw HTML or binary formats, which directly reduces API costs. This is the core reason tools like SaveTokens exist: to make any document AI-ready by converting it to clean, efficient Markdown.
The original Markdown specification was intentionally underspecified, leading to inconsistencies between implementations. CommonMark is a strict, unambiguous specification that resolves these inconsistencies. GitHub Flavored Markdown (GFM) extends CommonMark with tables, task list checkboxes, strikethrough, and autolinked URLs. Most modern tools target either CommonMark or GFM.
Other notable flavors include MultiMarkdown, which adds footnotes, bibliography, and metadata support for academic writing; Pandoc Markdown, which adds an enormous range of extensions for scholarly and technical documents; and MDX, which embeds React components inside Markdown for interactive documentation sites.
Markdown is everywhere in modern software development and content creation. GitHub, GitLab, and Bitbucket use it for READMEs, issues, pull requests, and wikis. Static site generators like Hugo, Jekyll, Gatsby, Astro, and Eleventy all use Markdown as their primary content format. Documentation platforms like Notion, Confluence, and Obsidian support Markdown import and export.
For writers, tools like iA Writer, Bear, Typora, and Obsidian use Markdown as their native format. Blogging platforms like Ghost and Substack accept Markdown. Email clients like Markdown Here convert Markdown to rich email formatting. The format has achieved true ubiquity across the writing and developer tooling landscape.