Markdown solved a real problem: formatting text without lifting your hands off the keyboard to click toolbar buttons. With a few intuitive symbols, you can write headings, bold text, lists, links, and code that render beautifully as HTML. It has become the default for README files, documentation, and countless writing tools. This guide covers the core syntax and how to preview your work live.
Why Markdown Caught On
Markdown's appeal is that it is readable even before it is rendered. A Markdown document looks sensible as plain text, unlike HTML with its angle brackets. That gives it several advantages:
- Fast to write. Format as you type, no mouse required.
- Portable. Plain text works in any editor and version-controls cleanly.
- Readable raw. You can understand a Markdown file without rendering it.
- Converts to HTML. It maps directly to clean web markup.
The Core Syntax
You can be productive with just these essentials:
Headings use # symbols:
# Heading 1
## Heading 2
### Heading 3
Emphasis uses asterisks:
*italic*renders as italic**bold**renders as bold***bold italic***combines both
Lists are simple:
- Bullet item
- Another item
1. Numbered item
2. Second item
Links and images:
[link text](https://example.com)creates a linkembeds an image
Code uses backticks โ single for inline code, and triple for blocks:
a code block
Blockquotes use >:
> This is a quote.
That handful of symbols covers the vast majority of everyday formatting. The reason this small vocabulary works so well is that it maps neatly onto the structure most documents actually use: a few levels of headings, some emphasis, lists, the occasional link, and code. You rarely need more, and when you do, Markdown gets out of the way and lets you drop in raw HTML.
Step-by-Step: Write and Preview
Use the Markdown Preview tool, which renders live in your browser.
- Type Markdown in the editor panel.
- Watch the preview update in real time beside it, showing the rendered HTML.
- Adjust as you go โ see instantly how a heading, list, or table looks.
- Copy the result โ the rendered HTML or the Markdown source โ when you are done.
Tip: Leave a blank line between block elements โ paragraphs, lists, headings, and code blocks. Markdown uses blank lines to separate blocks, and forgetting them is the most common reason formatting does not render as expected.
Tables and Extended Syntax
Many Markdown flavors support tables using pipes and dashes:
| Feature | Supported |
|---------|-----------|
| Tables | Yes |
| Lists | Yes |
This renders as a clean table. GitHub Flavored Markdown adds task lists (- [ ] and - [x]), strikethrough (~~text~~), and automatic links. These extensions are widely supported but not universal, so check your target platform.
Where Markdown Shines
- Documentation. README files and docs sites are almost universally Markdown.
- Notes. Many note apps use it for quick, portable formatting.
- Content. Static site generators and this very blog are authored in Markdown.
- Comments and posts. GitHub, Reddit, and many forums accept Markdown.
If you are moving Markdown into a web page, remember to handle special characters correctly โ the HTML entity encoder helps when your text contains reserved symbols.
Common Mistakes to Avoid
- Missing blank lines. Blocks need separating blank lines to render properly.
- Inconsistent list markers. Stick to one bullet style within a list.
- Wrong code fences. Use triple backticks for blocks; single backticks only wrap inline code.
- Assuming every feature is universal. Tables and task lists are extensions โ confirm your platform supports them.
Conclusion
Markdown gives you clean, portable formatting with a syntax you can learn in minutes: # for headings, asterisks for emphasis, dashes for lists, backticks for code. Write it in a live preview so you see the rendered result as you type, remember to separate blocks with blank lines, and you will format documents faster than any toolbar allows.
Start writing now with the free Markdown Preview tool โ live, private, and in your browser.