File Formats
What Is Markdown? Syntax, CommonMark and GFM
Markdown is a lightweight markup language that adds headings, lists and links to plain text with a few symbols. We cover its history, its standards and what survives when you turn MD files into Word or PDF.
Author: Hemen Dönüştür Editör EkibiPublished: 7 min read
Think of a software project's README, the headed lists in a note-taking app, or the words you bold with asterisks in a chat app. Behind all of them is the same idea: Markdown. Markdown is a lightweight markup language that lets you define headings, lists, links and tables by adding a few simple symbols to plain text. The file stays readable in any text editor, yet it can be turned into a clean HTML page, a Word document or a PDF whenever you need. This article covers how Markdown came about, its core syntax, the differences between CommonMark and GitHub Flavored Markdown, and what to watch for when converting MD files.
What is Markdown?
Markdown is both a set of writing conventions and the common name for tools that convert text written with them into HTML. Files are usually saved with the .md or .markdown extension. According to its creator, John Gruber, the overriding design goal is readability: a Markdown document should be publishable as-is, as plain text, without looking like it has been marked up with tags or formatting instructions. Where HTML needs <strong>important</strong>, Markdown uses **important**, and even the raw version reads naturally.
A short history
John Gruber created Markdown in 2004, with Aaron Swartz contributing as a sounding board for his ideas. The syntax drew on conventions from plain-text email (asterisks for emphasis, hyphens for lists) and on earlier markup languages such as setext and Textile. Version 1.0.1 of Markdown.pl, the Perl script Gruber published on his Daring Fireball site, is dated December 17, 2004.
Gruber's description, however, was an explanation by example rather than a formal specification. Ambiguous cases (nested lists, indented code blocks, mixing in HTML) led every implementation to make its own choices, and the same text began producing different output in different tools. Two major responses followed:
- CommonMark (2014): a specification led by John MacFarlane that defines Markdown unambiguously and makes it testable with hundreds of examples. The first versions appeared in autumn 2014; the current version is 0.31.2, dated January 28, 2024. The specification has not yet been declared 1.0.
- GitHub Flavored Markdown (GFM, 2017): GitHub's formal specification built on top of CommonMark. It adds extensions such as tables, task lists, strikethrough, extended autolinks and, for security, the filtering of certain raw HTML tags. The latest published specification is 0.29-gfm, dated April 6, 2019.
Markdown also gained recognition in internet infrastructure: RFC 7763, published in March 2016, registered the text/markdown media type (MIME type) with an optional variant parameter that indicates which Markdown flavor the author intended.
Major Markdown variants
Beyond CommonMark and GFM there are other widespread variants. RFC 7764, published alongside RFC 7763, registered several of them and offered usage guidance:
- Markdown Extra: an early extension that added footnotes, definition lists and tables.
- MultiMarkdown: a variant aimed at academic writing, with metadata, citations and cross-references.
- Pandoc Markdown: the flavor used by the Pandoc converter, with many extensions for writing books and papers.
A practical rule: if your document uses only headings, lists, links, code and simple tables, it will look the same almost everywhere. If you rely on footnotes, definition lists or special block types, check which variant the target environment supports.
Core syntax
The part of Markdown you need day to day takes a few minutes to learn:
# Level one heading
## Level two heading
This paragraph has **bold**, *italic* and `code`.
- Bulleted list
- Second item
- Indented sub-item
1. Numbered list
2. Second step
[Link text](https://example.com)
> Blockquote
```
Multi-line code block
```Tables and task lists, added by GFM, look like this:
| Format | Extension |
|--------|-----------|
| Markdown | .md |
| Plain text | .txt |
- [x] Write the draft
- [ ] Review itParagraphs are separated by blank lines. A single line break is treated as part of the same paragraph in most implementations; to force a line break, end the line with two spaces. You can also write HTML directly inside Markdown. CommonMark allows it, though environments such as GFM block certain tags for security.
Where is Markdown used?
- Software development: READMEs, changelogs and contribution guides, plus issues and code review comments on platforms such as GitHub and GitLab.
- Technical documentation: static site generators that build websites from Markdown files.
- Note-taking: many note apps store or export notes as Markdown.
- Chat and community platforms: platforms such as Reddit and Discord use Markdown variants.
- Writing and publishing: producing HTML, PDF, DOCX and EPUB from a single Markdown source with tools like Pandoc.
- AI tools: chat-based AI assistants often format their answers in Markdown.
Strengths and weaknesses
| Strengths | Weaknesses |
|---|---|
| Readable even in raw form | Variants behave differently |
| Plain text: small, portable, version-control friendly | No fonts, colors or page layout |
| Converts easily to HTML, PDF and Word | No complex tables (merged cells) |
| Learnable in minutes | Images live in separate files |
| Not tied to any program | Whitespace and indentation mistakes change the output |
Which programs open Markdown?
Because Markdown is plain text, it opens in any text editor, Notepad and TextEdit included. For a formatted preview you can use the built-in Markdown preview in Visual Studio Code or dedicated editors such as Obsidian and Typora. GitHub and GitLab render .md files in repositories automatically. Word, on the other hand, does not open Markdown as formatted text, so you need to convert the file first.
Common problems and how to fix them
A list or heading does not render
CommonMark requires a space after the heading marker: ## Heading, not ##Heading. A list following a paragraph also often needs a blank line in between to render correctly.
Lines run together
A single line break does not split a paragraph. Leave a blank line for a new paragraph, or end the line with two spaces to break within a paragraph.
A table works on one platform but not another
Tables are not part of Gruber's original Markdown or the CommonMark core; they come from extensions such as GFM. Check which flavor the target platform supports.
A paragraph starting with a number becomes a numbered list
A line such as "2024. was a busy year" starts with digits and a period, so it can be parsed as a list. Escape the period with a backslash (2024\.) to prevent it.
Tips for converting Markdown files
On our converter, Markdown files are uploaded to our server and deleted within 30 minutes. For reading, we use the Markdig library with CommonMark and GitHub-style extensions (tables, task lists, footnotes, autolinks).
- Markdown to PDF and Markdown to Word keep headings, lists, code blocks, blockquotes and bordered tables. Task list checkboxes are turned into ☑ and ☐ characters so they remain visible in Word and PDF. Text is set in a 12 pt serif font by default, and code blocks in a monospaced font.
- Markdown to HTML turns a README into a self-contained web page with its character encoding declared.
- In the other direction, Word to Markdown, HTML to Markdown and PDF to Markdown produce GitHub-compatible Markdown: headings, bold and italic text, lists, tables, links, code blocks and blockquotes are kept; fonts, colors and page layout are dropped. In tables without a header row, the first row becomes the header, because GFM tables require one. Plain paragraphs that start with a number, such as "1. Clause", are escaped so they do not accidentally turn into lists. The file is saved as UTF-8 without a BOM.
Frequently Asked Questions
How do I open an MD file?
Any text editor will open it. To see it formatted, use Visual Studio Code's preview or a Markdown editor; if you want to read it in Word, convert it to DOCX.
What is the difference between CommonMark and GitHub Flavored Markdown?
CommonMark defines Markdown's core syntax with precise rules. GFM is a superset that adds extensions on top of CommonMark, such as tables, task lists, strikethrough and extended autolinks.
Can I make tables in Markdown?
Yes, with extensions such as GFM you can write simple tables using pipes and hyphens. For complex structures such as merged cells, use an HTML table or prepare the document in Word.
What is the difference between Markdown and HTML?
Markdown is a simpler writing format designed to be converted into HTML. It cannot express everything HTML can, but its raw form is far more readable. You can still write HTML inside Markdown when you need to.
Does Markdown have an official standard?
Gruber's original description is not a formal specification. The most widely accepted precise definition today is CommonMark, and the text/markdown media type was registered by RFC 7763 in March 2016.
Sources
- John Gruber, Daring Fireball: Markdown
- CommonMark Spec (version history)
- GitHub Flavored Markdown Spec
- IETF RFC 7763: The text/markdown Media Type (March 2016)
- IETF RFC 7764: Guidance on Markdown
- Wikipedia: Markdown (history, secondary source)
- Markdig: a CommonMark-compliant Markdown processor for .NET
