Fuad Blogs
· 5 min read

The Complete Markdown Syntax Guide

Every markdown feature you need — from headers to footnotes. A comprehensive reference for writing clean, readable content.

Table of Contents

Markdown is the lingua franca of developer writing. This guide covers every syntax feature you’ll encounter, with examples you can copy-paste.

Headings

Use # for headings. One # is the largest, six # is the smallest.

# Heading 1

## Heading 2

### Heading 3

#### Heading 4

##### Heading 5

###### Heading 6

In practice, you’ll use ## for sections and ### for subsections. Skip # — the page title handles that.

Text Formatting

Bold with **double asterisks**. Italic with *single asterisks*. Bold italic with ***triple asterisks***. Strikethrough with ~~double tildes~~.

**bold** and _italic_ and _**bold italic**_ and ~~strikethrough~~

Inline links use [text](url):

[Google](https://google.com)

Reference links keep URLs at the bottom:

[Google][google-ref]

[google-ref]: https://google.com

Autolinks work too:

<https://example.com>

Images

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

Use descriptive alt text. It matters for accessibility and SEO.

Lists

Unordered Lists

Use -, *, or + — they’re all the same:

- Item one
- Item two
  - Nested item
  - Another nested item
- Item three

Ordered Lists

Use numbers (the actual number doesn’t matter):

1. First
2. Second
3. Third

Task Lists

- [x] Completed task
- [ ] Pending task
- [ ] Another pending task

Blockquotes

Use >:

> This is a blockquote.
> It can span multiple lines.
>
> It can also contain blank lines.

Nested blockquotes:

> Outer quote
>
> > Inner quote
> >
> > > Even deeper

Code

Inline Code

Wrap with backticks:

Use `console.log()` for debugging.

Fenced Code Blocks

Triple backticks with an optional language identifier:

```javascript
function greet(name) {
  return `Hello, ${name}!`;
}
```

Indented Code Blocks

Four spaces or one tab:

    This is a code block
    created with indentation.

Fenced code blocks are almost always better — they support syntax highlighting.

Tables

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

Alignment:

| Left | Center | Right |
| :--- | :----: | ----: |
| L    |   C    |     R |

Horizontal Rules

Three or more -, *, or _:

---
---

---

All produce a horizontal line. Use --- — it’s also valid frontmatter delimiters, so it’s the most recognizable.

Escape Characters

Use \ to escape special characters:

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

HTML in Markdown

Most markdown processors let you embed raw HTML:

<div class="custom">
  <span style="color: red;">This works.</span>
</div>

Use sparingly. If you need complex markup, consider a component instead.

Nested Lists

Indent by 2-4 spaces (processor-dependent):

- First level
  - Second level
    - Third level
- Back to first

Definition Lists

Not universal, but supported by many processors:

Term
: Definition

Another Term
: First definition
: Second definition

Footnotes

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

[^1]: This is the footnote content.

Abbreviations

*[HTML]: HyperText Markup Language

HTML is the backbone of web pages.

Subscript and Superscript

Not standard markdown, but common with extensions:

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

Emphasis Boundaries

Asterisks must be surrounded by non-space characters:

_this works_ but * this does not *
**this works** but ** this does not **
[Link text](https://example.com "Title text")

The title appears on hover.

Images with References

![Alt text][image-ref]

[image-ref]: https://example.com/image.jpg "Title"

Column Width in Tables

Pad cells for readability:

| Name    | Age | City     |
| ------- | --- | -------- |
| Alice   | 30  | New York |
| Bob     | 25  | London   |
| Charlie | 35  | Tokyo    |

Nested Blockquotes with Lists

> 1. First item
> 2. Second item
>    - Nested item
> 3. Third item

Code Blocks in Blockquotes

> ```javascript
> const x = 1;
> ```

Escape in Code

Backticks inside inline code:

``Use `backticks` inside code``

Multiple Code Fences

Use more backticks for code containing triple backticks:

code with backticks

Best Practices

  • Use ATX-style headings (#) over underline style
  • One blank line between paragraphs
  • No trailing spaces (they create <br>)
  • Fenced code blocks over indented
  • Consistent list markers (pick - and stick with it)
  • Descriptive link text (avoid “click here”)
  • Alt text on every image

What’s Not Standard

These require specific markdown processors or extensions:

  • Task lists (GitHub Flavored Markdown)
  • Tables (GFM, CommonMark)
  • Footnotes (Markdown Extra, Pandoc)
  • Definition lists (PHP Markdown Extra)
  • Abbreviations (PHP Markdown Extra)
  • Subscript/superscript (Pandoc, MDX)

Astro uses marked by default, which supports most common extensions. Check your astro.config.mjs for custom remark/rehype plugins.

Quick Reference

Syntax Result
**bold** bold
*italic* italic
~~strike~~ strike
`code` code
[text](url) link
![alt](img) image
> quote blockquote
- item list item
1. item numbered list
--- horizontal rule
| H | H | table

That’s every markdown syntax feature you’ll realistically use. Bookmark this page as a reference when writing your next post.