How do you add a hyperlink in markdown?

Use square brackets for the link text and parentheses for the URL: [link text](https://example.com). The text in brackets is what the user sees; the URL in parentheses is where they go.

How do you open a markdown link in a new tab?

Standard markdown has no syntax for target="_blank". Use raw HTML instead: Link text . This works on GitHub, GitLab, and any platform that allows HTML.

What is a reference-style link in markdown?

A reference-style link separates the URL from the prose: [link text][label] in the body, and [label]: https://example.com defined elsewhere. This keeps long URLs out of your text for cleaner source code.

Why is my markdown link not working?

The most common causes are: a space between ] and ( (write [text](url) not [text] (url)), missing protocol (use https://example.com not just example.com), or special characters in the URL that need percent-encoding.

How do you link to a heading in the same markdown document?

Use the heading as an anchor: [Section Name](#section-name). The anchor ID is the heading text lowercased with spaces replaced by hyphens and special characters removed.

How to Add a Link in Markdown

The quick answer: Use square brackets for the link text and parentheses for the URL — link text. This is the standard inline link syntax that works on GitHub, Notion, Obsidian, Discord, and all CommonMark renderers.

Basic Inline Link Syntax

Visit MarkdownTools

The structure is always the same: [visible text](URL). The text in [ ] is what renders as the clickable link. The URL in ( ) is the destination.

You can link to any URL: pages, images, anchors, mailto addresses:

Home — external URL
[Contact](mailto:hello@example.com) — email link
[Section](#section-title) — anchor link within the same document
[README](./README.md) — relative link to another file

Adding a Title Tooltip

Add a quoted title after the URL to show a tooltip on hover: MarkdownTools

Single or double quotes work for the title. The title renders as the HTML title attribute — visible when users hover the link.

Auto-Links (Bare URLs)

Wrap a URL in angle brackets to auto-link it without creating separate link text:

This renders the URL itself as a clickable link. GitHub also auto-links bare https:// URLs without angle brackets, but wrapping in <> is more portable.

Email auto-links work the same way:

Reference-Style Links

For long documents with many links, reference-style links keep prose clean: Here is a guide to [markdown][mdt-guide] and [MarkdownTools][mdt].

Then define all references at the bottom of the document: [mdt-guide]: https://allmarkdowntools.com/blog [mdt]: https://allmarkdowntools.com

Benefits:

Easier to update URLs — change them in one place
Cleaner prose — long URLs don't interrupt reading
Reuse the same URL multiple times with one definition

Reference labels are case-insensitive and can be numbers or words.

Linking to Headings (Anchor Links)

Every heading in a markdown document generates an anchor ID automatically. Use it for internal navigation: [Go to Installation](#installation)

Anchor ID Rules

The anchor is derived from the heading text: 1. All characters lowercased 2. Spaces replaced with hyphens 3. Special characters (punctuation, brackets) removed 4. Numbers kept as-is

Examples:

## Getting Started → #getting-started
## API Reference (v2) → #api-reference-v2
## Step 1: Install → #step-1-install
## What is it? → #what-is-it

Opening Links in a New Tab

Standard markdown has no native syntax for opening links in a new tab. Use inline HTML: Link text

Always include rel="noopener noreferrer" when using target="_blank" — this is a security best practice that prevents the opened page from accessing your window's context.

Platform-by-Platform Breakdown

GitHub and GitLab

Full support for inline links, reference links, auto-links, and anchor links. GitHub auto-links bare https:// URLs. Links in README files are relative to the repository root.

Obsidian

Obsidian supports standard markdown links. It also has its own [[wiki-link]] syntax for internal note linking. Both can coexist in the same document.

Notion

Notion supports inline markdown links. When importing markdown, [text](url) converts to Notion inline links. Notion does not support reference-style links in markdown import mode.

Discord

Discord renders inline links but strips the hypertext — it shows the full URL rather than the linked text. [link text](url) will render as the URL itself, not "link text". Discord auto-links bare URLs automatically.

Slack

Slack also strips link text. [text](url) renders as the URL. Use Slack's native link format: for links with custom text in Slack messages.

Common Mistakes

Space Between ] and (

[link text] (url) — wrong: the space breaks the link syntax [link text](url) — correct: no space between ] and (

Missing Protocol

[Link](example.com) — wrong: without https:// this is treated as a relative path, not an external URL Link — correct

Unencoded Special Characters in URLs

URLs with spaces or special characters need percent-encoding: Link — wrong: space in URL Link — correct

Nested Links

Markdown doesn't support links inside links. You cannot put a link inside another link's text.

Real-World Use Cases

Technical Documentation

Links in technical docs typically reference other sections of the same document (anchor links), external API documentation, and GitHub issues or PRs. Reference-style links are preferred in long docs where URLs would clutter the prose.

AI-Generated Content

When ChatGPT or Claude generates markdown with citations, the links are usually inline style. Before exporting to PDF via MarkdownTools, verify that the URLs are real (AI sometimes generates plausible-sounding but fake URLs) and that all anchor links match actual headings in the document.

README Files

GitHub README files typically combine multiple link types: inline links for external resources, anchor links for internal navigation (Table of Contents), and image links for badges. The TOC Generator can build the anchor link TOC automatically.

Full reference: Markdown Links.

Ready to put this into practice? Paste your markdown into the free MarkdownTools PDF exporter or HTML converter — no signup required.