Markdown is a lightweight markup language created by John Gruber in 2004. It lets you format text using plain-text syntax that's easy to read and write, then converts it to structurally valid HTML. Instead of writing <h1>Title</h1>, you simply write # Title. Instead of <strong>bold</strong>, you write **bold**.
The philosophy behind Markdown is readability. A Markdown-formatted document should be publishable as-is, as plain text, without looking like it's been marked up with tags or formatting instructions. This makes it perfect for note-taking, documentation, README files, blog posts, and any content where you want to focus on writing rather than formatting.
Today, Markdown is used everywhere: GitHub READMEs, Jira tickets, Slack messages, Notion pages, technical documentation, and even some email clients. If you work with text on a computer, you'll encounter Markdown.
There are several compelling reasons to choose Markdown over rich-text editors like Word or Google Docs:
Here's a comprehensive overview of the core Markdown syntax you'll use every day:
Use hash symbols to create headings. One hash for H1, two for H2, and so on up to H6:
# Heading 1
## Heading 2
### Heading 3
#### Heading 4| Style | Syntax | Result |
|---|---|---|
| Bold | **bold** | bold |
| Italic | *italic* | italic |
| Bold + Italic | ***both*** | both |
| Strikethrough | ~~strikethrough~~ | |
| Inline code | `code` | code |
Unordered lists use dashes, asterisks, or plus signs. Ordered lists use numbers:
- Item one
- Item two
- Item three
1. First step
2. Second step
3. Third step[Link text](https://example.com)
This is normal text.
> This is a blockquote.
> It can span multiple lines.For multi-line code, wrap with triple backticks and optionally specify the language for syntax highlighting:
```javascript
function greet(name) {
return `Hello, ${name}!`;
}
```| Header 1 | Header 2 |
|----------|----------|
| Cell 1 | Cell 2 |
| Cell 3 | Cell 4 |Many Markdown processors support additional features through extensions. These aren't part of the original specification but are widely supported:
- [ ] (unchecked) and - [x] (checked). Popular on GitHub for issue tracking.[^1] to create a footnote reference and [^1]: Text here for the content.$E = mc^2$) in compatible renderers.mermaid render flowcharts, sequence diagrams, and more.[!NOTE], [!WARNING], [!TIP] callouts.A Markdown preview tool converts your plain-text Markdown into formatted HTML and displays it alongside (or instead of) the raw source. The process works in three steps:
# Title becomes <h1>Title</h1>, and so on.Online Markdown preview tools handle all three steps in your browser using JavaScript. No server processing is needed. Your content stays private because nothing is sent over the network.
The biggest advantage of a live Markdown preview is immediate visual feedback. You type Markdown on the left and instantly see the formatted result on the right. This eliminates the guesswork of "will this look right?" and catches formatting mistakes as you make them.
Key benefits include:
./images/screenshot.png) so they work when the project is moved. instead of .Pro tip: Use a Markdown preview tool to validate your README files before pushing to GitHub. Broken formatting in your project's README is a common first impression killer.
There is no single "Markdown standard." Over the years, different implementations have added their own features, leading to several "flavors":
| Flavor | Used By | Notable Features |
|---|---|---|
| CommonMark | GitHub, GitLab, Discourse | Strict spec, unambiguous parsing |
| GitHub Flavored (GFM) | GitHub | Tables, task lists, strikethrough, alerts |
| MultiMarkdown | Academic writing, books | Footnotes, citations, metadata |
| PHP Markdown Extra | WordPress, PHP apps | Definition lists, fenced code blocks |
| RST/MDX | React docs, Docusaurus | JSX components inside Markdown |
For most users, GitHub Flavored Markdown (GFM) is the de facto standard. It's well-documented, widely supported, and covers the vast majority of use cases. When in doubt, write for GFM compatibility.
Is Markdown hard to learn?
Not at all. The basic syntax (headings, bold, italic, lists, links) can be learned in under 10 minutes. Most people are productive with Markdown after a single afternoon of use. The extended features (tables, footnotes, math) come naturally as you need them.
Can I convert Markdown to PDF?
Yes. Tools like Pandoc, md-to-pdf, and browser print functions can convert Markdown to PDF. Many Markdown editors also have built-in PDF export. For best results, use a CSS stylesheet to control the PDF layout.
What's the difference between Markdown and HTML?
Markdown is a shorthand for writing formatted text. It's designed for humans to write and read. HTML is a markup language designed for browsers to render. Markdown gets converted to HTML behind the scenes. You can embed HTML inside Markdown, but not the other way around.
Does Markdown support comments?
Standard Markdown doesn't have a comment syntax. However, some flavors support HTML comments (<!-- comment -->), which are ignored by the renderer. This is useful for leaving notes in collaborative documents.
Is my content safe in an online Markdown preview tool?
Reputable tools process everything client-side in your browser. No data is sent to any server. Your content never leaves your device, making it safe for drafting sensitive documents like API keys (though we still recommend using environment variables for actual secrets).