How to Create Links in Markdown
Create a link in Markdown by putting the link text in square brackets followed immediately by the URL in parentheses: [link text](https://example.com). No space is allowed between the closing bracket and the opening parenthesis.
Platform Support
The inline form covers most needs, and it accepts an optional title in quotes after the URL — [docs](https://example.com "Opens the documentation") — which browsers show as a hover tooltip. Write meaningful link text: "see the install guide" beats "click here" for both readers and search engines. Links can carry emphasis too: **[bold link](https://example.com)** works by wrapping the entire link in the bold markers.
URLs containing parentheses are the classic breakage. A Wikipedia URL like https://en.wikipedia.org/wiki/Markdown_(language) ends the link at the first closing parenthesis, leaving "(language)" as stray text. Fix it by percent-encoding the parentheses (%28 and %29), escaping them with backslashes, or wrapping the URL in angle brackets: [Markdown](<https://en.wikipedia.org/wiki/Markdown_(language)>). Spaces in URLs must always be encoded as %20.
Reference links separate the URL from the prose: write [link text][ref] in the sentence and define [ref]: https://example.com anywhere else in the document (conventionally at the bottom). This keeps long paragraphs readable in source form and lets you reuse one URL many times — change the definition once and every reference updates. The shortcut form [ref] with a matching definition also works, using the reference name as the link text. Autolinks are the third form: wrap a bare URL in angle brackets (<https://example.com>) to make it clickable. GFM additionally auto-links bare URLs without brackets, but plain CommonMark does not, so angle brackets are the safe choice.
In repositories and wikis, prefer relative links for internal targets: [contributing guide](docs/CONTRIBUTING.md) survives forks, renames of the host domain, and branch switches, where an absolute github.com URL would silently point at the wrong fork. You can also link to heading anchors within a page using [section](#section-name) — see the headings reference for how anchor IDs are generated.
Examples
[Link text](https://example.com)Create a clickable link with custom text.
[Link text](https://example.com "Title on hover")Add a tooltip title that appears on hover.
[Link text][ref]
[ref]: https://example.comDefine links separately for cleaner text.
<https://example.com>Automatically convert URLs to clickable links.
[Markdown on Wikipedia](https://en.wikipedia.org/wiki/Markdown_%28language%29)Percent-encode parentheses as %28 and %29, or wrap the URL in angle brackets.
Read the [contributing guide](docs/CONTRIBUTING.md) before opening a PR.Read the contributing guide before opening a PR.
Relative links keep working in forks and on different branches.
Jump to [Installation](#installation)Jump to Installation
Common Mistakes
[link text] (https://example.com)[link text](https://example.com)A space between the closing bracket and opening parenthesis breaks the link — the parser sees plain bracketed text followed by parenthesized text.
[wiki](https://en.wikipedia.org/wiki/Markdown_(language))[wiki](https://en.wikipedia.org/wiki/Markdown_%28language%29)An unescaped closing parenthesis in the URL ends the link early. Percent-encode parentheses or wrap the URL in angle brackets.
(https://example.com)[link text][link text](https://example.com)The order is brackets first, then parentheses. Reversing them renders both parts as literal text.
Platform Notes
GitHub
Full support for all link forms, plus auto-linking of bare URLs, issue references (#123), and commit SHAs. Relative links resolve against the current branch.
Discord
Inline [text](url) links work in messages (and embeds). Wrap a URL in <angle brackets> to suppress the embed preview.
Slack
Standard Markdown links do not work in regular messages — Slack uses its own link UI (paste a URL, or use Cmd/Ctrl+Shift+U). Bare URLs auto-link.
Obsidian
Supports standard links plus [[wikilinks]] for internal notes. Spaces in file paths must be encoded as %20 in standard-style links.
Frequently Asked Questions
How do I create a hyperlink in Markdown?
Put the link text in square brackets immediately followed by the URL in parentheses: [link text](https://example.com).
How do I make a link open in a new tab?
Standard Markdown has no syntax for link targets. If the renderer allows raw HTML, use <a href="..." target="_blank" rel="noopener">text</a>; otherwise it is controlled by the platform.
Why does my link break when the URL has parentheses?
The first closing parenthesis in the URL ends the link. Percent-encode parentheses as %28 and %29, backslash-escape them, or wrap the whole URL in angle brackets.
What is a reference link?
A two-part link: [text][label] in the prose and [label]: https://example.com defined elsewhere. It keeps source text readable and lets you reuse the same URL in many places.
How do I link to another section of the same page?
Use the heading anchor: [Install](#installation). GitHub generates anchors by lowercasing heading text, replacing spaces with hyphens, and stripping punctuation.