Markdown Link Syntax
The complete guide to writing links in Markdown. Inline syntax, reference links, autolinks, relative paths, and the five most common mistakes that break them.
Basic Syntax
A Markdown link has two parts: the visible text in square brackets, and the URL in parentheses. The two parts must touch directly (no space between ] and ().
[Visit MarkdownFormatting](https://markdownformatting.com)Link Titles
Add a title in double quotes after the URL. It is shown as a tooltip when the reader hovers over the link. Not all platforms render it, but it is valid in CommonMark.
[Visit MarkdownFormatting](https://markdownformatting.com "A free Markdown reference")Reference Links
Reference links split the link text and the URL so the paragraph stays readable. Use [text][id] inline, then define [id]: url on its own line later in the document. The identifier can be a number, a word, or a combination.
See the [Markdown style guide][1] and [our homepage][home].
[1]: https://markdownformatting.com/cheat-sheet
[home]: https://markdownformatting.com "Markdown formatting made easy"See the Markdown style guide and our homepage.
Autolinks
When you want the URL itself to be the clickable text, wrap it in angle brackets. This is the standard way to render a bare URL as a link in Markdown. Many platforms also auto-link plain URLs, but the angle brackets guarantee it.
<https://markdownformatting.com>
<contact@example.com>Relative Links
Markdown supports relative URLs the same way HTML does. Use them for cross-references within the same project, website, or repository. The path is resolved relative to the file containing the link.
[Read more](/blog)
[Installation guide](./install.md)
[Parent directory](../readme.md)Common Mistakes
The five most common reasons a Markdown link fails to render. Each row shows the broken version and the corrected one side by side.
Broken
[Visit MarkdownFormatting](markdownformatting.com)Fixed
[Visit MarkdownFormatting](https://markdownformatting.com)Broken
[Visit MarkdownFormatting] (https://markdownformatting.com)Fixed
[Visit MarkdownFormatting](https://markdownformatting.com)Broken
[Visit MarkdownFormatting](https://markdownformatting.comFixed
[Visit MarkdownFormatting](https://markdownformatting.com)Broken
[See docs](https://example.com/intro to docs)Fixed
[See docs](https://example.com/intro%20to%20docs)Broken
[Reference Link][1]
[1] https://markdownformatting.comFixed
[Reference Link][1]
[1]: https://markdownformatting.comQuick Reference
| Syntax | What it does |
|---|---|
| [text](https://url) | Inline link with clickable text |
| [text](url "title") | Inline link with a tooltip |
| [text][id] | Reference link marker |
| [id]: url "title" | Reference link definition |
| <https://url> | Autolink: URL as clickable text |
| <email@example.com> | Autolink: email as mailto link |
| [text](./file.md) | Relative link to a file in the same directory |
| [](url) | Image that acts as a link |
Platform Support
Links are core Markdown syntax, so they work almost everywhere. Platform-specific notes cover relative-path resolution, tooltip support, and auto-unfurling behavior.
| Platform | Supported? | Notes |
|---|---|---|
| GitHub | Yes | Full support. Relative links resolve to the repository. Link titles render as tooltips. |
| GitLab | Yes | Same as GitHub. Relative links resolve within the repository. |
| Reddit (new) | Yes | Link syntax and autolinks work. Link titles are ignored. |
| Reddit (old) | Partial | Basic links and autolinks work. Link titles are not shown. |
| Discord | Yes | Basic links work. Discord also auto-embeds bare URLs. Link titles are ignored. |
| Slack | Yes | Link syntax works. Slack auto-unfurls and previews many URLs. Link titles are ignored. |
| Notion | Yes | Links paste and convert to Notion's native link format. Reference links work on import. |
| Obsidian | Yes | Relative links use vault-relative paths. Wikilinks ([[Page]]) are preferred internally. |
| VS Code preview | Yes | Renders inline links, reference links, and autolinks. Link titles show as tooltips. |
| Standard Markdown / CommonMark | Yes | Inline links, reference links, and autolinks are all core syntax. |
| Docusaurus / VitePress / Astro | Yes | Full support. Relative links resolve according to the site's routing config. |
Frequently Asked Questions
How do you create a link in Markdown?
Write the link text in square brackets, followed by the URL in parentheses: [Link text](https://example.com). The text between brackets is what the reader sees. The URL between parentheses is where they go when clicked.
Can you add a hover tooltip to a Markdown link?
Yes. Add a title in double quotes after the URL: [text](https://example.com "Tooltip here"). The title is shown when the reader hovers over the link. Not all platforms display it (Discord, Reddit, and Slack do not).
What is a reference link in Markdown?
A reference link splits the link into two parts: a marker [text][id] placed inline, and a definition [id]: url placed elsewhere in the document (usually at the bottom). This keeps the paragraph readable when the URL is long. The id can be a number or a word like [docs].
Does Markdown support automatic link detection?
Not automatically for bare URLs in plain text. To force a URL to render as a link, wrap it in angle brackets: <https://example.com>. This is called an autolink. Many platforms (GitHub, Discord, Slack) also auto-link plain URLs, but standard Markdown does not.
Can you use relative links in Markdown?
Yes. Markdown supports relative URLs: [About](/about) links to the root, [Install](./install.md) links to a file in the same directory, and [Go up](../readme.md) links to the parent directory. The target is resolved relative to the file containing the link. This is how GitHub, Obsidian, and most static-site generators handle cross-references.
Why is my Markdown link rendering as plain text?
The five most common causes are: (1) the URL is missing a protocol (use https://, not just example.com), (2) there is a space between ] and ( in the inline syntax, (3) the closing parenthesis is missing, (4) the URL contains spaces that are not percent-encoded, or (5) in a reference-style link, the definition is missing the colon after the identifier ([1]: url instead of [1] url).
Do Markdown links open in a new tab?
No. Markdown does not have syntax for target="_blank" or rel="noopener". If you need a new-tab link, use raw HTML: <a href="url" target="_blank" rel="noopener noreferrer">text</a>. Most static-site generators and platforms like GitHub strip target attributes for security, so the link behavior is controlled by the platform, not the Markdown author.
How do you create an email link in Markdown?
Wrap the email address in angle brackets: <contact@example.com>. Most renderers treat it as a mailto link. Some platforms obscure it to prevent scraping. You can also use the inline syntax: [Email us](mailto:contact@example.com).
Can I put an image inside a link?
Yes. Replace the link text with the Markdown image syntax: [](https://example.com). The image renders as the clickable link body. This works on GitHub, GitLab, and most static-site generators.
Are reference links supported on GitHub?
Yes. GitHub fully supports reference-style links. The definition can be anywhere in the document, but it is conventional to place it at the bottom. GitHub also resolves relative reference links to files in the same repository.
Related Markdown Guides
Links are core Markdown syntax. For the rest of the syntax surface area: