You've been writing Markdown for years. Or maybe you just opened a .md file for the first time and thought, "Why does this look like someone typed with their elbows?" Either way, you're here because you want a quick reference for Markdown syntax — and ideally, a way to see your formatting come alive as you type.
Good news. This guide covers every piece of Markdown syntax you'll actually use, from headings and bold text to tables and code blocks. And if you want to write and preview side by side, the Markdown Preview tool does exactly that — no installs, no sign-ups, just paste and see.
Headings
Headings use hash symbols. One # for the biggest heading, six ###### for the smallest. You'll rarely go past three levels.
# Heading 1
## Heading 2
### Heading 3
#### Heading 4
Pro tip: always leave a blank line before and after headings. Some Markdown parsers won't render them correctly without that spacing.
Text formatting: bold, italic, and more
The basics are straightforward:
**bold text**
*italic text*
***bold and italic***
~~strikethrough~~
You can nest them, too. ***bold italic*** works fine. Need to combine strikethrough with bold? Stack the markers: ~~**bold and struck**~~.
One thing that trips people up: underscores also work for bold and italic (_italic_, __bold__), but asterisks are safer. Underscores can behave unpredictably in the middle of words on some parsers.
Links and images
Links follow a simple pattern — square brackets for the text, parentheses for the URL:
[ToolsJam](https://toolsjam.co)
Images use the same syntax with an exclamation mark in front:
That alt text matters. Screen readers use it, and it shows up when images fail to load. Don't skip it.
Reference-style links
If you're writing a long document with repeated links, reference-style links keep things tidy:
Check out [ToolsJam][1] for free browser tools.
[1]: https://toolsjam.co
The link definitions can go anywhere in the document — most people put them at the bottom. Your rendered output looks the same either way.
Lists: ordered and unordered
Unordered lists use dashes, asterisks, or plus signs. Pick one and stick with it:
- First item
- Second item
- Third item
Ordered lists use numbers followed by periods:
1. First step
2. Second step
3. Third step
Here's something useful: the actual numbers don't matter to most parsers. You could write 1. 1. 1. and the output would still render as 1, 2, 3. That said, using correct numbers makes your raw Markdown much easier to read.
Nested lists
Indent by two or four spaces (depending on the parser) to create sub-items:
- Main item
- Sub-item
- Another sub-item
- Next main item
Nesting works for both ordered and unordered lists, and you can mix them. An ordered list inside an unordered list? Totally fine.
Code: inline and blocks
For inline code, wrap text in single backticks:
Use the `console.log()` function to debug.
For multi-line code blocks, use triple backticks with an optional language identifier for syntax highlighting:
```javascript
function greet(name) {
return `Hello, ${name}!`;
}
```
The language tag after the opening backticks (javascript, python, css, html, etc.) tells the renderer which syntax highlighting rules to apply. Most Markdown viewers support dozens of languages.
Want to see how your fenced code blocks actually render? The Markdown Preview tool shows syntax-highlighted output instantly as you type.
Blockquotes
Prefix lines with > to create blockquotes:
> This is a quote.
> It can span multiple lines.
>
> Add a blank line with just `>` to create paragraph breaks within the quote.
You can nest blockquotes by stacking the > symbols:
> Outer quote
>> Nested quote
Blockquotes are great for highlighting important information, callouts, or — obviously — actual quotations.
Tables
Tables in Markdown look a bit odd in raw form, but they render beautifully:
| Feature | Supported |
|------------|-----------|
| Bold | Yes |
| Tables | Yes |
| Emoji | Yes |
The second row (the one full of dashes) separates the header from the body. You can align columns using colons:
| Left-aligned | Center-aligned | Right-aligned |
|:-------------|:--------------:|--------------:|
| Text | Text | Text |
Colon on the left means left-aligned (the default). Colons on both sides means centered. Colon on the right means right-aligned.
Honestly, building tables by hand is tedious. That's where a live preview becomes essential — you catch alignment issues immediately instead of pushing a commit and discovering your table looks like abstract art.
Horizontal rules
Three or more dashes, asterisks, or underscores on a line by themselves:
---
***
___
All three produce the same horizontal line. Use them to separate sections visually when a heading feels like overkill.
Task lists
GitHub-flavored Markdown (and many other renderers) supports checkboxes:
- [x] Write the intro
- [x] Add code examples
- [ ] Proofread
- [ ] Publish
The [x] renders as a checked box, [ ] as unchecked. These are great for tracking progress in README files, issue descriptions, and project notes.
Escaping special characters
What if you actually want to display an asterisk or hash symbol without triggering Markdown formatting? Use a backslash:
\*This won't be italic\*
\# This won't be a heading
Any Markdown-special character can be escaped: \*, \#, \[, \], \(, \), \|, \\, and so on.
Tips for writing better Markdown
Keep it readable in raw form. One of Markdown's biggest strengths is that the source file is legible even without rendering. Add blank lines between sections. Don't cram everything together.
Use consistent formatting. If you pick **bold** with asterisks, don't switch to __bold__ with underscores halfway through. Consistency helps other people (and future-you) edit the document.
Preview as you write. This one's obvious but often skipped. Small syntax mistakes — a missing backtick, an extra space before a list marker — can break your formatting in ways that are invisible in the raw text. Open the Markdown Preview tool in a browser tab, paste your Markdown on the left, and watch the rendered output on the right.
Don't over-format. Not every sentence needs bold text. Not every list needs to be nested three levels deep. Markdown shines when it's simple. Let the structure do the work.
Where Markdown gets used
You might be wondering: where does all this syntax actually apply? More places than you'd think.
- GitHub — README files, issues, pull requests, comments
- Static site generators — Jekyll, Hugo, Astro, Gatsby
- Note-taking apps — Obsidian, Notion, Bear, Typora
- Documentation platforms — GitBook, Docusaurus, Read the Docs
- Messaging — Slack, Discord, and Reddit all support Markdown (or subsets of it)
- Blogs — Many CMS platforms accept Markdown for post content
The syntax is the same everywhere, with minor variations. GitHub adds task lists and tables. Some apps support footnotes or math blocks. But the core — headings, bold, links, code, lists — works universally.
Start writing
Markdown takes about ten minutes to learn and maybe a day of practice before it becomes muscle memory. Bookmark this page as a reference, and when you need to check how something renders, open the Markdown Preview tool and test it live. No downloads. No accounts. Just type and see.