Markdown Syntax Guide: From Basics to Advanced Formatting

Imagine you could make text bold, create lists, and add headings — all without touching a toolbar button or learning HTML. That is basically Markdown. Created by John Gruber back in 2004, it was designed with one beautifully simple goal: let people write formatted text that is easy to read even as raw source code.

Today, Markdown is literally everywhere. GitHub? Markdown. Notion? Markdown. Discord messages? Yep, Markdown. Heck, even this blog post was written in Markdown first. Once you learn it, you will wonder how you ever lived without it.

Headings: The Hash Sign is Your Friend

Making headings in Markdown is as easy as counting hash marks. One hash for the biggest heading, six for the tiniest:

# Heading 1 (the big boss)
## Heading 2 (section title)
### Heading 3 (sub-section)
#### Heading 4
##### Heading 5
###### Heading 6 (the little guy)

Paragraphs and Line Breaks

Paragraphs are separated by a blank line. If you just hit Enter once, most Markdown renderers will smoosh those lines together into one paragraph (rude, I know). To force a line break within a paragraph, end the line with two spaces or use a <br> tag:

This is line one.
This is line two (notice the two trailing spaces above).

This is a whole new paragraph.

Bold, Italic, and Strikethrough

Want to add some oomph to your text? Asterisks and tildes have you covered:

*italic* or _italic_
**bold** or __bold__
***bold AND italic*** (for when you really mean it)
~~strikethrough~~ (for dramatic corrections)

Quick tip: most style guides recommend sticking with asterisks over underscores. Why? Because underscores can cause weird behavior inside words like some_variable_name. Asterisks play nice everywhere.

Lists: Ordered and Unordered

Unordered lists use dashes, asterisks, or plus signs. Pick one and be consistent (your teammates will appreciate it):

- Milk
- Eggs
  - Free range (fancy)
  - Regular (still good)
- Bread

Ordered lists use numbers followed by a period. Here is a neat trick — you can use 1. for every single item and Markdown will auto-number them for you. This is a lifesaver when you need to reorder things:

1. Wake up
1. Coffee (essential)
1. More coffee
1. Actually start working

Task Lists (GitHub Flavored Markdown)

These are perfect for to-do lists in GitHub issues and pull requests:

- [x] Write the introduction
- [x] Add code examples
- [ ] Proofread the article
- [ ] Pretend I proofread the article

Links and Images

Links follow a "text in brackets, URL in parentheses" pattern that becomes second nature fast:

[Click me!](https://example.com)
[Hover for a surprise](https://example.com "Surprise!")

If you are reusing the same URL multiple times, reference-style links keep things tidy:

Read the [official docs][docs] for more info.

[docs]: https://example.com/docs "Documentation"

Images work exactly like links but with an exclamation mark in front (think of it as the image shouting "look at me!"):

![A cute cat](cat.jpg)
![A cute cat](cat.jpg "This cat judges your code")

Code: Inline and Blocks

For inline code, wrap it in single backticks. For a code block, use triple backticks with an optional language name for syntax highlighting:

Use the `console.log()` function to debug.

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

Common language identifiers you will use: javascript, python, html, css, bash, json, sql, typescript.

Blockquotes

Prefix lines with > to create blockquotes. Great for callouts, warnings, or quoting that one Stack Overflow answer that saved your project:

> This is a blockquote.
>
> It can span multiple paragraphs.
>
> > And you can nest them, like inception for text.

Tables

Tables use pipes and hyphens. They look a bit fiddly in raw Markdown, but the result is worth it:

| Feature  | Syntax       | Result     |
| -------- | ------------ | ---------- |
| Bold     | `**text**`   | **text**   |
| Italic   | `*text*`     | *text*     |
| Code     | `` `code` `` | `code`     |

Want to control alignment? Add colons in the separator row: left colon for left-aligned, right colon for right-aligned, both for centered:

| Left     | Center       | Right      |
| :------- | :----------: | ---------: |
| data     | data         | data       |

Escaping Characters and Extras

Need a literal asterisk without triggering bold? Backslash is your escape hatch:

\*This is not italic\*
\# This is not a heading

Some parsers also support footnotes and collapsible sections (especially on GitHub). These are nice-to-haves that can make your documentation feel polished:

Here is a claim.[^1]

[^1]: Source for the claim.

<details>
<summary>Click to expand</summary>
Hidden content lives here. **Markdown** works inside!
</details>

Best Practices for Writing Clean Markdown

• One sentence per line. This makes git diffs way easier to read. Each sentence on its own line still renders as one paragraph.
• Blank lines are free — use them generously. Separate every heading, code block, and list with breathing room.
• Be consistent. Pick asterisks or underscores for emphasis and stick with your choice throughout the document.
• Use reference links for long URLs. Nobody wants to read a paragraph with a 200-character URL jammed in the middle.
• Lint your Markdown. Tools like markdownlint catch common mistakes automatically.

Where You Will Use Markdown

Pretty much everywhere, honestly:

• GitHub / GitLab: READMEs, issues, pull requests, wikis
• Static site generators: Jekyll, Hugo, Gatsby, Astro
• Documentation platforms: Docusaurus, MkDocs, Read the Docs
• Note-taking apps: Obsidian, Notion, Bear, Typora
• Chat platforms: Slack, Discord, Microsoft Teams

Learning Markdown is one of those skills that pays off immediately and keeps paying off forever. Whether you are a developer writing READMEs, a technical writer crafting docs, or just someone who takes notes, Markdown makes your text cleaner and your workflow faster. Bookmark this guide and come back whenever you need a refresher.