Markdown is a lightweight markup language created in 2004 that uses everyday punctuation symbols, such as hash marks for headings and asterisks for bold text, to format plain text documents. Files written in Markdown use the .md or .markdown file extension and open in any basic text editor without proprietary software. When you view an .md file on the web or in a preview pane, a software program called a Markdown processor reads those punctuation markers and converts them into structural HTML or printable documents.
Why did John Gruber create Markdown as a plain-text syntax?
John Gruber released Markdown in March 2004, with syntax feedback and testing from Aaron Swartz, to let writers format web content without typing repetitive HTML tags by hand. According to Daring Fireball’s Markdown project (2004), Gruber defined the name as both a plain-text formatting syntax and a software conversion tool, and its latest version, Markdown 1.0.1, came out on December 17, 2004, as an 18 KB Perl script named Markdown.pl that requires Perl 5.6.0 or later.
Traditional word processors like Microsoft Word use what is called a “What You See Is What You Get” (WYSIWYG) interface, where clicking toolbar buttons hides formatting instructions inside packaged XML archives such as .docx files (Markdown Guide, 2024; Tabular Editor, 2026). Markdown takes the opposite approach by borrowing conventions from plain-text email, keeping every formatting symbol visible right next to your words.
Gruber’s central design rule was that a Markdown document must be readable as-is in raw plain text without looking cluttered by markup tags or formatting code (Daring Fireball, 2004). He drew a clear distinction between the two formats: HTML is a publishing format for browsers, while Markdown is a writing format for people.
How does a Markdown processor convert .md files into HTML?
An .md or .markdown document is strictly a plain-text file registered under the official Internet media type text/markdown by the Internet Engineering Task Force in IETF RFC 7763 (March 2016), which requires every Markdown file sent under that type to declare its character set, such as UTF-8. Because the file holds only raw characters and punctuation, it never locks your writing into a single vendor’s application.
Turning a raw .md file into a formatted page follows a four-step workflow described in the Markdown Guide (2024):
- You create a plain-text file in any text editor, format your text with Markdown punctuation, and save it with the .md or .markdown extension.
- You open that .md file in a Markdown-capable application, code editor, or website build tool.
- The application runs a Markdown processor (also called a parser) that scans the punctuation lines and converts them into valid HTML tags, turning a single hash mark before Heading 1 into <h1>Heading 1</h1> and double asterisks around bold into <strong>bold</strong> (Contentful, 2026).
- A web browser or preview pane renders that generated HTML on screen, or a print engine exports the result as a PDF or presentation document.
When you need page elements that Markdown’s punctuation does not cover, Gruber’s specification allows you to write raw inline HTML tags directly inside the .md file, and the parser passes those tags through to the browser unchanged (Daring Fireball, 2004).
What are the core syntax rules for formatting an .md file?
Core Markdown syntax covers the structural elements most writers use in articles, notes, and technical documentation (Contentful, 2026; Daring Fireball, 2004):
| Element | Markdown Syntax in .md File | Converted HTML Output |
|---|---|---|
| Heading 1 to 6 | One to six hash marks (#) plus a space before Heading 1 to Heading 6 | <h1>Heading 1</h1> to <h6>Heading 6</h6> |
| Italic text | Single asterisks (*italic*) or single underscores (_italic_) | <em>italic</em> |
| Bold text | Double asterisks (**bold**) or double underscores (__bold__) | <strong>bold</strong> |
| Unordered list | – Item, * Item, or + Item | <ul><li>Item</li></ul> |
| Ordered list | 1. First item | <ol><li>First item</li></ol> |
| Blockquote | > Quoted paragraph | <blockquote><p>Quoted paragraph</p></blockquote> |
| Hyperlink | Anchor text in square brackets followed immediately by the URL in parentheses | <a href=”url”>anchor text</a> |
| Image | Exclamation mark, alt text in square brackets, and image path in parentheses | <img src=”image.png” alt=”alt text”> |
| Inline code | Single backticks (`code`) | <code>code</code> |
For multi-line code snippets, Google’s Markdown Style Guide (2024) recommends fenced code blocks created by placing three backticks on the line before and after the code rather than indenting lines by four spaces, because fenced blocks let you declare the programming language right after the opening backticks for syntax highlighting.
How do CommonMark and GitHub Flavored Markdown differ?
Gruber’s original 2004 syntax guide left several formatting edge cases open to interpretation, which caused different Markdown parsers to display the same .md file in incompatible ways. To fix those inconsistencies, a group of developers launched the CommonMark initiative in 2014 to establish a strict specification for core Markdown syntax (Contentful, 2026; FormatArc, 2026).
Base CommonMark intentionally covers only foundational elements: headings, paragraphs, emphasis, lists, links, images, blockquotes, and code blocks (FormatArc, 2026). Many platforms build on top of that baseline by adding extra syntax rules known as flavors.
The most widely adopted dialect is defined in the GitHub Flavored Markdown specification (2019), a strict superset of CommonMark that adds five formal extensions (FormatArc, 2026):
- Pipe tables built with vertical bars (|) and hyphen header dividers to generate HTML tables without writing raw tags.
- Strikethrough text wrapped in double tildes (~~deleted~~).
- Task lists using brackets (- [ ] for unchecked boxes and – [x] for completed items).
- Extended autolinks that turn bare URLs and www addresses into clickable links without angle brackets.
- A security filter that blocks specific raw HTML tags, such as script and iframe elements, from rendering on public pages.
Even when two tools both claim GitHub Flavored Markdown support, rendering can still vary by platform. On GitHub.com, features like callout alerts ([!NOTE]), Mermaid diagrams, and mathematical LaTeX blocks are processed by GitHub’s own web application layer on top of the parser, so they will not render in third-party GFM editors unless you install separate plugins (FormatArc, 2026).
What common mistakes break formatting in .md files?
A few syntax habits routinely trip up people switching from standard word processors to .md files:
- Pressing Enter once for a line break: Under CommonMark and GFM rules for .md files, a single newline inside a paragraph is treated as a space rather than a visible line break. To force a <br> break without starting a new paragraph, end the line with two trailing spaces or a backslash (\), or leave a full blank line to start a new paragraph (Google, 2024; FormatArc, 2026). Note that GitHub.com issue and pull request comment boxes treat a single Enter press as a line break, which is why text pasted from a comment into a repository .md file often merges together (FormatArc, 2026).
- Skipping the space after a heading hash mark: CommonMark and GFM require a space between the # character and your title text (write # Introduction, not #Introduction). Without that space, the parser reads the line as plain text or a hashtag (Contentful, 2026).
- Using pipe tables in a strict CommonMark parser: Because pipe tables belong to GitHub Flavored Markdown rather than base CommonMark, opening an .md file with tables in a basic CommonMark viewer displays raw vertical bars instead of a formatted grid (FormatArc, 2026).
Frequently asked questions
What program opens an .md file on Windows or macOS?
Any built-in plain-text editor, including Windows Notepad and macOS TextEdit (in plain-text mode), opens and edits .md files out of the box (Markdown Guide, 2024; Tabular Editor, 2026). If you want a live formatted preview alongside your raw text, code editors like Visual Studio Code and note-taking apps like Obsidian render .md files natively.
What is the difference between .md and .markdown file extensions?
Both extensions identify the exact same plain-text file under the text/markdown media type registered in IETF RFC 7763 (2016). Software developers and documentation tools simply prefer the shorter .md suffix by convention.
Why do software developers and AI tools use .md files instead of Word documents?
Because .md files contain only raw text and lightweight punctuation rather than packaged XML archives like .docx, version control systems such as Git can compare changes line by line in files like README.md (Tabular Editor, 2026). Large language models and AI coding agents also use .md files for project context, skills, and custom system prompts because plain-text punctuation stays readable for humans while using fewer tokens than heavy markup (Contentful, 2026; Tabular Editor, 2026).

