"Markdown: The Complete Guide (Syntax, Tables, and Where It's Used)"

What Is Markdown and Why Did It Win?

Markdown is a lightweight markup language: you write plain text with a few conventional symbols, and it renders as formatted HTML. **bold** becomes bold, # Title becomes a heading. That's the whole idea.

Created by John Gruber in 2004, it beat every heavier alternative for three simple reasons:

• It's plain text. No proprietary format, no binary blob. Any editor on any OS can open it, forever.
• It's readable raw. A Markdown file makes sense even before rendering — unlike HTML or LaTeX source.
• It's versionable. Git diffs on Markdown are clean and human-readable, which is why developers standardized on it for documentation.

Today it's the default format for GitHub READMEs, technical docs, note-taking apps like Notion and Obsidian, static site generators (Hugo, Astro, Jekyll), and — this article you're reading was written in it.

Core Syntax: Source vs Rendered

Here's everything you'll use daily. Try any of these live in the Markdown Editor to see the rendered output side by side.

Headings

# H1 — one per document, usually the title
## H2 — main sections
### H3 — subsections

Six levels exist (# through ######), but well-structured documents rarely go past H3.

Emphasis

*italic* or _italic_
**bold** or __bold__
***bold italic***

Lists

- Unordered item
- Another item
  - Nested item (indent 2 spaces)

1. Ordered item
2. Second item

A nice trick: numbering doesn't have to be correct in the source. 1. / 1. / 1. renders as 1, 2, 3 — renderers count for you, so reordering items never breaks the list.

Links and Images

[Link text](https://example.com)
![Alt text](https://example.com/image.png)

An image is just a link with a ! in front. The alt text matters for accessibility and SEO — don't leave it empty.

Code

Inline code uses single backticks: `const x = 1`. For blocks, use triple-backtick fenced code blocks with an optional language tag for syntax highlighting:

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

Blockquotes

> This renders as a quote.
> Multiple lines stay in the same block.

GitHub Flavored Markdown: The Extras Everyone Uses

The original 2004 spec left gaps, so GitHub Flavored Markdown (GFM) filled them. These extensions are now supported almost everywhere.

Tables

| Feature  | Basic Markdown | GFM |
|----------|:--------------:|----:|
| Tables   | No             | Yes |
| Tasks    | No             | Yes |

The second row controls alignment: :--- left, :---: center, ---: right.

Task Lists

- [x] Write the draft
- [ ] Review it
- [ ] Publish

GitHub renders these as real checkboxes — interactive in issues and pull requests.

Strikethrough

~~deprecated approach~~

The Big Cheatsheet

Bookmark this table — it covers 95% of everyday Markdown:

Where Markdown Is Actually Used

• README files. Every GitHub, GitLab, or npm project expects one. If you're starting a project, a README Generator gets you a properly structured file (badges, install, usage, license) in minutes.
• Documentation sites. Docusaurus, Starlight, MkDocs and friends all consume Markdown files and output full websites.
• Note-taking apps. Obsidian stores pure .md files; Notion imports and exports it; Bear, Logseq and Joplin are Markdown-native.
• Static site generators. Hugo, Jekyll, Astro: blog posts are Markdown files with a frontmatter block on top.
• Chat tools. Slack and Discord support a Markdown-ish subset (*bold* in Slack, ``` fences in Discord) — close enough that your muscle memory transfers.
• Presentations. Tools built on Marp or reveal.js turn a Markdown file into slides — try it with Markdown Slides, where --- separates each slide.

And when you need to move between worlds: Markdown to HTML converts your file into clean markup for emails or CMS fields, while HTML to Markdown does the reverse — handy for migrating old web pages into a docs repo.

Common Gotchas

Line breaks don't work the way you expect. Pressing Enter once does not create a visible line break in most renderers. You need either two trailing spaces at the end of the line, or a full blank line to start a new paragraph. This is the #1 source of "my Markdown looks wrong" confusion.

Nested list indentation is picky. Some parsers want 2 spaces, others 4. If a nested item renders flat, add indentation until it works — and never mix tabs and spaces.

Special characters need escaping. Want a literal asterisk? Write \*. The same applies to _, #, | (inside tables), and backticks.

Raw HTML sometimes works, sometimes doesn't. Most renderers accept inline HTML like <br> or <details>, but sanitized environments (comments, chat) strip it. Don't rely on it for portable documents.

A Word on Flavors

There is no single "official" Markdown standard — the original spec was ambiguous, so dialects emerged. CommonMark is the rigorous base specification most modern parsers implement; GFM is CommonMark plus tables, task lists, strikethrough and autolinks; MultiMarkdown and Pandoc Markdown add academic features like footnotes and citations. In practice: write CommonMark + GFM and your documents will render correctly nearly everywhere.

Try It Yourself

The fastest way to learn Markdown is to type it and watch it render. Open the Markdown Editor — live preview, syntax highlighting, export to HTML or PDF. Free, in your browser, no account required.