What is Markdown
Markdown is a lightweight markup language that converts plain text into formatted HTML using simple, readable syntax.
John Gruber created it in 2004. The goal was a format readable as-is, no rendering required.
It's used in README files, documentation, static site generators, note-taking apps, and developer platforms like GitHub and GitLab.
Markdown is not a single standard. Parsers differ, flavors vary, and what renders in one editor may break in another.
Markdown Basic Syntax
The core syntax works across nearly every Markdown parser, from CommonMark to GitHub Flavored Markdown.
Headings in Markdown
Use # symbols before your heading text. One # for H1, two ## for H2, up to six ###### for H6.
# Heading 1
## Heading 2
### Heading 3
ATX-style headings (the # approach) are the most portable.
Setext style uses === or --- underlines below text, but only supports H1 and H2. Most people skip it.
Paragraphs and Line Breaks
Separate paragraphs with a blank line.
A single return does nothing. Two returns create a new paragraph.
For a hard line break (<br>), end a line with two or more spaces, then press Return.
Some parsers also accept a backslash \ at end of line.
Bold and Italic Text
**bold** → bold
*italic* → italic
***bold italic*** → bold italic
Underscores work too: __bold__, _italic_. Asterisks are more reliable across parsers.
Nesting works, but be consistent. Mixing * and _ in the same word causes unpredictable rendering in some editors.
Blockquotes
Prefix any line with > to create a blockquote.
> This is a blockquote.
> It can span multiple lines.
Nest them with >>. You can put other Markdown elements inside, including bold text, lists, and even other blockquotes.
Lists in Markdown
Two types: ordered and unordered. Both support nesting.
Ordered Lists
Use numbers followed by a period. The actual number doesn't matter, but 1. is the convention.
1. First item
2. Second item
3. Third item
Unordered Lists
Use -, *, or +. All render the same. Pick one and stay consistent in your codebase.
- Item one
- Item two
- Item three
Task Lists (GitHub Flavored Markdown)
GFM-specific. Renders as checkboxes in GitHub, Notion, and Obsidian.
- [x] Done
- [ ] Not done
Not supported in CommonMark without a plugin.
Nested Lists
Indent by two or four spaces (parser-dependent) to nest items.
- Parent item
- Child item
- Another child
- Grandchild
Mixing ordered and unordered in the same nested list works fine.
Code in Markdown
For inline code, wrap text in single backticks: `code`
For fenced code blocks, use triple backticks. Add a language identifier for syntax highlighting.
```javascript
const greeting = "Hello";
```
Most editors and platforms support language identifiers: python, bash, html, css, json, and more.
Indented code blocks (4 spaces) are part of the original spec but are widely considered outdated. Stick with fenced blocks.
Horizontal Rules
Three or more hyphens, asterisks, or underscores on their own line.
---
***
___
All render as <hr>. Put blank lines before and after to avoid accidental heading interpretation.
Markdown Extended Syntax
Extended syntax isn't in the original spec. Support depends on the parser.
CommonMark doesn't include tables or strikethrough. GFM does.
Check your target platform before relying on these.
Tables in Markdown
Use pipes | and hyphens - to build tables. A header row is required.
| Column 1 | Column 2 | Column 3 |
|----------|----------|----------|
| Cell | Cell | Cell |
Control alignment with colons in the separator row:
| Left | Center | Right |
|:-----|:------:|------:|
Tables don't support line breaks inside cells. For complex content, HTML is the better option.
Footnotes
Here is a claim.[^1]
[^1]: And here is the footnote definition.
The footnote reference renders as a superscript link. The definition appears at the bottom of the rendered output.
Supported in Pandoc, MultiMarkdown, and some static site generators. Not in standard CommonMark.
Strikethrough
~~strikethrough text~~
GFM-specific. Renders as <del> in HTML. Widely supported in GitHub, Notion, and Obsidian.
Highlight
==highlighted text==
Not universally supported. Works in Obsidian and some Markdown editors. Not in GFM or CommonMark.
Subscript and Superscript
H~2~O → subscript
E = mc^2^ → superscript
Pandoc and MultiMarkdown support these. Most web-based parsers don't.
Definition Lists
Term
: Definition
Supported in Pandoc and Kramdown. Useful for glossaries and documentation. Not in GFM.
Links and Images in Markdown
Links and images follow the same base syntax, with images adding a ! prefix.
Inline Links
[anchor text](https://example.com)
[anchor text](https://example.com "Optional title")
The title attribute appears as a tooltip on hover.
Reference Links
Separate the URL from the text, defined elsewhere in the document.
[anchor text][ref-id]
[ref-id]: https://example.com
Useful for long documents where repeated URLs clutter the text. The definition can go anywhere in the file.
Images
Alt text is required for accessibility. It also displays when the image fails to load.
Markdown has no native syntax for controlling image size or alignment. That requires inline HTML.
Linked Images
Wrap the image syntax inside a link.
[](https://example.com)
Markdown Escaping Special Characters
Certain characters trigger Markdown formatting. Escape them with a backslash \ to render literally.
Characters you can escape: \ ` * _ { } [ ] ( ) # + - . !
\*This will not be italic\*
Renders as: *This will not be italic*
If formatting is appearing where you don't want it, a backslash before the triggering character is the fix.
HTML in Markdown
Most Markdown parsers allow raw HTML inline. When native syntax falls short, HTML fills the gap.
Common uses: image sizing, colored text, centered content, complex tables, line breaks inside cells.
<img src="image.jpg" width="300" alt="description">
<br>
<details>
<summary>Click to expand</summary>
Hidden content here.
</details>
Not all parsers allow it. GitHub sanitizes certain tags. Some static site generators strip HTML entirely.
If your content targets multiple platforms, avoid HTML-dependent formatting.
Markdown Flavors and Rendering Differences
The original Markdown spec left too many edge cases undefined. Flavors exist to fill those gaps.
Same syntax, different output. That's the tricky part.
CommonMark
A strict, unambiguous Markdown specification. No tables, no task lists, no strikethrough.
The baseline. If you need guaranteed cross-platform consistency, CommonMark is the safest target.
GitHub Flavored Markdown (GFM)
Built on CommonMark, with additions: tables, task lists, strikethrough, and autolinks.
The most widely encountered Markdown flavor for developers. README files, pull requests, wikis, and issues all use GFM.
MultiMarkdown
Adds footnotes, definition lists, tables, math support, and document metadata via front matter.
Good for longer-form writing and academic documents.
Pandoc Markdown
The most feature-rich flavor. Supports nearly every extension, plus conversion to PDF, EPUB, DOCX, LaTeX, and more.
If you're building a documentation pipeline or writing system, Pandoc is worth learning.
Where Markdown Is Used
Markdown isn't just for developers anymore. It's in tools used by writers, designers, project managers, and researchers.
Developer platforms: GitHub, GitLab, Bitbucket, Stack Overflow, all render Markdown natively in issues, comments, and wikis.
Note-taking apps: Obsidian, Notion, Bear, Typora, iA Writer. Obsidian stores notes as raw .md files. Notion uses a Markdown-inspired editor with some proprietary extensions.
Static site generators: Jekyll, Hugo, Eleventy, Astro. Content lives in .md files; the generator converts them to HTML at build time.
Documentation tools: MkDocs, Docusaurus, GitBook, Read the Docs. Markdown is the standard input format.
Communication tools: Slack, Discord, Linear, and Jira support Markdown-style formatting in messages and comments, though each has slight variations.
Writing and publishing: Ghost, Hashnode, and Dev.to accept Markdown for blog posts. Reddit uses a Markdown-based editor.
FAQ on Markdown
What is Markdown used for?
Markdown is used for writing README files, documentation, blog posts, and notes. It converts plain text into formatted HTML using simple syntax. Developers, writers, and teams use it across GitHub, Notion, Obsidian, and static site generators like Jekyll and Hugo.
What is the difference between basic and extended Markdown syntax?
Basic syntax covers headings, bold, italic, lists, links, images, and code blocks. Extended syntax adds tables, footnotes, strikethrough, task lists, and definition lists. Extended features require a compatible parser like GFM, MultiMarkdown, or Pandoc.
Does Markdown work the same everywhere?
No. Rendering depends on the parser and flavor. GitHub Flavored Markdown supports task lists and tables; CommonMark does not. Always check which Markdown flavor your target platform uses before relying on extended syntax features.
How do I create a table in Markdown?
Use pipes | and hyphens - to define columns and headers. Add colons in the separator row for column alignment. Tables require a header row and are supported in GFM and most modern editors, but not in standard CommonMark.
How do I add a link in Markdown?
Use [anchor text](URL) for inline links. For reference links, define the URL separately as [id]: URL and reference it with [text][id]. Add an optional title in quotes after the URL for a hover tooltip.
What is GitHub Flavored Markdown?
GitHub Flavored Markdown (GFM) is a Markdown flavor built on CommonMark. It adds tables, task lists, strikethrough, and autolinks. It's the standard format for GitHub README files, issues, pull requests, and wikis.
How do I escape special characters in Markdown?
Use a backslash \ before the character. Works for * _ # [ ] ( ) \ and others. This prevents Markdown from interpreting the character as formatting syntax and renders it literally in the output.
Can I use HTML inside Markdown?
Yes, most parsers allow inline HTML. Useful for image sizing, centering content, or adding line breaks inside table cells. Some platforms like GitHub sanitize certain tags, so test before depending on raw HTML in published content.
What Markdown editor should I use?
Typora renders as you type. VS Code with the built-in preview works well for developers. Obsidian suits note-taking with linked files. For quick online editing, Dillinger and StackEdit both offer split-pane live preview with no setup required.
What is the difference between a fenced code block and an indented code block?
Fenced code blocks use triple backticks and support syntax highlighting with a language identifier. Indented code blocks use four spaces and are part of the original spec. Fenced blocks are more portable, better supported, and the standard approach in modern Markdown usage.
