Markdown Link Syntax
How to write a hyperlink in Markdown: inline links, titles, reference links, autolinks, links to headings and other files, and the mistakes that leave a link as plain text.
Short answer
Put the link text in square brackets and the URL in parentheses, with nothing between them: [Link text](https://example.com). Add a tooltip with [text](url "Title"), link to a heading with [text](#heading-name), and wrap a bare URL in angle brackets, <https://example.com>, to make it clickable.
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 (). The link text can hold other formatting, such as [**bold** text](url).
[Visit MarkdownFormatting](https://markdownformatting.com)Link Titles
Add a title after the URL, separated by a space. CommonMark accepts "double", 'single', or (parentheses) around it. It becomes the link's title attribute, which browsers show as a tooltip on hover.
[Visit MarkdownFormatting](https://markdownformatting.com "A free Markdown reference")Spaces and Parentheses in URLs
A link destination cannot contain a raw space. Encode it as %20, or wrap the whole destination in angle brackets inside the parentheses. Parentheses in a URL are fine as long as they are balanced; escape a lone one as \).
[Spec with spaces](<https://example.com/my file.pdf>)
[Mercury (planet)](https://en.wikipedia.org/wiki/Mercury_(planet))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 anywhere in the document. Definitions do not render, labels are case-insensitive, and when the label matches the link text you can shorten it to [text][] or just [text].
See the [table guide][1], [our homepage][home], or the [cheat sheet].
[1]: https://markdownformatting.com/tables
[home]: https://markdownformatting.com "Markdown formatting made easy"
[cheat sheet]: https://markdownformatting.com/cheat-sheetSee the table guide, our homepage, or the cheat sheet.
Link to a Heading (Anchor Links)
Most renderers give every heading an anchor, so [text](#anchor) jumps to it. On GitHub the anchor is the heading text lowercased, with each space turned into a hyphen and other punctuation removed: ## What's New? becomes #whats-new. Add the anchor after a path to reach a section in another file.
## Installation
[Jump to Installation](#installation)
[Setup, step 2](docs/setup.md#step-2)Obsidian uses the heading text instead of a slug ([[Note#My Heading]]). The headings guide covers duplicate headings, custom anchors, and tables of contents.
Autolinks
To make the URL itself the clickable text, wrap it in angle brackets. The URL needs a scheme such as https: and cannot contain spaces. An email address in angle brackets becomes a mailto: link.
<https://markdownformatting.com>
<contact@example.com>GitHub Flavored Markdown goes further: plain URLs starting with https:// or www., and plain email addresses, link themselves without brackets. Plain CommonMark leaves them as text.
Docs live at www.example.com and https://example.com/docs.Docs live at www.example.com and https://example.com/docs.
Relative Links
Markdown supports relative URLs the same way HTML does. ./ and ../ resolve from the file that contains the link, and a leading / resolves from the site root. On GitHub, / means the repository root, and relative links keep working in forks and clones where absolute URLs would not.
[Read more](/blog)
[Installation guide](./install.md)
[Parent directory](../readme.md)Open a Link in a New Tab
Markdown has no new-tab syntax. Where raw HTML is allowed (VS Code, Obsidian, most static-site generators), write the link as an HTML anchor. GitHub strips the target attribute, so there is no way to force a new tab in a README.
<a href="https://example.com" target="_blank" rel="noopener noreferrer">Example</a>Some generators add their own attribute syntax: kramdown (Jekyll) accepts [text](url){:target="_blank"} and Pandoc accepts [text](url){target="_blank"}.
Common Mistakes
The five most common reasons a Markdown link breaks. 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 ('title' and (title) also work) |
| [text](<url with spaces>) | Destination with spaces |
| [text][id] | Reference link marker |
| [text][] or [text] | Collapsed and shortcut reference links |
| [id]: url "title" | Reference link definition (does not render) |
| [text](#heading-name) | Link to a heading in the same file |
| [text](file.md#heading-name) | Link to a heading in another file |
| <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. The differences are in relative paths, bare-URL autolinking, and chat apps that use their own link format. See the Slack and Discord guides for their full formatting rules.
| Platform | Supported? | Notes |
|---|---|---|
| GitHub | Yes | Every form works. Relative links resolve inside the repository (/ means the repo root), bare URLs link automatically, and target="_blank" is stripped. |
| GitLab | Yes | Same core syntax. Relative links resolve inside the repository. |
| Yes | In the Markdown editor and on old.reddit.com. r/name and u/name link themselves. The Rich Text editor uses its link button instead. | |
| Discord | Partial | Inline [text](url) masked links work in messages. No reference links. Wrapping a URL in <> keeps it clickable but hides the embed preview. |
| Slack | Partial | The composer accepts [text](url) or ⌘/Ctrl+Shift+U. Slack's mrkdwn API format uses <https://url|text> instead; an app's markdown block takes [text](url). |
| Notion | Yes | Pasted [text](url) converts to a link. While typing, select text and press Cmd/Ctrl+K, or paste a URL over it. |
| Obsidian | Yes | Markdown links need %20 or <> for spaces in paths. [[Wikilinks]] are the default for links between notes. |
| VS Code preview | Yes | Renders inline, reference, and autolinks. Path completions suggest files and #heading anchors. |
| CommonMark | Yes | Inline links, reference links, and <> autolinks are core syntax. Bare-URL autolinking is a GFM extension. |
| 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 the brackets is what the reader sees, and the URL is where the link goes. There must be no space between ] and (.
How do I make a hyperlink with custom text in Markdown?
Use the inline link form and put your text in the brackets: [Read the docs](https://example.com/docs). The URL never appears on the page. To show the URL itself as the link text, wrap it in angle brackets instead: <https://example.com/docs>.
Can you add a hover tooltip to a Markdown link?
Yes. Add a title after the URL, separated by a space: [text](https://example.com "Tooltip here"). CommonMark accepts double quotes, single quotes, or parentheses around the title. The renderer outputs it as the link's title attribute; whether a tooltip appears depends on the platform.
How do I link to a heading or section in Markdown?
Link to the heading's anchor with a #: [Jump to Installation](#installation). On GitHub the anchor is the heading text lowercased, with spaces turned into hyphens and punctuation removed. To link to a section of another file, put the anchor after the path: [Setup](docs/setup.md#installation). Obsidian uses the heading text itself: [[Note#Heading]].
What is a reference link in Markdown?
A reference link splits the link into two parts: [text][id] in the paragraph, and a definition [id]: url on its own line elsewhere in the document. The definition does not render. Labels are case-insensitive, and you can shorten [text][text] to [text][] or just [text] when the label matches the link text.
Does Markdown automatically turn URLs into links?
Plain CommonMark does not. To make a bare URL clickable there, wrap it in angle brackets: <https://example.com>. GitHub Flavored Markdown adds extended autolinks, so on GitHub a plain https:// or www. URL becomes a link on its own. Discord, Slack, and Reddit also link plain URLs.
Can you use relative links in Markdown?
Yes. [Install](./install.md) links to a file in the same directory, [Up](../README.md) goes to the parent directory, and a path starting with / is resolved from the site root. On GitHub, / means the repository root, and GitHub's docs recommend relative links over absolute URLs for files in the same repository.
Why is my Markdown link rendering as plain text?
The usual causes: (1) a space between ] and (, (2) a missing closing parenthesis, (3) a space inside the URL that is not encoded as %20 or wrapped in <>, (4) a reference definition missing its colon ([1] url instead of [1]: url), or (5) the platform does not parse Markdown links in that field. A URL without https:// still renders as a link, but it points to a relative path on the current site.
How do I put spaces or parentheses in a Markdown link URL?
Replace spaces with %20, or wrap the whole destination in angle brackets: [Report](<files/annual report.pdf>). Parentheses are fine when they are balanced, as in Wikipedia URLs like .../Mercury_(planet). An unbalanced parenthesis needs escaping as \) or encoding as %29.
How do I make a Markdown link open in a new tab?
Markdown has no syntax for it. Where raw HTML is allowed, write <a href="https://example.com" target="_blank" rel="noopener noreferrer">text</a>. GitHub strips the target attribute, so a new-tab link is not possible in a README. Some generators add an attribute syntax: kramdown (Jekyll) accepts [text](url){:target="_blank"} and Pandoc accepts [text](url){target="_blank"}.
How do you create an email link in Markdown?
Wrap the address in angle brackets: <contact@example.com>. CommonMark renders it as a mailto: link. For custom text, use the inline form with a mailto: URL: [Email us](mailto:contact@example.com). On GitHub, a bare email address also links automatically.
Can I put an image inside a link?
Yes. Replace the link text with image syntax: [](https://example.com). The image becomes the clickable link body. This is how most README badges are built.