Text

Markdown: The Writer's Formatting Language

A complete guide to Markdown syntax, from basic formatting to advanced features like tables, code blocks, and extensions.

HandyUtils December 22, 2025 5 min read

Markdown lets you write formatted content using plain text. It's simple enough to learn in five minutes but powerful enough for documentation, README files, blogs, notes, and more. Here's everything you need to know.

Why Markdown?

Readable as plain text: Even without rendering, it's easy to read
Portable: Works everywhere—GitHub, Notion, Discord, Reddit, VS Code
Simple: No complex tags or menus
Convertible: Easily converts to HTML, PDF, Word, and more
Future-proof: Plain text never becomes obsolete

Basic Formatting

Headings

# Heading 1
## Heading 2
### Heading 3
#### Heading 4
##### Heading 5
###### Heading 6

Emphasis

*italic* or _italic_
**bold** or __bold__
***bold and italic*** or ___bold and italic___
~~strikethrough~~

Renders as:

italic
bold
bold and italic
~~strikethrough~~

Paragraphs and Line Breaks

Separate paragraphs with a blank line:

First paragraph.

Second paragraph.

For a line break without a new paragraph, end a line with two spaces or use  :

Line one  
Line two

Lists

Unordered Lists

- Item 1
- Item 2
  - Nested item
  - Another nested
- Item 3

* Also works with asterisks
+ Or plus signs

Ordered Lists

1. First item
2. Second item
3. Third item

Numbers don't have to be in order:
1. Still first
1. Second
1. Third

Task Lists (GitHub Flavored)

- [x] Completed task
- [ ] Incomplete task
- [ ] Another task

Completed task
Incomplete task
Another task

Links and Images

Links

[Link text](https://example.com)
[Link with title](https://example.com "Hover title")
[Reference link][ref-id]

[ref-id]: https://example.com "Optional title"

<!-- Auto-linking -->
<https://example.com>
<email@example.com>

Images

![Alt text](image-url.jpg)
![Alt text](image-url.jpg "Optional title")

<!-- Linked image -->
[![Alt text](image.jpg)](https://example.com)

Code

Inline Code

Use the `console.log()` function.

Use the console.log() function.

Code Blocks

```
Plain code block
```

```javascript
// Syntax highlighted
const greeting = "Hello, World!";
console.log(greeting);
```

```python
# Python code
def hello():
    print("Hello, World!")
```

Supported Languages

Common syntax highlighting identifiers:

javascript, js
python, py
typescript, ts
java, csharp, cpp, c
html, css, scss
json, yaml, xml
bash, shell, sh
sql, graphql
markdown, md
diff

Blockquotes

> This is a blockquote.
>
> It can span multiple paragraphs.
>
> > Nested blockquotes work too.

This is a blockquote.

It can span multiple paragraphs.

Nested blockquotes work too.

Horizontal Rules

---
***
___

All three create a horizontal line:

Tables

| Header 1 | Header 2 | Header 3 |
|----------|----------|----------|
| Cell 1   | Cell 2   | Cell 3   |
| Cell 4   | Cell 5   | Cell 6   |

Header 1	Header 2	Header 3
Cell 1	Cell 2	Cell 3
Cell 4	Cell 5	Cell 6

Table Alignment

| Left | Center | Right |
|:-----|:------:|------:|
| L    |   C    |     R |
| 1    |   2    |     3 |

Left	Center	Right
L	C	R
1	2	3

Extended Syntax

Not all Markdown processors support these, but most modern ones do.

Footnotes

Here's a sentence with a footnote.[^1]

[^1]: This is the footnote content.

Definition Lists

Term 1
: Definition of term 1

Term 2
: Definition of term 2

Abbreviations

The HTML specification is maintained by the W3C.

*[HTML]: Hyper Text Markup Language
*[W3C]: World Wide Web Consortium

Subscript and Superscript

H~2~O (subscript)
X^2^ (superscript)

Some processors use different syntax: H2O

Highlighting

==highlighted text==

Or use HTML: highlighted text

Emoji

:smile: :rocket: :thumbsup:

GitHub and many platforms support emoji shortcodes.

Escaping Characters

Use backslash to display literal characters:

\*not italic\*
\# not a heading
\[not a link\]

Characters that can be escaped: \ * _ { } [ ] ( ) # + - . ! |

HTML in Markdown

Most Markdown processors allow raw HTML:

<div class="custom">
  <p>Custom HTML content</p>
</div>

<details>
<summary>Click to expand</summary>
Hidden content here.
</details>

Common Patterns

README Structure

# Project Name

Short description of the project.

## Features

- Feature 1
- Feature 2
- Feature 3

## Installation

```bash
npm install my-package

Usage

const package = require('my-package');
package.doSomething();

Contributing

Pull requests are welcome.

License

MIT


### Documentation Page

```markdown
# Function Name

Brief description.

## Syntax

```javascript
functionName(param1, param2)

Parameters

Parameter	Type	Description
param1	string	Description
param2	number	Description

Return Value

Returns a boolean.

Examples

functionName('hello', 42); // true

Markdown Flavors

Different platforms extend Markdown differently:

CommonMark

The standardization effort. Defines core syntax precisely.

GitHub Flavored Markdown (GFM)

Adds:

Task lists
Tables
Strikethrough
Autolinks
Emoji shortcodes
Syntax highlighting

MDX

Markdown + JSX components:

import Chart from './Chart'

# My Document

<Chart data={[1, 2, 3]} />

Obsidian