A Markdown link is square brackets for the text and parentheses for the destination, in that order. Once you have that, the rest is variations on where you put the destination — inline, in a reference at the bottom, or nowhere at all when the URL speaks for itself.
An [inline link](https://inkiostro.app) is the common one.
A [link with a title](https://inkiostro.app "Hover me") shows a tooltip.
A [reference link][site] keeps the paragraph readable.
A bare URL like https://inkiostro.app is auto-linked.
[site]: https://inkiostro.appAn inline link is the common one.
A link with a title shows a tooltip.
A reference link keeps the paragraph readable.
A bare URL like https://inkiostro.app is auto-linked.
Inline links
[Inkiostro](https://inkiostro.app)The text in brackets is what the reader sees and click. Write it so it makes sense out of context: “the guide to tables” tells you where you are going, “click here” does not. Screen reader users often navigate by jumping between links, and a page full of “here” is unusable.
Titles
A quoted string after the URL becomes the title attribute, shown as a tooltip on hover:
[Inkiostro](https://inkiostro.app "A Markdown editor for Mac, iPad and iPhone")Use it sparingly. Tooltips do not appear on touch devices, so a title must never carry information the reader needs.
Reference links
When a paragraph has several links, inline URLs make the source unreadable. Reference style moves them out of the way:
Read the [complete guide][guide], the [notes on tables][tables]
and the [notes on lists][lists].
[guide]: /markdown-guide
[tables]: /markdown-tables
[lists]: /markdown-listsRead the complete guide, the notes on tables and the notes on lists.
The definitions can sit anywhere in the document — the bottom is conventional. Labels are case-insensitive and never appear in the output.
If the link text is the label, you can leave the second pair of brackets empty:
Read the [markdown guide][] for the whole picture.
[markdown guide]: /markdown-guideRead the markdown guide for the whole picture.
Reference links pay off twice: the prose stays legible, and a URL used ten times is defined once.
Anchor links
Link to a heading in the same document with # and the heading’s generated id — lowercase, spaces to hyphens, punctuation dropped:
Jump to [reference links](#reference-links).Jump to reference links.
Across documents, combine the two: [tables](/markdown-tables#alignment). See headings for how the ids are generated.
Automatic links
Most renderers turn a bare URL into a link. Angle brackets make it explicit and work even where auto-linking is off:
<https://inkiostro.app>
<carlo@appjuice.it>An email address in angle brackets becomes a mailto: link.
Relative links
Inside a site or a repository, link by path rather than by full URL:
[The lists guide](/markdown-lists)
[A file next to this one](./CONTRIBUTING.md)Relative links survive a change of domain and work offline. Prefer them for anything inside your own project.
Common mistakes
Brackets and parentheses the wrong way round. (text)[url] renders as literal text. Square brackets first, always.
A space between them. [text] (url) breaks the link. They must touch.
Spaces inside the URL. Wrap the URL in angle brackets — [file](<my file.pdf>) — or percent-encode the space as %20.
Parentheses inside the URL. Common with Wikipedia. Escape them as \( and \), or use a reference link, which has no such problem.
“Click here” as link text. Bad for accessibility, bad for search engines, and useless in a list of links.
FAQ
How do I create a link in Markdown?
Put the visible text in square brackets and the destination in parentheses right after, with no space between them: [Inkiostro](https://inkiostro.app).
What is a reference link in Markdown?
A link whose destination is defined elsewhere in the document. You write [text][label] in the prose and [label]: https://example.com on its own line, usually at the bottom. It keeps paragraphs readable and lets one URL serve many links.
How do I link to a section of the same page?
Link to the heading’s anchor with #: [jump](#my-section). The anchor is the heading text lowercased, with spaces turned into hyphens and punctuation removed.
How do I handle a URL with spaces or parentheses?
Wrap the URL in angle brackets — [text](<my file.pdf>) — or percent-encode the characters, %20 for a space. For parentheses you can also escape them with a backslash or switch to a reference link.
Can I make a link open in a new tab in Markdown?
Not in standard Markdown, which has no way to express target. You would need raw HTML, which costs portability. Most renderers deliberately leave the choice to the reader.