Inline links
The everyday form. An optional title in quotes after the URL becomes hover text.
[MDTool](https://www.mdtool.dev)
[MDTool](https://www.mdtool.dev "Free Markdown converter")Reference-style links
For documents that repeat the same URL, define it once at the bottom and reference it by label. This keeps paragraphs readable in the raw source.
See the [documentation][docs] for details.
[docs]: https://www.mdtool.dev/markdown-cheat-sheetAutomatic links and section anchors
GFM automatically links bare URLs like https://example.com. To link to a heading on the same page, use its generated anchor: lowercase, spaces replaced with hyphens.
<https://example.com>
[Jump to setup](#getting-started)URLs with spaces
A space ends the URL in an inline link, so "[Report](my report.pdf)" breaks. Either encode each space as %20, or wrap the whole destination in angle brackets, which CommonMark and GitHub allow precisely for this case.
[Report](my%20report.pdf)
[Report](<my report.pdf>)
[Spec](<docs/Design Notes.md>)Linking to headings and anchors
GitHub builds a heading’s anchor by lowercasing the text, removing formatting, deleting punctuation, and replacing each space with a hyphen. When two headings produce the same anchor, the second gets -1, the third -2, and so on. To link to a heading in another file, add the anchor after the file path.
| Heading | Anchor link |
|---|---|
| ## Getting Started | #getting-started |
| ## What’s New in v2.0? | #whats-new-in-v20 |
| ## C++ & Rust | #c--rust |
| ## **Bold** Heading | #bold-heading |
| A second "## Setup" heading | #setup-1 |
[Jump to the FAQ](#frequently-asked-questions)
[Install steps](docs/setup.md#installation)Ampersands, parentheses and special characters in URLs
Query strings with & work as-is inside a Markdown link. You do not need to write &. Parentheses are fine when balanced, which matters for Wikipedia-style URLs; an unbalanced one must be escaped with a backslash or encoded as %28 or %29. An unbalanced square bracket inside the link text needs escaping too.
[Search](https://example.com/search?q=markdown&page=2)
[Wiki](https://en.wikipedia.org/wiki/Mercury_(planet))
[Odd URL](https://example.com/a%29b)
[Read the \[draft notes](notes.md)Collapsed and shortcut reference links
Reference links have two shorter forms. With empty brackets, or none at all, the link text doubles as the label. Labels are case-insensitive, and a definition can carry a title just like an inline link.
Convert files with [MDTool][] or read the [cheat sheet].
[mdtool]: https://www.mdtool.dev "Free Markdown converter"
[cheat sheet]: https://www.mdtool.dev/markdown-cheat-sheetFrequently Asked Questions
How do I open a Markdown link in a new tab?
Pure Markdown has no syntax for that. Use inline HTML instead: <a href="https://example.com" target="_blank" rel="noopener">text</a>. Note that GitHub strips target attributes in READMEs.
How do I put a space in a Markdown link URL?
Replace each space with %20, or wrap the URL in angle brackets: [Report](<my report.pdf>). A plain space ends the URL and breaks the link.
How do I link to a heading in another Markdown file?
Add the heading’s anchor after the file path: [Install](docs/setup.md#installation). On GitHub the anchor is the heading text in lowercase, with punctuation removed and spaces turned into hyphens.
Try it live
Paste this syntax into the free html to markdown converter and see the rendered output instantly. No signup, and everything runs in your browser.
Open HTML to Markdown Converter →