MarkdownViewer

Markdown Link Syntax: How to Add Links

Links are the connective tissue of any document — pointing readers to sources, related pages and other sections. Markdown gives you several ways to write them, from a quick inline link to reusable reference definitions and internal anchor links. This guide covers each form and the details, like titles and escaping, that keep links working.

Inline links (the common form)

The basic form is square brackets for the text and parentheses for the URL. This is what you will use most of the time: it keeps the link text and destination together and needs no second step.

  1. [link text](https://example.com)
  2. [link text](https://example.com "Hover title")

Reference-style links

When the same URL appears many times, or when a long URL would clutter the paragraph, use a reference link. The text refers to a label, and the label's definition sits elsewhere — usually at the bottom of the document. This keeps the prose readable and lets you change a URL in one place.

  1. See the [documentation][docs] for details.
  2. Then, later in the file:
  3. [docs]: https://example.com/docs

Automatic links

GitHub-flavoured Markdown auto-links bare URLs wrapped in angle brackets, and often links plain URLs with no markup at all. For maximum portability, the angle-bracket form is the safer choice because not every renderer auto-links bare text.

  1. <https://example.com>

Linking to a section (anchor links)

To link to a heading within the same document, use the heading's anchor in the URL. Anchors are usually the heading text lowercased, with punctuation removed and spaces replaced by hyphens. So a heading 'Getting Started' becomes #getting-started. This is how a table of contents links to its sections.

  1. [Jump to Usage](#usage)
  2. [Jump to Install](#installation)

Email links

An email address in angle brackets becomes a mailto link. This is convenient for a contact line, though be aware that plain-text email addresses attract spam; on a public page a contact form is usually better.

  1. <[email protected]>

Mistakes that break links

  1. Missing parentheses or brackets, leaving the syntax visible as text
  2. Spaces inside the URL — URLs must not contain literal spaces; use %20 instead
  3. Unclosed brackets in the link text, which swallows the rest of the line
  4. Anchor links whose slug does not match the heading's auto-generated anchor
  5. Reference definitions with a typo in the label, so the link resolves to nothing

Frequently Asked Questions

How do I make a link open in a new tab?
Standard Markdown has no target attribute, so links open in the same tab. Opening in a new tab requires raw HTML with target="_blank", which many renderers pass through. On GitHub, for example, external links in READMEs open in the same tab by design.
What is the difference between inline and reference links?
Inline links put the URL right in the sentence; reference links put a short label there and define the URL elsewhere. Reference links keep prose tidy and make URL updates a one-line change, which is why long documents often prefer them.
Why does my anchor link not jump to the heading?
The anchor must match the renderer's auto-generated slug for that heading — usually lowercased, punctuation removed, spaces turned into hyphens. If the heading has odd punctuation or symbols, check the slug the renderer actually produced, or simplify the heading.
Can I use Markdown links in my page's Markdown?
Yes. Links are core Markdown and render everywhere. Preview the document first to confirm each link resolves and reads well in context before publishing.

Related Markdown Tools

Markdown ViewerMarkdown TOC GeneratorMarkdown Cheat SheetAll Markdown Tools