What Is Markdown?
Markdown is a lightweight markup language created by John Gruber in 2004, with significant contributions from Aaron Swartz. Its original goal was simple yet ambitious: allow people to write in an easy-to-read, easy-to-write plain text format that could be optionally converted to structurally valid HTML.
Unlike HTML, which requires opening and closing tags that clutter the reading experience, Markdown uses intuitive punctuation characters to indicate formatting. A hash sign becomes a heading. Asterisks create bold or italic text. Dashes form lists. The result is a document that looks clean and readable even before any conversion takes place.
Today, Markdown has become the de facto standard for writing on the web. It powers README files on GitHub, posts on Reddit, documentation for countless software projects, and is supported by tools like Notion, Obsidian, and Slack. Understanding Markdown is no longer optional for developers, technical writers, or anyone who publishes content online.
A Brief History of Markdown
Markdown was born out of frustration with the verbosity of HTML. John Gruber, who ran the popular Daring Fireball blog, wanted a writing format that was as readable as plain text but could produce clean HTML output. He worked with Aaron Swartz on the original specification and a Perl script that performed the conversion.
Since 2004, several extensions and variants have emerged. GitHub Flavored Markdown (GFM) added features like task lists, tables, and strikethrough. CommonMark attempted to create a standardized specification to resolve ambiguities in the original syntax. MultiMarkdown extended the language with footnotes, metadata, and more.
Despite these variations, the core syntax remains remarkably stable and consistent across implementations.
Basic Syntax
Headings
Headings in Markdown use the hash (#) symbol. The number of hashes indicates the heading level:
# Heading 1
## Heading 2
### Heading 3
#### Heading 4
##### Heading 5
###### Heading 6
A single # creates the largest heading (equivalent to <h1> in HTML), while six hashes create the smallest (<h6>). Most documents use heading levels 1 through 3. It is best practice to use only one # Heading 1 per document as the main title.
Bold and Italic Text
Emphasis is straightforward in Markdown. Wrapping text with single asterisks or underscores creates italic text, while double asterisks or underscores produce bold text:
*italic text* or _italic text_
**bold text** or __bold text__
***bold and italic*** or ___bold and italic___
Most style guides recommend using asterisks over underscores for consistency, since underscores can sometimes conflict with filenames or URLs that contain underscores.
Lists
Markdown supports both ordered and unordered lists. Unordered lists use dashes, asterisks, or plus signs:
- First item
- Second item
- Nested item
- Another nested item
- Third item
Ordered lists use numbers followed by periods:
1. First step
2. Second step
3. Third step
1. Sub-step
2. Another sub-step
An interesting detail: the actual numbers you use do not matter for ordered lists. Markdown will render them sequentially regardless. However, starting with 1. and continuing sequentially makes the raw text more readable.
Links and Images
Links use square brackets for the text and parentheses for the URL:
[Visit OpenAI](https://openai.com)
[Link with title](https://example.com "Example Website")
Images follow the same pattern but with an exclamation mark prefix:
You can also use reference-style links to keep your text clean when using the same URL multiple times:
[Google][1] is a search engine. So is [Bing][2].
[1]: https://google.com
[2]: https://bing.com
Code
Inline code uses single backticks:
Use the `console.log()` function to debug.
Code blocks use triple backticks (fenced code blocks) with an optional language identifier for syntax highlighting:
```javascript
function greet(name) {
return `Hello, ${name}!`;
}
```
Supported languages typically include javascript, python, html, css, bash, json, typescript, and many more, depending on the renderer.
Blockquotes
Blockquotes use the greater-than symbol:
> This is a blockquote.
> It can span multiple lines.
>
> It can also have multiple paragraphs.
Blockquotes can be nested:
> First level
>> Second level
>>> Third level
Tables
Tables use pipes and dashes to create columns and rows:
| Feature | Markdown | HTML |
|------------|----------|---------|
| Readability| High | Low |
| Learning | Easy | Medium |
| Portability| Excellent| Good |
You can control column alignment with colons in the separator row:
| Left-aligned | Center-aligned | Right-aligned |
|:-------------|:--------------:|--------------:|
| Text | Text | Text |
Horizontal Rules
Three or more dashes, asterisks, or underscores on a line create a horizontal rule:
---
***
___
These are useful for visually separating sections within a document.
Advanced Features
Task Lists
GitHub Flavored Markdown supports task lists, which are perfect for tracking to-do items:
- [x] Write the introduction
- [x] Add code examples
- [ ] Proofread the article
- [ ] Publish
Footnotes
Some Markdown processors support footnotes:
Here is a statement that needs a citation.[^1]
[^1]: This is the footnote content.
Strikethrough
Double tildes create strikethrough text:
~~This text is crossed out.~~
Definition Lists
Some extended Markdown implementations support definition lists:
Term
: Definition of the term.
Another Term
: Its definition.
Why Use Markdown?
Portability
Markdown files are plain text. They open in any text editor on any operating system. There is no proprietary format lock-in, no compatibility issues, and no special software required.
Version Control Friendly
Because Markdown is plain text, it works beautifully with version control systems like Git. You can track changes, review diffs, and collaborate through pull requests, something that is nearly impossible with binary formats like .docx or .pptx.
Speed
Writing in Markdown is fast. Once you learn the syntax, your hands never leave the keyboard. There is no need to reach for the mouse to click formatting buttons. This makes Markdown especially popular among developers and technical writers who value efficiency.
Flexibility
A single Markdown file can be converted to HTML, PDF, EPUB, DOCX, presentation slides, and more. Tools like Pandoc, printmd, and various static site generators make these conversions seamless. Write once, publish everywhere.
Focus on Content
Markdown strips away formatting distractions. When you write in Markdown, you focus on the words and the structure, not on font sizes, colors, or margins. This separation of content and presentation leads to clearer writing.
Getting Started
The best way to learn Markdown is to start using it. Create a new file with a .md extension, open it in any text editor, and start writing. Use a preview tool to see the rendered output as you type.
If you want to convert your Markdown to a professionally formatted PDF, tools like printmd make it straightforward. Simply write your content in Markdown, and let the tool handle the typography and layout.
For quick practice, try writing your next set of notes, a project README, or even a blog post in Markdown. Within an hour, the syntax will feel natural, and you will wonder why you ever used anything else.
Conclusion
Markdown has earned its place as one of the most important writing tools of the modern web. Its simplicity, portability, and flexibility make it suitable for everything from quick notes to full-length technical documentation. Whether you are a developer documenting an API, a student taking lecture notes, or a writer drafting a blog post, Markdown provides a clean, efficient foundation for your work.
The syntax covered in this guide will handle the vast majority of your writing needs. As you grow more comfortable, explore extensions like footnotes, definition lists, and math notation to unlock even more possibilities.