Markdown
Markdown is a lightweight markup language that uses plain text formatting syntax to create structured documents that can be converted cleanly to HTML. It was designed to be easy to read and write in its raw form.
§ 1 Definition
Markdown was created in 2004 by John Gruber (with significant contributions from Aaron Swartz) as a minimal markup language that reads naturally as plain text while offering the structural elements of HTML. A Markdown file uses characters like #, *, and []() to indicate headings, emphasis, and links. It converts to HTML through a processor. Markdown has become the de facto standard for README files, documentation, forum posts, and note-taking. Its philosophy is that "a Markdown-formatted document should be publishable as-is, as plain text, without looking like it's been marked up with tags or formatting instructions."
§ 2 Common Markdown Syntax
The core syntax includes: # through ###### for headings of different levels, *italic* and bold for emphasis, - for unordered lists, 1. for ordered lists, text for links, !alt for images, > for blockquotes, and `code` for inline code. Code blocks use triple backticks with optional language specification for syntax highlighting. Tables, task lists, and strikethrough are part of GitHub Flavored Markdown (GFM), an extended version widely adopted across platforms.
§ 3 Why Markdown Won
Markdown succeeded because it solves a real problem: HTML is verbose and unpleasant to write in raw form. Markdown is portable (any text editor can open it), version-control friendly (diffs are clean and readable), and platform independent (it converts to HTML, PDF, DOCX, and more). It became the backbone of modern developer documentation (GitHub READMEs, Notion, Obsidian, Discord, Reddit, Stack Overflow). Its simplicity means it requires almost no learning curve for basic use, while supporting enough structure for complex documents.
§ 4 Limitations and Flavor Fragmentation
The biggest problem with Markdown is fragmentation. The original specification is intentionally minimal, leaving gaps that different platforms filled in incompatible ways. GitHub Flavored Markdown, CommonMark, R Markdown, and others each add slightly different syntax. Tables, footnotes, and definition lists work differently across processors. CommonMark is the most significant standardization effort, aiming to create an unambiguous spec and test suite. For complex documents with cross-references, charts, or academic citations, dedicated formats like AsciiDoc or reStructuredText may be more appropriate.
§ 5 In code
# Heading Level 1
## Heading Level 2
This text has **bold** and *italic* formatting.
- Unordered list item
- Another item
1. Ordered list item
2. Another item
[Atomic Glue](https://atomicglue.com)
> A blockquote goes here.
```python
def hello():
print("Hello, Markdown!")
```§ 6 Common questions
- Q. Is Markdown the same as HTML?
- A. No. Markdown is a lightweight plain-text format that converts to HTML. HTML is the underlying markup language of the web. Markdown is more readable as raw text.
- Q. Can Markdown do everything HTML can?
- A. No. Markdown covers common formatting but lacks native support for complex tables, interactive elements, or custom styling. You can embed raw HTML in Markdown for edge cases.
- Q. What is CommonMark?
- A. CommonMark is a standardized, unambiguous specification for Markdown, developed to reduce the fragmentation between different Markdown implementations.
- Markdown is a lightweight plain-text markup language that converts to clean HTML.
- Its core syntax covers headings, bold/italic, lists, links, images, and code blocks.
- Markdown is everywhere: GitHub, documentation, note-taking apps, forums.
- Fragmentation across "flavors" is its main weakness; CommonMark aims to fix this.
We use Markdown extensively for documentation and content workflows. It keeps version control clean and deployments fast. Our Web Development team can set up your content pipeline. Get in touch.
Get in touchMarkdown is a lightweight markup language that uses plain text formatting syntax to create structured documents that can be converted cleanly to HTML. It was designed to be easy to read and write in its raw form.
Category: General (also: Front End, Software Engineering, Content Strategy)
Author: Atomic Glue Technical Team
## Definition
Markdown was created in 2004 by John Gruber (with significant contributions from Aaron Swartz) as a minimal markup language that reads naturally as plain text while offering the structural elements of HTML. A Markdown file uses characters like #, *, and []() to indicate headings, emphasis, and links. It converts to HTML through a processor. Markdown has become the de facto standard for README files, documentation, forum posts, and note-taking. Its philosophy is that "a Markdown-formatted document should be publishable as-is, as plain text, without looking like it's been marked up with tags or formatting instructions."
## Common Markdown Syntax
The core syntax includes: # through ###### for headings of different levels, *italic* and **bold** for emphasis, - for unordered lists, 1. for ordered lists, [text](url) for links,  for images, > for blockquotes, and `code` for inline code. Code blocks use triple backticks with optional language specification for syntax highlighting. Tables, task lists, and strikethrough are part of GitHub Flavored Markdown (GFM), an extended version widely adopted across platforms.
## Why Markdown Won
Markdown succeeded because it solves a real problem: HTML is verbose and unpleasant to write in raw form. Markdown is portable (any text editor can open it), version-control friendly (diffs are clean and readable), and platform independent (it converts to HTML, PDF, DOCX, and more). It became the backbone of modern developer documentation (GitHub READMEs, Notion, Obsidian, Discord, Reddit, Stack Overflow). Its simplicity means it requires almost no learning curve for basic use, while supporting enough structure for complex documents.
## Limitations and Flavor Fragmentation
The biggest problem with Markdown is fragmentation. The original specification is intentionally minimal, leaving gaps that different platforms filled in incompatible ways. GitHub Flavored Markdown, CommonMark, R Markdown, and others each add slightly different syntax. Tables, footnotes, and definition lists work differently across processors. CommonMark is the most significant standardization effort, aiming to create an unambiguous spec and test suite. For complex documents with cross-references, charts, or academic citations, dedicated formats like AsciiDoc or reStructuredText may be more appropriate.
## In code
# Heading Level 1
## Heading Level 2
This text has **bold** and *italic* formatting.
- Unordered list item
- Another item
1. Ordered list item
2. Another item
[Atomic Glue](https://atomicglue.com)
> A blockquote goes here.
```python
def hello():
print("Hello, Markdown!")
```## Common questions
Q: Is Markdown the same as HTML?
A: No. Markdown is a lightweight plain-text format that converts to HTML. HTML is the underlying markup language of the web. Markdown is more readable as raw text.
Q: Can Markdown do everything HTML can?
A: No. Markdown covers common formatting but lacks native support for complex tables, interactive elements, or custom styling. You can embed raw HTML in Markdown for edge cases.
Q: What is CommonMark?
A: CommonMark is a standardized, unambiguous specification for Markdown, developed to reduce the fragmentation between different Markdown implementations.
## Key takeaways
- Markdown is a lightweight plain-text markup language that converts to clean HTML.
- Its core syntax covers headings, bold/italic, lists, links, images, and code blocks.
- Markdown is everywhere: GitHub, documentation, note-taking apps, forums.
- Fragmentation across "flavors" is its main weakness; CommonMark aims to fix this.
## Related entries
- [WYSIWYG Editor](atomicglue.co/glossary/wysiwyg-editor)
- [Open Source](atomicglue.co/glossary/open-source)
Last updated July 2025. Permalink: atomicglue.co/glossary/markdown