Markdown Links: Every Way to Add a Link
By the MDConverter team · Updated · 3 min read
Quick answer
A Markdown link is the link text in square brackets followed immediately by the URL in parentheses: [MDConverter](https://mdconverter.net). Add a title in quotes after the URL for a hover tooltip, use #heading-name to link to a section, or a relative path such as docs/setup.md to link to another file. Markdown cannot open links in a new tab on its own — that needs HTML (<a target="_blank">) or a renderer setting.
Inline links
The most common form. No space is allowed between ] and (.
Read the [CommonMark spec](https://spec.commonmark.org).
Hover for a [tooltip](https://commonmark.org "CommonMark home page").Read the CommonMark spec.
Hover for a tooltip.
Automatic links and email addresses
Wrap a URL or email address in angle brackets to make it clickable as-is. GitHub and most GFM renderers also link bare URLs that start with https:// or www. automatically.
<https://mdconverter.net>
<hello@mdconverter.com>
https://www.example.com is linked automatically in GFM.https://www.example.com is linked automatically in GFM.
[Email us](mailto:hello@mdconverter.com).Reference-style links
Put a short label in the text and define the URL elsewhere — usually at the bottom of the document. The definitions never appear in the output. Useful for long URLs and for links you repeat.
Compare [CommonMark][cm] with [GitHub Flavored Markdown][gfm].
Both build on [the original Markdown].
[cm]: https://commonmark.org
[gfm]: https://github.github.com/gfm/ "GFM spec"
[the original Markdown]: https://daringfireball.net/projects/markdown/Compare CommonMark with GitHub Flavored Markdown. Both build on the original Markdown.
Linking to a heading on the same page
Use # plus the heading's anchor: lowercase, spaces replaced by hyphens, punctuation removed. ## Install & Setup becomes #install--setup. The rules are covered in detail in Markdown headings.
Jump to [Installation](#installation) or the [FAQ](#faq).Jump to Installation or the FAQ.
Linking to other files (relative links)
In a repository or docs site, link to other Markdown files with a relative path so the link keeps working on forks, branches and local clones:
[Setup guide](docs/setup.md)— a file in a sub-folder[Changelog](../CHANGELOG.md)— one folder up[Install section](docs/setup.md#install)— a heading in another file- On GitHub, a path starting with
/is relative to the repository root.
If a path contains spaces, wrap it in angle brackets — [Notes](<my notes/todo.md>) — or encode the spaces as %20.
Opening a link in a new tab
Standard Markdown has no syntax for this. Your options:
- HTML, where it is allowed:
<a href="https://example.com" target="_blank" rel="noopener">Example</a>. GitHub removes thetargetattribute, so it has no effect there. - Attribute lists in renderers that support them (Kramdown, Pandoc, MkDocs with attr_list):
[Example](https://example.com){:target="_blank"}. - Site settings — many static site generators and themes can open all external links in a new tab.
Linked images and links with formatting
Link text can contain formatting, and an image can be wrapped in a link — the pattern behind every README badge.
[**Bold link text**](https://example.com)
[](https://mdconverter.net)
Links when converting to and from Markdown
Markdown to Word turns links into real clickable hyperlinks, and Markdown to PDF keeps them clickable in the PDF. In the other direction, HTML to Markdown and Word to Markdown convert hyperlinks to [text](url) syntax. For plain text, the plain-text converter lets you keep links as “text (URL)” or text only.
Link support by app
| App | Supported | Notes |
|---|---|---|
| GitHub / GitLab | Yes | Inline, reference, autolinks, relative links; target is stripped. |
| Obsidian | Yes | Markdown links plus [[wiki links]] between notes. |
| Discord | Yes | Masked links [text](url) in messages; a confirmation dialog appears before opening. |
| Slack | Partly | Pasted [text](url) is not converted; Slack’s own format is <url|text> (see Markdown to Slack). |
| Yes | Inline links in Markdown mode. | |
| Notion | Yes | Typing or pasting [text](url) creates a link. |
Common mistakes and how to fix them
| Problem | Fix |
|---|---|
Link shows as [text] (url) | Remove the space between ] and (. |
| URL with parentheses breaks the link | Encode them as %28 and %29, or wrap the URL in <…>. |
| Relative link works locally but 404s on the site | Static site generators often need the built URL (/docs/setup/) instead of the file name. Check your generator’s docs. |
| Section link does nothing | The anchor must match the heading’s generated ID exactly — lowercase, hyphens, no punctuation. |
Tools for this
Frequently Asked Questions About Links
Comprehensive answers to common technical, formatting, security, and compatibility questions.
Related reading
- Markdown Headings: Syntax, Levels and Linking to a Heading — Heading levels, the setext alternative, anchor links and the mistakes that break headings.
- Markdown Images: Insert, Resize, Center and Caption — Insert images, set their size, center them, add captions and fix images that do not show.
- How to Add Footnotes in Markdown — Add numbered notes with [^1], write long notes, and know where footnotes are supported.