Markdown Links: Internal, External, Anchors & Reference-Style

Links are how Markdown becomes the web. The basic syntax is two characters away from a working hyperlink — but if you want anchor links, reference-style organization, or links that open in a new tab, you'll need a few more tricks.

This guide covers every kind of link you'll ever need to write in Markdown, with examples and a reference card at the bottom.

The basic Markdown link

The standard inline link syntax:

[Link text](https://example.com)

Two parts:

• [Link text] — the visible, clickable text.
• (URL) — the destination, in parentheses.

Example:

Visit [Markdown Viewer](https://trymarkdownviewer.com) to try it.

You can also add a tooltip (shown on hover):

[Markdown Viewer](https://trymarkdownviewer.com "Free online Markdown editor")

The tooltip is plain HTML title and works in every browser.

Automatic links

If you have a bare URL, Markdown can auto-link it for you. Two ways:

<https://trymarkdownviewer.com>

The angle-bracket form is the CommonMark autolink — works in every renderer.

Visit https://trymarkdownviewer.com to try it.

The bare-URL form requires GFM autolinks — supported by GitHub, GitLab, and most modern renderers. Don't rely on it for portable documents.

Internal links — linking inside the same document

To link to a heading on the same page, use a hash followed by the heading's auto-generated ID:

[Jump to installation](#installation)

## Installation

…

GitHub-style renderers automatically generate IDs from heading text by:

1. Lowercasing everything
2. Replacing spaces with hyphens
3. Removing punctuation

So ## Installation guide becomes #installation-guide. If two headings share the same slug, the renderer adds -1, -2, and so on.

Some renderers (Pandoc, MkDocs Material) let you customize the heading ID:

## Installation {#install}

[Jump to install](#install)

Markdown Viewer's preview supports this slug pattern out of the box — try it in the editor.

Linking to other Markdown files

For a multi-file project (a docs site, a multi-page README), use relative paths:

See [the contributing guide](./CONTRIBUTING.md) for details.

Or to link to a specific heading in another file:

See [the installation steps](./SETUP.md#installation).

Two things to know:

• Some renderers (GitHub) automatically rewrite .md paths to the rendered HTML route. Others (Pandoc, static site generators) keep them as-is and you need to write the rendered path yourself.
• Linking with a leading slash (/CONTRIBUTING.md) is absolute — it starts at the repo root. Without the slash, it's relative to the current file.

Reference-style links

Inline links clutter prose when you have many. Reference-style links separate the URL from the text:

You can edit Markdown in the [browser][editor], read the [docs][guide], or
clone the [GitHub repo][repo].

[editor]: https://trymarkdownviewer.com/editor
[guide]: https://trymarkdownviewer.com/guide
[repo]: https://github.com/saifurrahmanshochib/markdown-viewer

The label inside the second set of brackets matches the definition at the bottom of the document. Labels are case-insensitive.

You can also omit the label and use the text itself:

Try [Markdown Viewer]!

[Markdown Viewer]: https://trymarkdownviewer.com

Reference-style is great when:

• You reuse the same link multiple times.
• You're writing a long article and want the prose to stay readable.
• You're collaborating and reviewers want to see what URLs were added at a glance.

Link titles (tooltips)

Both inline and reference-style links accept an optional title:

[Markdown Viewer](https://trymarkdownviewer.com "A free online editor")

[Markdown Viewer][mv]

[mv]: https://trymarkdownviewer.com "A free online editor"

The title is shown in a browser tooltip. It's also useful for accessibility tools that announce it as additional context.

Open links in a new tab

Pure Markdown doesn't support this. The standard solution is HTML:

<a href="https://example.com" target="_blank" rel="noopener noreferrer">
  Open in new tab
</a>

Always include rel="noopener noreferrer" for external links:

• noopener — prevents the new page from getting access to your page via window.opener (a security and performance issue).
• noreferrer — prevents the Referer header from being sent.

Some renderers (including Markdown Viewer) automatically add these attributes to external links — check the editor preview for the live behavior.

Email and phone links

Markdown supports email autolinks:

<mailto:hello@example.com>

Or the inline form:

[Send us an email](mailto:hello@example.com)

You can also pre-fill the subject and body:

[Email us](mailto:hello@example.com?subject=Hello&body=Hi%20there)

Phone numbers use tel::

[Call us](tel:+15551234567)

Anchor links to specific text (text fragments)

A relatively new browser feature lets you link to specific text on a page using a URL text fragment:

[Jump to "installation"](https://docs.example.com#:~:text=installation)

The browser scrolls to and highlights the matching text. Works in Chrome, Edge, and Safari (Firefox is catching up). It's a great pattern for documentation links.

Footnote links (GFM)

When you want a small link in the prose with a longer note at the bottom, use footnotes:

Markdown was created in 2004[^1].

[^1]: By John Gruber and Aaron Swartz.

Footnotes are GFM and work in GitHub, Markdown Viewer, and most modern renderers.

Links inside images (and vice versa)

You can wrap an image in a link:

[![Alt text](/logo.png)](https://example.com)

Result: clickable image. This is how every GitHub README badge works.

You can't put a link inside the alt text of an image — the alt text is plain string, not Markdown.

Linking to a specific line of code on GitHub

GitHub generates anchors for line numbers. Click any line in a file view and the URL becomes:

https://github.com/user/repo/blob/main/src/index.ts#L42

You can also link to a range with #L42-L57. These deep links are gold for code reviews and bug reports.

URL encoding for special characters

URLs with spaces, parentheses, or special characters need to be encoded. The most common one:

• Space → %20
• ( → %28
• ) → %29

[Search results](https://example.com/search?q=markdown%20editor)

Most editors handle this automatically when you paste a URL. If you're writing by hand, run the URL through encodeURIComponent once.

SEO best practices for Markdown links

Search engines treat Markdown links the same as HTML <a> tags after rendering. To boost SEO:

1. Use descriptive anchor text. "Click here" is meaningless — "the Markdown table guide" is searchable.
2. Link to canonical URLs. Avoid linking to redirects or query-laden URLs when a clean canonical exists.
3. Avoid cloaking. Don't make the link text say one thing and link somewhere unrelated.
4. Use nofollow for untrusted content. User-generated links (comments, forums) should get rel="nofollow".
5. Don't open every external link in a new tab. It's anti-UX. Reserve new tabs for contexts where leaving would lose state (forms, half-finished work).

Common Markdown link mistakes

1. Forgetting the parentheses. [text]url isn't a link — it's text followed by text.

2. Spaces between the brackets and parens. [text] (url) doesn't work in strict CommonMark. Always: [text](url).

3. Reversed syntax. Some users remember it as (text)[url] (the bracket order is wrong). Markdown uses [text](url) — same order as a function call.

4. Unencoded URLs. A space in the URL breaks the link.

5. Heading anchor case mismatch. #Installation won't find a heading rendered as #installation. Lowercase the slug.

6. Linking with the heading text instead of the slug. [Jump](#My Heading) doesn't work — use [Jump](#my-heading).

Link best practices

• One purpose per link. Don't pack two destinations into one anchor.
• Open in same tab by default. Users know how to middle-click.
• Front-load the keyword. "Read the [installation guide]" reads better than "click [here] for installation".
• Don't end sentences with links. It's harder to scan visually.
• Validate links periodically. Use Markdown Viewer's link checker — open the Links tab in the sidebar and click Check.

Try it now

Open the Markdown editor and try each style of link. The toolbar's link button (Ctrl/⌘ + K) inserts the [text](url) skeleton and selects the URL portion so you can paste immediately.

Related articles

• Markdown cheat sheet — every Markdown feature on a single page
• How to add images in Markdown — alt text, sizing, hosting
• Markdown syntax guide — CommonMark and GFM, end to end

Quick reference

[Inline](url)                     Inline link
[Inline](url "Title")             With tooltip
[Reference][label]                Reference-style
[label]: url "Title"              Reference definition
<https://example.com>             Autolink (CommonMark)
[Jump](#heading-slug)             Internal anchor
[Doc](./other.md#section)         Cross-file link
[Email](mailto:hi@example.com)    Email link
[Call](tel:+15551234567)          Phone link
[![alt](img.png)](url)            Clickable image
[^1]                              Footnote ref
[^1]: Footnote text               Footnote definition

The link is the smallest unit of the web — and Markdown gives you eight different ways to write one.