Markdown Guide: Syntax, Flavors, and Best Practices
Markdown is a lightweight markup language designed to be readable as plain text and convertible to HTML. It is the default format for README files, documentation, blog posts, and commenting systems.
Free Markdown EditorWrite and preview Markdown in real time.
Open Markdown Editor →Core Syntax
Headings
# H1 through ###### H6. Hash style is more portable than Setext underlines.
Emphasis
*italic*, **bold**, ***bold italic***, ~~strikethrough~~ (most flavors).
Links and Images
[Link text](https://example.com) — inline link — image[text][id] then [id]: https://url.com — reference link
Code
Inline: backticks. Blocks: triple backticks with optional language name for syntax highlighting.
Tables (GFM)
| Left | Center | Right |
|:-----|:------:|------:|
| A | B | C |
Flavors
| Flavor | Used by | Extras |
|---|---|---|
| CommonMark | Many platforms | Strict spec |
| GitHub Flavored (GFM) | GitHub, GitLab | Tables, task lists, strikethrough |
| MDX | Next.js, Docusaurus | JSX inside Markdown |
Best Practices
- One blank line between blocks — missing blank lines cause parser ambiguity
- Prefer fenced code blocks over indented — they support language hints
- Test in the target platform — GFM tables break in plain CommonMark
Note: Markdown defines structure, not style. The same file looks completely different on GitHub vs a documentation site vs a notes app.