Markdown File Format (Markdown)
Markdown is a lightweight markup language created by John Gruber, with help from Aaron Swartz, in 2004. Its goal is to let people write formatted documents using plain text that stays readable in its raw form. Simple symbols control structure: number signs create headings, asterisks or underscores produce emphasis, hyphens build lists, and backticks mark code. A Markdown processor then converts that plain text into HTML for display. Because a .md file is just text, it opens in any editor, works perfectly with version control like Git, and never locks you into a single application. Markdown became the de facto format for software documentation, README files, static-site content, technical wikis, and note-taking apps. The original specification left several details ambiguous, which led to popular variants: GitHub Flavored Markdown (GFM) added tables, task lists, strikethrough, and fenced code blocks, while CommonMark was created in 2014 to give Markdown a precise, unambiguous standard. Today Markdown powers GitHub and GitLab repositories, documentation generators such as MkDocs and Docusaurus, chat apps like Slack and Discord, and writing tools including Obsidian and Notion. It is the preferred choice whenever content needs to be both easy to write by hand and easy to convert into clean HTML.
Quick Facts
- Extension: .md, .markdown
- MIME Type: text/markdown
- Category: document
Advantages
- Plain text that stays readable even before rendering
- Works perfectly with Git and version control (clean diffs)
- Editable in any text editor with no special software
- Converts cleanly to HTML, PDF, and many other formats
- Faster to write than HTML or word processors for structured text
Disadvantages
- No single universal standard (flavors differ: CommonMark, GFM, others)
- Limited control over complex layout and precise styling
- Advanced features require HTML fallback or extensions
- Tables and footnotes are not part of the original specification
- No built-in support for fonts, colors, or page layout
Common Use Cases
- README files and software documentation on GitHub/GitLab
- Static-site and blog content (Jekyll, Hugo, Docusaurus, MkDocs)
- Technical wikis and knowledge bases (Obsidian, Notion)
- Note-taking and personal knowledge management
- Formatted messages in chat tools like Slack and Discord
Technical Details
Markdown is plain text with no binary structure, so a .md file is simply a sequence of characters interpreted by a parser. Block-level elements include headings (# through ######), paragraphs separated by blank lines, blockquotes (>), ordered and unordered lists, and code blocks (indented four spaces or fenced with triple backticks). Inline elements include emphasis (*italic*, **bold**), inline code (`code`), links ([text](url)), and images (). Raw HTML may be embedded directly for anything Markdown cannot express. CommonMark defines a precise reference grammar and test suite, while GitHub Flavored Markdown extends it with pipe-delimited tables, task list checkboxes, autolinks, and strikethrough (~~text~~). Many tools read optional YAML front matter delimited by triple dashes at the top of the file to store metadata such as title, date, and tags. Parsers like markdown-it, marked, Pandoc, and remark transform Markdown into an abstract syntax tree before emitting HTML.
Frequently Asked Questions about Markdown
What is Markdown used for?
Markdown is used to write formatted text in plain text. It is the standard for README files, software documentation, static-site content, wikis, and note-taking apps because it is easy to write by hand and converts cleanly into HTML.
What is the difference between Markdown and HTML?
HTML is a verbose markup language with tags like <strong> and <a>. Markdown uses simple symbols (#, *, -, []) that are far easier to read and write. A Markdown processor converts your text into HTML, and you can embed raw HTML inside Markdown when you need features it lacks.
Is Markdown the same as CommonMark or GitHub Flavored Markdown?
They are closely related. The original 2004 Markdown left some rules ambiguous. CommonMark is a strict, standardized specification, and GitHub Flavored Markdown (GFM) builds on CommonMark by adding tables, task lists, strikethrough, and autolinks. Files all use the .md extension.
How do I convert Markdown to HTML or PDF?
A Markdown processor such as Pandoc, markdown-it, or marked converts .md files to HTML, and HTML can then be rendered to PDF. FileChange handles Markdown conversion directly in your browser, so your files never leave your device.
Can Markdown include tables and images?
Images are part of standard Markdown using the  syntax. Tables are not in the original specification but are supported by GitHub Flavored Markdown and most modern processors using pipe characters to separate columns.
What program opens a .md file?
Any text editor opens a .md file because it is plain text, including Notepad, VS Code, and TextEdit. Editors like VS Code, Obsidian, and Typora also show a live formatted preview, and GitHub renders .md files automatically in the browser.