Markdown is a lightweight markup language that uses plain-text formatting syntax to create structured documents. Created by John Gruber (with contributions from Aaron Swartz) in 2004, Markdown was designed with a single, clear philosophy: the source text should be readable as-is, without requiring rendering. Unlike HTML, where tags like <strong> and <em> clutter the text, Markdown uses intuitive characters -- asterisks for emphasis, hashes for headings, dashes for lists -- that feel natural even before rendering.
The beauty of Markdown lies in its simplicity. A heading is just a line starting with #. Bold text is wrapped in **double asterisks**. A link is [text](url). These conventions are easy to learn, easy to remember, and easy to read in their raw form. This makes Markdown ideal for writing content that may be read both as source and as rendered output.
Today, Markdown is everywhere. GitHub uses it for README files, pull request descriptions, and issues. Documentation platforms like Read the Docs, GitBook, and Docusaurus are built on Markdown. Note-taking apps like Obsidian, Notion, and Bear support it natively. Static site generators like Hugo, Jekyll, and Gatsby use Markdown for content authoring. Chat platforms like Slack, Discord, and Teams support Markdown-like formatting. Even email clients are beginning to adopt Markdown for composing messages.
Markdown files use the .md or .markdown file extension. The MIME type is text/markdown (defined in RFC 7763). Because Markdown is plain text, it is inherently portable, version-control friendly, and future-proof -- your content is never locked into a proprietary format.
John Gruber published the original Markdown syntax description and a Perl script (Markdown.pl) on his site, Daring Fireball, on March 19, 2004. His goal was to create a format that was "as easy-to-read and easy-to-write as is feasible" while being convertible to structurally valid HTML. The syntax drew inspiration from conventions that had evolved organically in plain-text email and Usenet posts -- for example, using asterisks for emphasis and indentation for code.
Markdown quickly gained traction in the developer community. By 2008, GitHub had adopted Markdown for its README rendering, introducing what would later become GitHub Flavored Markdown (GFM). Stack Overflow adopted Markdown for its question-and-answer format. Reddit used a Markdown variant for comments. Blogging platforms like Tumblr and WordPress added Markdown support.
However, the original Markdown specification was intentionally informal. Gruber described the syntax through examples and prose, not through a formal grammar. This left many edge cases undefined: What happens when you nest blockquotes inside lists? How should blank lines within list items be handled? Different parsers answered these questions differently, leading to fragmentation and rendering inconsistencies.
This ambiguity motivated the creation of CommonMark in 2014, which aimed to provide a complete, unambiguous specification for Markdown. Since then, CommonMark has become the de facto standard that most modern Markdown parsers target.
CommonMark is a strongly specified, highly compatible version of Markdown. The project was initiated by Jeff Atwood (co-founder of Stack Overflow) and John MacFarlane (creator of Pandoc), along with a group of Markdown enthusiasts who were frustrated by the lack of a formal specification.
The CommonMark spec defines the syntax through a combination of prose descriptions and over 600 test examples. Each example shows the input Markdown and the expected HTML output, leaving no room for ambiguity. The spec covers every aspect of Markdown parsing, from how precedence works between inline elements to how lazy continuation lines interact with block-level constructs.
Key principles of CommonMark include:
CommonMark-compatible parsers are available in virtually every programming language: commonmark.js (JavaScript), cmark (C), commonmark-java (Java), comrak (Rust), goldmark (Go), and many more. If you are building a tool or platform that renders Markdown, targeting the CommonMark spec ensures consistent, predictable output.
Let's walk through the fundamental Markdown syntax elements. These are the building blocks you will use in virtually every Markdown document.
Headings are created using the # character. The number of hashes determines the heading level, from 1 (largest) to 6 (smallest):
# Heading 1
## Heading 2
### Heading 3
#### Heading 4
##### Heading 5
###### Heading 6
CommonMark requires a space between the # characters and the heading text. #Heading (without a space) is not a valid heading. Headings can also include inline formatting: ## This is **bold** heading.
An alternative syntax for level 1 and 2 headings uses underlines:
Heading 1
=========
Heading 2
---------
This alternative (called "setext headings") is supported by CommonMark but less commonly used than ATX headings (the # style).
Paragraphs are separated by one or more blank lines. Adjacent lines of text without a blank line between them are joined into a single paragraph:
This is the first paragraph. It can span
multiple lines in the source.
This is the second paragraph.
To create a hard line break within a paragraph (an HTML <br>), end the line with two or more spaces, or use a backslash (\) at the end of the line:
This line has a hard break
after the two trailing spaces.
This line also breaks\
using a backslash.Use asterisks or underscores for emphasis:
*italic* or _italic_
**bold** or __bold__
***bold and italic*** or ___bold and italic___
The convention in most style guides is to use asterisks rather than underscores, because underscores can behave unexpectedly within words in some parsers (e.g., foo_bar_baz might be interpreted as emphasis in some renderers but not others). CommonMark handles this correctly by only treating underscores as emphasis delimiters at word boundaries, but asterisks are the safer, more universal choice.
Unordered lists use -, *, or + as markers. Ordered lists use numbers followed by a period or closing parenthesis:
- Item one
- Item two
- Item three
1. First item
2. Second item
3. Third itemNested lists are created by indenting (typically 2 or 4 spaces):
- Parent item
- Child item
- Another child
- Grandchild item
- Another parentIn ordered lists, the actual numbers do not matter for rendering -- Markdown will number them sequentially. However, it is good practice to use correct sequential numbers for readability of the source text.
Inline links use the format [link text](URL). You can optionally add a title attribute:
[Visit QuickUtil](https://quickutil.dev)
[Hover for title](https://example.com "Example Site")Reference-style links let you define URLs elsewhere in the document, keeping the text cleaner:
Check out [QuickUtil][1] for developer tools.
[1]: https://quickutil.dev "QuickUtil - Free Dev Tools"
Autolinks are URLs wrapped in angle brackets: <https://quickutil.dev>. Many Markdown flavors (including GFM) also autolink bare URLs without angle brackets.
Images use the same syntax as links, prefixed with an exclamation mark:
The alt text is important for accessibility -- screen readers use it to describe the image. In contexts where images cannot be displayed (like a terminal), the alt text serves as a fallback.
Inline code is wrapped in backticks:
Use the `console.log()` function for debugging.If your code contains backticks, use double backticks:
``Use `backticks` inside code``Code blocks (multi-line code) can be created by indenting each line with 4 spaces or by using fenced code blocks with triple backticks:
```javascript
function greet(name) {
return `Hello, ${name}!`;
}
```
The language identifier after the opening backticks (e.g., javascript) enables syntax highlighting in renderers that support it. This is not part of the core CommonMark spec but is widely supported as an extension.
Blockquotes are created with the > character:
> This is a blockquote.
> It can span multiple lines.
>
> It can contain multiple paragraphs.Blockquotes can be nested:
> Outer quote
>> Nested quote
>>> Deeply nestedBlockquotes can contain any other Markdown elements -- headings, lists, code blocks, and even other blockquotes.
Create a horizontal rule (thematic break) with three or more hyphens, asterisks, or underscores on a line by themselves:
---
***
___Beyond the basics, Markdown supports several advanced formatting features that are essential for technical writing and documentation.
Tables are not part of the core CommonMark spec but are supported by virtually all Markdown flavors (GFM, PHP Markdown Extra, etc.). They use pipes and hyphens:
| Feature | Markdown | HTML |
|------------|-------------------|-------------------------|
| Bold | `**text**` | `<strong>text</strong>` |
| Italic | `*text*` | `<em>text</em>` |
| Code | `` `code` `` | `<code>code</code>` |
| Link | `[text](url)` | `<a href="url">text</a>` |Column alignment is controlled by colons in the separator row:
| Left-aligned | Center-aligned | Right-aligned |
|:-------------|:--------------:|--------------:|
| Left | Center | Right |Tables do not need to be perfectly aligned in the source -- the pipes just need to be present. However, aligning them makes the source text much more readable.
Task lists (checkboxes) are a popular GFM extension:
- [x] Write the introduction
- [x] Add code examples
- [ ] Review and edit
- [ ] PublishOn GitHub, task lists in issues and pull requests are interactive -- you can check and uncheck items directly in the rendered view.
Strikethrough text is created with double tildes (a GFM extension):
~~This text is struck through~~Footnotes let you add references without cluttering the main text:
Markdown was created in 2004[^1].
[^1]: By John Gruber, with help from Aaron Swartz.Footnotes are supported by PHP Markdown Extra, Pandoc, and several other flavors, though they are not part of CommonMark or GFM.
Some Markdown flavors support definition lists:
Markdown
: A lightweight markup language for formatting text.
CommonMark
: A standardized specification for Markdown.To display a literal character that has special meaning in Markdown, prefix it with a backslash:
\* This is not italic \*
\# This is not a heading
\[This is not a link\](url)
The following characters can be escaped: \ ` * _ { } [ ] ( ) # + - . ! |.
Markdown supports inline HTML. When Markdown syntax is insufficient, you can use raw HTML tags:
This is a paragraph with <abbr title="HyperText Markup Language">HTML</abbr> inside.
<details>
<summary>Click to expand</summary>
Hidden content here. **Markdown** works inside HTML blocks
if there is a blank line separating them.
</details>
The <details> and <summary> elements are particularly useful on GitHub for creating collapsible sections in README files and issues.
Markdown's versatility makes it the go-to format for a wide range of writing tasks. Here are the most common use cases and how to approach each one.
The README is often the first thing people see when they visit a repository. A well-structured README should include:
A good README template in Markdown:
# Project Name
Short description of the project.
## Installation
```bash
npm install project-name
```
## Usage
```javascript
const project = require('project-name');
project.doSomething();
```
## API
### `doSomething(options)`
| Parameter | Type | Default | Description |
|-----------|--------|---------|------------------------|
| `timeout` | number | 5000 | Timeout in ms |
| `retries` | number | 3 | Number of retry attempts |
## Contributing
See [CONTRIBUTING.md](CONTRIBUTING.md) for details.
## License
MITMarkdown is the backbone of modern technical documentation. Documentation-focused static site generators like Docusaurus, MkDocs, VitePress, and GitBook all use Markdown as their primary content format. This approach offers several advantages:
For API documentation, Markdown works well with tools like Swagger/OpenAPI for auto-generated reference docs, while hand-written Markdown guides provide conceptual explanations, tutorials, and getting-started content.
The rise of Markdown-based note-taking apps has transformed personal knowledge management. Tools like Obsidian, Logseq, and Dendron store notes as plain Markdown files in local directories, giving users full ownership of their data. Key Markdown features for note-taking include:
[[Page Name]] syntax for linking between notes (Obsidian, Logseq)#tag for categorizing notes![[note]] for transclusion (embedding one note inside another)Static site generators have made Markdown the standard format for blog content. A typical blog post in Markdown includes YAML front matter for metadata:
---
title: "My Blog Post"
date: 2026-03-12
author: "Suvom Das"
tags: ["markdown", "writing", "tools"]
description: "A guide to writing with Markdown."
---
# My Blog Post
The content starts here...The front matter is parsed by the static site generator and used for page metadata, SEO tags, and template rendering. The body content is rendered from Markdown to HTML.
Markdown, combined with Pandoc, is increasingly used for academic papers. Pandoc can convert Markdown to LaTeX, PDF, DOCX, and other formats. Extensions like citation support ([@citation-key]), math equations (using LaTeX syntax), and cross-references make Markdown viable for scholarly writing. Tools like R Markdown and Quarto extend this further with executable code blocks for reproducible research.
Many communication platforms support Markdown or Markdown-like formatting:
Because the original Markdown spec was incomplete, various "flavors" have emerged that extend the base syntax with additional features. Understanding these flavors helps you write Markdown that renders correctly on your target platform.
GFM is the most influential Markdown flavor. It builds on CommonMark and adds:
- [x] checkbox syntax~~text~~:rocket:, :thumbsup:, etc.#123 links to issue number 123The GFM spec is published at github.github.com/gfm and is a strict superset of CommonMark.
Pandoc, the "Swiss Army knife" of document conversion, supports an extended Markdown syntax that includes footnotes, definition lists, superscript/subscript, math (LaTeX), citation syntax, table captions, and much more. Pandoc can convert between dozens of formats, making its Markdown flavor one of the most feature-rich.
MultiMarkdown (MMD) adds features like metadata, cross-references, math support, table captions, image attributes, and glossary entries. It was one of the earliest Markdown extensions and influenced many later flavors.
R Markdown combines Markdown with executable R code blocks, enabling reproducible data analysis and reporting. It can produce HTML, PDF, Word documents, slideshows, and dashboards. The more recent Quarto project generalizes this approach to support Python, Julia, and Observable JS in addition to R.
| Feature | CommonMark | GFM | Pandoc |
|---|---|---|---|
| Headings | Yes | Yes | Yes |
| Tables | No | Yes | Yes |
| Task Lists | No | Yes | Yes |
| Strikethrough | No | Yes | Yes |
| Footnotes | No | No | Yes |
| Math (LaTeX) | No | No | Yes |
| Definition Lists | No | No | Yes |
| Citations | No | No | Yes |
Follow these guidelines to write clean, maintainable, and portable Markdown documents.
Start with a single # H1 for the document title, then use ## H2 for major sections, ### H3 for subsections, and so on. Never skip heading levels (e.g., going from ## H2 directly to #### H4). A consistent hierarchy improves readability, accessibility, and SEO when the document is rendered as a web page.
Always put a blank line before and after headings, code blocks, lists, blockquotes, and tables. While some parsers are lenient about this, omitting blank lines can cause unexpected rendering in stricter CommonMark-compliant parsers:
## Good Practice
A paragraph before the list.
- Item one
- Item two
Another paragraph after the list.
## Bad Practice
A paragraph before the list.
- Item one
- Item two
Another paragraph (might not render correctly).
Prefer # Heading (ATX style) over the underline style (setext). ATX headings support all 6 levels, are more compact, and are easier to scan in the source. Most style guides and linters recommend ATX headings.
Always specify the language for fenced code blocks. This enables syntax highlighting and helps readers identify the language at a glance:
```python
def hello(name: str) -> str:
return f"Hello, {name}!"
```
Use text or plaintext as the language identifier for plain text that should not be highlighted. Use bash or shell for terminal commands.
While Markdown does not enforce line length limits, keeping lines under 80-120 characters makes the source easier to read in editors and produces cleaner diffs in version control. Some teams use "one sentence per line" for prose content, which makes Git diffs more readable because changes to one sentence do not affect adjacent lines.
If you link to the same URL multiple times, use reference-style links. This keeps the prose clean and makes URLs easier to update:
Read the [CommonMark spec][commonmark] for details.
The [spec][commonmark] covers all edge cases.
[commonmark]: https://spec.commonmark.org/Alt text should describe the content and function of the image, not just its appearance. "Screenshot of the dashboard showing CPU usage at 85%" is better than "Dashboard screenshot" or "image1".
When writing Markdown for static site generators or documentation tools, use YAML front matter consistently. Define a schema for your front matter fields and stick to it across all documents:
---
title: "Page Title"
description: "Brief description for SEO"
date: 2026-03-12
tags: ["tag1", "tag2"]
draft: false
---
Use a Markdown linter like markdownlint (available as a CLI tool and VS Code extension) to enforce consistent style. Common rules include consistent heading style, no trailing spaces, no multiple consecutive blank lines, and proper list indentation. A .markdownlint.json configuration file lets you customize rules for your project.
The Markdown ecosystem includes a rich set of editors, renderers, and utilities for every workflow.
If you need to render Markdown in a web application, several excellent JavaScript libraries are available:
For syntax highlighting in code blocks, pair your Markdown renderer with a library like highlight.js or Prism.js.
Our free Markdown Preview tool gives you a live, side-by-side Markdown editing and rendering experience directly in your browser. No data is sent to any server -- all processing happens locally on your machine.
Type or paste Markdown in the editor pane and see the rendered output update in real time. The preview supports all standard Markdown syntax including headings, emphasis, lists, links, images, code blocks, blockquotes, tables, and task lists.
Fenced code blocks with language identifiers are syntax-highlighted in the preview, making it easy to verify that your code examples look correct before publishing. The tool supports highlighting for all major programming languages.
Whether you are drafting a README for your open-source project, writing documentation for your API, composing a blog post, or just learning Markdown syntax, our Markdown Preview tool provides a fast, distraction-free environment for working with Markdown. No account required, no installation needed -- just open the page and start writing.
Stop switching between your editor and browser to check Markdown rendering. Use our free tool to write and preview Markdown side-by-side, right in your browser -- with zero data sent to any server.
Try the Markdown Preview Tool NowMarkdown is a lightweight markup language created by John Gruber in 2004. It uses simple, intuitive syntax -- like asterisks for bold, hashes for headings, and dashes for lists -- to format plain text that can be converted to HTML and other formats. Markdown is widely used for README files, documentation, blog posts, notes, and messaging platforms.
CommonMark is a standardized specification for Markdown syntax. The original Markdown description by John Gruber left many edge cases ambiguous, leading to inconsistent rendering across different parsers. CommonMark, launched in 2014, provides a rigorous spec with over 600 examples that define exactly how every Markdown construct should be parsed and rendered.
Markdown is a simpler, more readable syntax that gets converted to HTML. While HTML uses verbose tags like <strong> and <em>, Markdown uses concise symbols like ** and *. Markdown is designed for writing content quickly, while HTML provides full control over document structure and styling. Most Markdown renderers also allow inline HTML for cases where Markdown syntax is insufficient.
Create tables using pipes (|) and hyphens (-). The first row is the header, the second row defines column alignment using colons, and subsequent rows are data. Use colons on the left (:---), right (---:), or both (:---:) of the hyphens to align columns left, right, or center.
Yes, GitHub uses Markdown (specifically GitHub Flavored Markdown, or GFM) as the default format for README files. Files named README.md are automatically rendered on repository pages. GFM extends CommonMark with features like task lists, tables, strikethrough, autolinked URLs, and syntax-highlighted code blocks.
Use fenced code blocks with triple backticks (```) followed by the language name. For example, ```javascript starts a JavaScript code block. Close it with another set of triple backticks. Most Markdown renderers support syntax highlighting for hundreds of programming languages including JavaScript, Python, Go, Rust, Java, C++, and many more.
Master JSON syntax, formatting best practices, validation techniques, and common parsing errors.
Master Kubernetes YAML from Deployments and Services to advanced scheduling and security contexts.
Master Base64 encoding and decoding. Learn the algorithm, common use cases, Base64URL, and code examples in multiple languages.