Markdown Syntax Reference: Everything You Need in One Place

Markdown is the standard for README files, documentation platforms, note-taking apps, and developer forums. Its design principle: it should be readable as plain text even without rendering. This reference covers CommonMark and GitHub Flavored Markdown (GFM), the two most widely supported variants.

Connect on LinkedIn →

Headings

# H1 — Page Title
## H2 — Major Section
### H3 — Subsection
#### H4
##### H5
###### H6

Always include a space after the #. Headings create the document outline used by screen readers, table-of-contents generators, and search engines.

Emphasis

**bold** or __bold__
*italic* or _italic_
***bold and italic***
~~strikethrough~~ (GFM)

Use **asterisks** for bold — they work more consistently mid-word and in all parsers.

Lists

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

1. Ordered item
2. Second item

- [x] Completed task (GFM)
- [ ] Incomplete task (GFM)

Links and Images

[Link text](https://example.com)
[Link with title](https://example.com "Hover title")

![Alt text describing the image](image.png)


[Link text][ref]
[ref]: https://example.com

Alt text on images matters for accessibility — describe what the image shows, not what it is.

Code

`inline code`

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

Always specify the language after the fence — it enables syntax highlighting in GitHub and most renderers.

Tables (GFM)

| Left   | Center | Right |
|:-------|:------:|------:|
| text   | text   | text  |

Colons in the separator row control alignment. Column widths don't need to be aligned in the source.

Blockquotes

> This is a blockquote.
> Spans multiple lines.
>
> Multiple paragraphs with a blank > line.

Horizontal Rule

---

Escaping Special Characters

\*not italic\*
\# not a heading
\[not a link\]

HTML in Markdown

Most parsers allow inline HTML for elements Markdown doesn't support — <details>, <sup>, <sub>, custom attributes:

<details>
<summary>Click to expand</summary>
Hidden content here.
</details>

Writing Tips

• Use blank lines before and after headings, code blocks, and lists
• Pick one bullet character (-) and use it throughout
• Keep lines under 100 characters for readable diffs
• Write meaningful alt text for every image
• Use reference-style links for URLs that appear multiple times

Markdown in Professional Workflows

Markdown has become the standard writing format for software documentation, technical blogs, and knowledge bases. GitHub renders Markdown natively in README files, pull request descriptions, issues, and wiki pages. GitLab, Bitbucket, Notion, Confluence (with plugins), and most modern content management systems support Markdown input. Learning Markdown fluently pays dividends across every tool in a developer's daily workflow.

For technical documentation specifically, Markdown strikes the right balance between readability in source form and richness in rendered form. A README written in Markdown is readable in a plain text editor, in a terminal with cat, and in a browser with full formatting. This dual readability is why Markdown won over alternatives like reStructuredText and AsciiDoc for most use cases — the source format is human-friendly, not just machine-parseable.

Extended Syntax and Compatibility

The original Markdown specification left many edge cases undefined, which led to dozens of incompatible implementations. CommonMark standardized the core syntax, and GitHub Flavored Markdown (GFM) extended it with tables, task lists, strikethrough, and autolinked URLs. When writing Markdown, know which flavor your target platform supports — a table that renders perfectly on GitHub might appear as pipe-separated text on a platform that only supports CommonMark.

Tables are the most common extended syntax feature, but they're limited to simple grids. For complex layouts with merged cells, nested tables, or precise alignment, you'll need to drop to inline HTML. Most Markdown renderers allow inline HTML, but some sanitize it aggressively (removing style attributes, for example), so test your HTML blocks on the actual platform.

Code blocks with syntax highlighting are supported everywhere that matters, but the language identifiers aren't standardized. Use javascript, python, sql, bash, json, html, css — these work on every major platform. More obscure languages may require different identifiers depending on the highlighter (Prism.js, highlight.js, Rouge, etc.).

Writing Better Markdown Documents

Good Markdown documents follow a consistent structure: a single H1 title, H2 sections for major topics, H3 for subtopics, and no skipped heading levels. This isn't just stylistic — screen readers and table-of-contents generators rely on heading hierarchy to navigate the document. Skipping from H1 to H3 breaks accessibility and confuses automated tooling.

For long documents, add a table of contents manually using Markdown links: [Section Name](#section-name). The anchor is the heading text lowercased, with spaces replaced by hyphens and special characters removed. Some platforms generate tables of contents automatically from headings, but a manual TOC at the top of a long README is universally supported and saves readers time. The Markdown Preview tool renders your document in real time, so you can verify that heading links and formatting work correctly before publishing.

```mermaid
flowchart TD
    A[Start] --> B{Is it working?}
    B -- Yes --> C[Deploy]
    B -- No --> D[Debug]
    D --> A
```