Markdown (Markdown)
The plain-text writing format that turns simple punctuation into clean HTML without touching a code editor.
| Full name | Markdown |
| Extension | .md |
| MIME type | text/markdown |
| Developer | John Gruber, with input from Aaron Swartz |
| Released | 2004 (announced March 15, 2004; version 1.0 August 28, 2004) |
| Type | Lightweight markup language / document format |
| Common variants | CommonMark, GitHub Flavored Markdown (GFM), MultiMarkdown |
What is a Markdown file?
Markdown is a lightweight markup language designed to be readable as plain text and convertible to HTML. John Gruber created it in 2004 so writers could format text using ordinary keyboard characters instead of HTML tags. Today it is the default writing format for GitHub README files, documentation sites, note-taking apps, and countless static-site generators.
A Markdown file is a plain-text document with simple formatting conventions: asterisks for bold, hash symbols for headings, hyphens for lists. Any text editor can open and display it without special software. When processed by a Markdown parser, those conventions are converted into HTML or other output formats. The original design goal was that the raw file should look like a naturally formatted email, not like a document full of angle brackets.
History
John Gruber announced Markdown on his blog Daring Fireball on March 15, 2004, and released version 1.0 on August 28, 2004, alongside a Perl script called Markdown.pl that handled the text-to-HTML conversion. Aaron Swartz contributed ideas and served as a sounding board during development, particularly around the syntax choices. Because Gruber never published a formal specification with a test suite, many incompatible variants emerged over the years; the CommonMark project, launched in 2014, produced the first unambiguous specification to resolve those inconsistencies.
How it works
A Markdown file is plain UTF-8 text with no binary sections or special encoding. Formatting is expressed entirely through punctuation: a line starting with # becomes an h1 heading, a line starting with ## becomes an h2, and so on up to six levels. Blank lines separate paragraphs. Inline elements like bold, italic, links, and inline code use paired characters such as **, *, [], and backticks. Fenced code blocks use triple backticks, and many parsers accept a language name after the opening fence to enable syntax highlighting.
What it is used for
- Writing README files and documentation for software projects hosted on GitHub or GitLab
- Authoring blog posts and articles for static-site generators like Hugo, Jekyll, or Astro
- Taking structured notes in apps like Obsidian, Notion, or Bear where formatting must survive export
- Writing technical documentation, API references, and wikis that need to render in multiple output formats
How to open it
Any plain-text editor opens an MD file directly, including Notepad, TextEdit, VS Code, and Vim. To see the rendered output, use a Markdown-aware editor like Typora or Obsidian, a browser extension, or a tool that converts the file to HTML or PDF.
Pros and cons
Strengths
- Human-readable in raw form, so the file makes sense even without a parser
- Supported by nearly every developer platform, documentation tool, and note-taking app
- Converts cleanly to HTML, PDF, DOCX, and other formats through tools like Pandoc
- No proprietary format lock-in: the file is plain text that any editor can open forever
Trade-offs
- No single universal standard: GitHub Flavored Markdown, CommonMark, and other variants differ in edge cases
- Limited built-in support for tables, footnotes, and complex layouts without extensions
- Not ideal for highly formatted documents like legal contracts or print-ready publications
- Converting to formats like DOCX or PDF can lose subtle formatting depending on the parser used
Convert Markdown files
Free, in your browser, no signup. Start at the Markdown converter, or jump straight to a popular conversion below.
Curious how fast and how small? See our measured conversion benchmarks.
Markdown FAQ
What is the difference between .md and .txt files?
Both are plain-text files. The .md extension signals that the file uses Markdown formatting conventions, so editors and platforms know to render the punctuation as headings, bold text, and links. A .txt file carries no formatting hints and is treated as bare text.
Is there an official Markdown standard?
John Gruber's original 2004 description on Daring Fireball is the closest thing to an original spec, but it was informal and left many cases undefined. CommonMark, published in 2014, is the most widely adopted formal specification today and is the basis for GitHub Flavored Markdown.
Can I convert a Markdown file to Word or PDF?
Yes. Pandoc is the most capable free tool for this: it reads Markdown and writes DOCX, PDF, EPUB, and dozens of other formats. Most static-site generators and documentation platforms also export Markdown to PDF via a browser print step.
Why do some Markdown files use .markdown instead of .md?
Both extensions are valid. The shorter .md extension became the convention because it is faster to type and is the default GitHub uses for README files. The longer .markdown extension is occasionally used when the author wants the filename to be self-explanatory without any prior knowledge of the extension.