The ultimate collection of markdown syntax

Markdown is a small writing format with a surprisingly useful toolkit. This collection walks through the common syntax you will see in README files, docs, issue comments, blog posts, and knowledge bases.

Each section shows the raw Markdown first, then the rendered result. That makes this page useful as a reference, and also as a test page for typography, spacing, tables, code blocks, lists, and other content styles.

Quick notes before the examples

Markdown comes in flavors. CommonMark covers the core rules. GitHub Flavored Markdown adds popular extras such as tables, task lists, strikethrough, and autolinks. Some apps add more features, so treat this page as the practical common set rather than a law book with a tiny gavel.

Markdown can be simple.

It can also hold code, tables, quotes, lists, links, images, and a few handy extras.

Markdown can be simple.

It can also hold code, tables, quotes, lists, links, images, and a few handy extras.

Document structure

Start with the blocks that shape a page before getting into inline styling. These examples cover headings, paragraphs, and line breaks, which are the pieces most likely to reveal spacing problems in a blog template.

Headings

Headings use one to six hash marks. This post already has a page title, so the rendered examples below start at level two. In most documents, use a single level-one heading for the title, then move down in order.

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

Heading level 2 example

Heading level 3 example

Heading level 4 example

Heading level 5 example

Heading level 6 example

Setext headings

Setext headings are an older style. They only create level-one and level-two headings. They are readable in plain text, though many teams prefer hash headings because the level is obvious at the start of the line.

Heading level 1
===============

Heading level 2
---------------

Setext level 2 example

Paragraphs

Paragraphs are just text separated by blank lines. A single line break in the source usually stays part of the same paragraph, which keeps text pleasant to edit.

This is one paragraph with a sentence.
It continues on the next source line.

This is a new paragraph because there is a blank line above it.

This is one paragraph with a sentence. It continues on the next source line.

This is a new paragraph because there is a blank line above it.

Line breaks

For a hard line break, end a line with two spaces, or use a <br> tag. The two-space version is easy to miss, so many writers prefer the HTML tag when the break matters.

First line with two spaces at the end.  
Second line after a hard break.

First line with an HTML break.<br>
Second line after the break.

First line with two spaces at the end.
Second line after a hard break.

First line with an HTML break. Second line after the break.

Inline text

Inline syntax changes text inside a paragraph. This is where rhythm, color, link styling, code styling, and contrast either feel polished or start to wobble.

Emphasis

Use one marker for emphasis, two markers for strong emphasis, and three markers for both. Asterisks and underscores both work, but asterisks tend to be clearer around words.

This is *italic text*.
This is _also italic text_.
This is **bold text**.
This is __also bold text__.
This is ***bold italic text***.

This is italic text. This is also italic text. This is bold text. This is also bold text. This is bold italic text.

Strikethrough

GitHub Flavored Markdown supports strikethrough with double tildes. It is useful for corrections, status notes, and the occasional tiny joke.

~~Ship it on Friday~~

Ship it after the tests pass.

~~Ship it on Friday~~

Ship it after the tests pass.

Inline code

Inline code uses backticks. It is good for command names, file names, variables, package names, and short literal values.

Run `pnpm test` before opening the pull request.

The file is `content/blog/example/index.md`.

Run pnpm test before opening the pull request.

The file is content/blog/example/index.md.

Code spans with backticks inside

If the code itself contains a backtick, wrap the span in double backticks and add a space inside the markers.

Use `` `code` `` when you need to show literal backticks.

Use `code` when you need to show literal backticks.

Code blocks

Code blocks are one of the fastest ways to find weak content styling. They need enough contrast, clear padding, readable wrapping behavior, and syntax highlighting that does not fight the surrounding prose.

Fenced code blocks

Fenced code blocks use three or more backticks. Add a language name after the opening fence when you want syntax highlighting.

```typescript
type MarkdownExample = {
  name: string;
  rendered: boolean;
};
```

type MarkdownExample = {
  name: string;
  rendered: boolean;
};

Language-specific code fences

Use the language name after the opening fence to help the renderer pick the right syntax highlighting. Different renderers support different labels, but these names are common enough to be useful in docs.

Common application languages

```typescript
const label = "TypeScript";
```

```php
<?php
echo "Hello from PHP";
```

```ruby
puts "Hello from Ruby"
```

```csharp
using System;

Console.WriteLine("Hello from C#");
```

```java
class Example {
  public static void main(String[] args) {
    System.out.println("Hello from Java");
  }
}
```

const label = "TypeScript";

<?php
echo "Hello from PHP";

puts "Hello from Ruby"

using System;

Console.WriteLine("Hello from C#");

class Example {
  public static void main(String[] args) {
    System.out.println("Hello from Java");
  }
}

More code fence labels

Here are a few more labels that show up often in product docs, API guides, and README files.

Scripting, config, and data labels

```javascript
const message = "Hello from JavaScript";
```

```python
print("Hello from Python")
```

```go
package main

import "fmt"

func main() {
  fmt.Println("Hello from Go")
}
```

```json
{
  "enabled": true,
  "format": "markdown"
}
```

```yaml
enabled: true
format: markdown
```

const message = "Hello from JavaScript";

print("Hello from Python")

package main

import "fmt"

func main() {
  fmt.Println("Hello from Go")
}

{
  "enabled": true,
  "format": "markdown"
}

enabled: true
format: markdown

Fenced code blocks with long content

Long lines test wrapping and horizontal scrolling. Code should stay readable without breaking the surrounding layout.

```bash
curl "https://api.example.test/messages?filter=markdown&include=links,tables,code,images,lists,quotes"
```

curl "https://api.example.test/messages?filter=markdown&include=links,tables,code,images,lists,quotes"

Indented code blocks

Indented code blocks use four spaces before each line. They are part of core Markdown, but fenced code blocks are easier to read and edit.

    npm run build
    npm run test

npm run build npm run test

Quotes and lists

Quotes and lists are where Markdown starts to show document structure inside the body copy. Nested items should be readable without turning the page into a maze of indentation.

Blockquotes

Blockquotes start with >. They can hold paragraphs, emphasis, links, and other block content. Keep quotes short unless the source truly deserves the stage.

> A quote can be a single sentence.
>
> It can also include a second paragraph.

A quote can be a single sentence.

It can also include a second paragraph.

Nested blockquotes

Nested blockquotes add another > marker. Use this sparingly, since deeply nested quotes can become a hallway of gray boxes.

> First level quote.
>
> > Second level quote.

First level quote.

Second level quote.

Unordered lists

Unordered lists can use hyphens, asterisks, or plus signs. Pick one marker style in a document and keep it consistent.

- Inbox
- Phone number
- Webhook

* Email
* SMS
* Attachment

Inbox
Phone number
Webhook

Email
SMS
Attachment

Ordered lists

Ordered lists use numbers. Many renderers normalize the visible numbers, so writers often use 1. for every item to make reordering easy.

1. Create a draft.
1. Add examples.
1. Review the rendered page.

Create a draft.
Add examples.
Review the rendered page.

Nested lists

Indent nested list items under the parent. Two spaces often work, but four spaces can be clearer in mixed lists.

- Testing
  - Unit tests
  - Integration tests
  - End-to-end tests
- Documentation
  - API reference
  - Examples

Testing
- Unit tests
- Integration tests
- End-to-end tests
Documentation
- API reference
- Examples

Mixed lists

You can mix ordered and unordered lists. The trick is to keep indentation clean so readers and renderers agree.

1. Plan the article.
   - Pick the audience.
   - Pick the scope.
1. Write the examples.
   - Show syntax.
   - Show output.

Plan the article.
- Pick the audience.
- Pick the scope.
Write the examples.
- Show syntax.
- Show output.

Task lists

Task lists are a GitHub Flavored Markdown feature. They are useful for checklists in issues, release notes, docs drafts, and project plans.

- [x] Write the syntax example.
- [x] Show the rendered result.
- [ ] Make coffee optional but welcome.

Write the syntax example.
Show the rendered result.
Make coffee optional but welcome.

Links and media

Links, images, and reference targets need to feel useful without shouting. This section is especially good for checking underline style, hover color, image sizing, and linked-media behavior.

Links

Inline links put the label in square brackets and the destination in parentheses. You can also add a title in double quotes.

[MailSlurp](https://www.mailslurp.com/)

[MailSlurp with a title](https://www.mailslurp.com/ "MailSlurp")

MailSlurp

MailSlurp with a title

Reference links

Reference links keep long URLs out of the paragraph. They are handy when the same link appears several times.

Read the [CommonMark spec][commonmark] or the [GitHub Flavored Markdown spec][gfm].

[commonmark]: https://spec.commonmark.org/0.31.2/
[gfm]: https://github.github.com/gfm/

Read the CommonMark spec or the GitHub Flavored Markdown spec.

Autolinks

Autolinks wrap a URL or email address in angle brackets. GitHub Flavored Markdown also auto-links many bare URLs, but angle brackets make the intent explicit.

<https://www.mailslurp.com/>

<support@example.com>

MailSlurp

Email support

Images

Images look like links with an exclamation mark at the front. Always include useful alt text. It helps accessibility, search, and humans on slow connections.

![MailSlurp wordmark](/assets/branding/mailslurp-logo-text-dark-transparent.svg)

Images with linked targets

Wrap an image in a link when the image should be clickable. This is common for badges, diagrams, and product screenshots.

[![MailSlurp wordmark](/assets/branding/mailslurp-logo-text-dark-transparent.svg)](https://www.mailslurp.com/)

Tables and separators

Tables are compact, practical, and easy to make ugly. The goal is readable data with clear alignment, steady spacing, and enough borders to scan without visual noise.

Tables

Tables are part of GitHub Flavored Markdown. Use pipes for columns and hyphens for the header separator.

| Feature | Syntax | Notes |
| --- | --- | --- |
| Bold | `**text**` | Strong emphasis |
| Link | `[label](url)` | Inline link |
| Code | `` `value` `` | Inline code |

Feature	Syntax	Notes
Bold	`text`	Strong emphasis
Link	`[label](url)`	Inline link
Code	`value`	Inline code

Table alignment

Colons in the separator row align columns. This is useful for numbers, status columns, and quick comparisons.

| Item | Count | Status |
| :--- | ---: | :---: |
| Inboxes | 12 | Ready |
| Messages | 348 | Review |
| Webhooks | 4 | Ready |

Item	Count	Status
Inboxes	12	Ready
Messages	348	Review
Webhooks	4	Ready

Escaping characters

Use a backslash to show a Markdown marker as literal text. This helps when documentation needs to show asterisks, brackets, or hash marks without triggering formatting.

\*This is not italic.\*

\[This is not a link label\]

\# This is not a heading.

*This is not italic.*

[This is not a link label]

# This is not a heading.

Horizontal rules

Horizontal rules create a thematic break. Three or more hyphens, asterisks, or underscores work. Keep blank lines around them for clarity.

Text before the break.

---

Text after the break.

Text before the break.

Text after the break.

Platform extras

Many publishing systems support features beyond the smallest Markdown core. These examples are useful for checking how the template handles richer docs syntax while staying readable.

HTML in Markdown

Many Markdown renderers allow safe inline HTML. Use it only when plain Markdown cannot express the thing you need.

Rendered: Ctrl + K.

Rendered: highlighted text can be useful in examples.

This sentence includes Ctrl + K.

Highlighted text can be useful in examples.

Details blocks

Details blocks come from HTML, not Markdown, but they are common in docs. They are useful for optional explanations and long examples.

Rendered: many Markdown tools show a collapsible note here. This page keeps the live example in source form so the MDX renderer stays portable.

Open the extra note

This content starts collapsed.

Footnotes

Footnotes are supported by GitHub Flavored Markdown and many documentation systems. They keep the main sentence clean while still preserving extra context.

Markdown is easy to scan in source form.[^scan]

[^scan]: That source readability is one reason people still like it.

Markdown is easy to scan in source form.¹

Definition style notes

Some Markdown tools support definition lists, but CommonMark and GitHub Flavored Markdown do not define them as core syntax. A regular list is the safer portable option.

- Term: Markdown
  Definition: A lightweight plain-text writing format.
- Term: GFM
  Definition: GitHub Flavored Markdown.

Term: Markdown Definition: A lightweight plain-text writing format.
Term: GFM Definition: GitHub Flavored Markdown.

Front matter

Many static sites use front matter at the top of Markdown files. It is metadata, not page content. This site uses it for titles, descriptions, dates, tags, and template selection.

---
title: "Example title"
description: "Example description"
date: "2026-06-05T00:00:00.000Z"
tags:
  - "markdown"
---

Rendered: front matter is usually not shown inside the article body. The template reads it and uses it to build the page title, metadata, SEO tags, and navigation.

Comments

HTML comments can hide notes from the rendered page. Use them carefully. If a note matters to readers, it should probably be visible.

<!-- This note is visible in source but hidden in rendered output. -->

Visible text after the comment.

Visible text after the comment.

Backslash line continuation in examples

Markdown is often used to document shell commands. A backslash at the end of a shell line is not Markdown syntax, but it is common inside code blocks.

```bash
curl "https://api.example.test/messages" \
  --header "Authorization: Bearer token"
```

curl "https://api.example.test/messages" \
  --header "Authorization: Bearer token"

Markdown inside lists

Lists can contain paragraphs, code blocks, blockquotes, and nested lists. Indentation is the whole game here.

1. First item with a paragraph.

   This paragraph belongs to the first item.

1. Second item with code.

   ```txt
   Code inside a list item
   ```

First item with a paragraph.

This paragraph belongs to the first item.
Second item with code.
```
Code inside a list item
```

Markdown inside blockquotes

Blockquotes can contain lists and emphasis. This is useful when quoting docs, release notes, or a short decision record.

> Review checklist:
>
> - Read the rendered page.
> - Check links.
> - Check code blocks.

Review checklist:

Read the rendered page.

Check links.

Check code blocks.

Literal URLs in text

Some renderers auto-link bare URLs. Others do not. If the link matters, use explicit link syntax or angle brackets.

Bare URL: https://www.mailslurp.com/

Explicit URL: [https://www.mailslurp.com/](https://www.mailslurp.com/)

Bare URL: https://www.mailslurp.com/

Explicit URL: https://www.mailslurp.com/

Emoji and symbols

Markdown itself does not define emoji shortcodes, but many platforms support Unicode emoji or platform-specific shortcodes. For portable docs, plain text labels are safest.

Status: pass
Status: warning
Status: blocked

Status: pass

Status: warning

Status: blocked

Complete example and checklist

The final section brings several idioms together, then closes with a practical checklist. It is a compact way to see whether the page still feels calm after many Markdown features stack up.

A compact all-in-one example

Here is a small document that uses several common Markdown idioms together.

## Release checklist

Before release, confirm:

- [x] Tests pass
- [x] Docs render
- [ ] Links have been checked

> Keep the release boring. Boring releases are beautiful.

See the [email testing release checklist](/blog/email-testing-checklist/).

```bash
pnpm test
pnpm build
```

Release checklist

Before release, confirm:

Tests pass
Docs render
Links have been checked

Keep the release boring. Boring releases are beautiful.

See the email testing release checklist.

pnpm test
pnpm build

Final checklist

Use this quick checklist when writing Markdown for a real page:

Keep headings in order.
Leave blank lines around block elements.
Prefer fenced code blocks over indented code blocks.
Add language names to code fences.
Use useful link text.
Add alt text to images.
Keep tables small enough to scan.
Escape syntax when you need literal characters.
Preview the rendered page before shipping.

Markdown is friendly because it stays close to plain text. That is the whole charm: you can read the source, render it on the web, paste it into docs, and still understand what is going on without a tiny formatting wizard on your shoulder.

That source readability is one reason people still like it. ↩