Inline links: the syntax you will use 90% of the time

The basic form is square brackets around the visible text, then parentheses around the destination:

Read the [Markdown guide](https://mdeditor.tw/markdown-guide) first.
In short
  • Square brackets hold the text, parentheses hold the URL, and no space sits between them.
  • Reference links move long or repeated URLs to the bottom of the file.
  • An anchor such as #setting-up-your-api-key is the heading text lowercased, stripped of punctuation and joined with hyphens.
  • Full-width brackets from a Chinese IME look right and render as nothing at all.

There is no space between ] and (. That single space is the most common link failure in Markdown. It does not raise an error either. You just get visible brackets in the middle of your text.

Adding a title attribute

A quoted string after the URL becomes the HTML title attribute. Browsers show it as a tooltip on hover:

[Markdown guide](https://mdeditor.tw/markdown-guide "Every element, explained")

Single quotes and parentheses work as delimiters too, but double quotes are the convention. Use titles sparingly. Tooltips are invisible on touch devices and unreliable for screen readers, so a title must never carry information the link text lacks.

Formatting inside link text

Link text accepts inline Markdown, so you can emphasise or code-format part of it. The rules are the ones in the bold and italic reference:

See the [**required** `--force` flag](https://example.com/docs/flags).

You cannot nest a link inside another link. The parser closes at the first ] it can match, which leaves a broken half-link on the page.

Illustration of square brackets holding link text connected by a chain to a pair of parentheses holding a web address

Reference-style links and when they help

Reference links separate the label from the destination. You write [text][id] in the prose, then define [id]: url elsewhere in the document:

Both the [style guide][style] and the [API reference][api]
are generated from the same source, and the [style guide][style]
is reviewed each quarter.

[style]: https://example.com/handbook/style-guide
[api]: https://example.com/developers/reference/v3/endpoints

Definitions never appear in the output. They can sit anywhere, though the bottom of the file is the convention, and the identifiers are case-insensitive.

Two shorthands, one of them risky

  • A collapsed reference, [Markdown guide][], uses the link text as the identifier.
  • A shortcut reference, [Markdown guide], drops the second bracket pair and still resolves if a definition exists.

Shortcuts are elegant but risky. Any bracketed phrase turns into a link the moment someone defines that name.

When they earn their keep

Reference links pay off in three situations:

  • The same URL appears several times and you want one place to update it.
  • The URL is long enough to wreck the raw line and make the file hard to read.
  • The file is reviewed as a diff, so a URL change touches one line at the bottom instead of a line of prose.

For a one-off link, inline is simpler. That is also why the examples in the complete Markdown guide stay inline unless a URL repeats.

Relative and absolute URLs

An absolute URL includes the scheme and the host, so it means the same thing from anywhere: https://example.com/docs/setup. A relative URL resolves against wherever the current document lives. That is both its power and its problem.

[Contributing guide](CONTRIBUTING.md)
[Setup instructions](docs/setup.md)
[Back to the root readme](../README.md)

The repo view versus the published site

Inside a GitHub repository these work perfectly. GitHub resolves the path against the file's own directory.

Trouble starts when the same files are published by a static site generator. Most generators rewrite docs/setup.md into a clean URL such as /docs/setup/, so a hand-written link to setup.md can 404 on the live site. MkDocs and Docusaurus rewrite .md targets for you, which is why their docs tell you to keep the extension. Other setups do not.

Three path rules worth memorising

  • No leading slash inside a repo. In a browser /docs/setup means the root of the domain, but a repository view may resolve it against the repository root.
  • Absolute URLs for anything shown in two places, such as a README that also appears on npmjs.com.
  • Match the case exactly. The servers hosting most static sites are case-sensitive even when your laptop is not, so Setup.md and setup.md are one file locally and two URLs in production.
Illustration of a folder tree on one side and a published website on the other, joined by two differently coloured link paths

Anchor links to headings

An anchor link jumps to a heading instead of loading a new page. The destination is a # followed by the heading's generated ID:

Jump to [installation](#installation) or [troubleshooting](#troubleshooting).

You do not create those IDs. GitHub and most renderers generate one per heading, using rules you can apply by hand. The headings reference covers the same rules from the heading side.

How a heading ID is generated: a worked example

Take this heading:

## Setting Up Your API Key (v2)

The renderer applies four steps in order:

  1. Strip the heading markers, leaving Setting Up Your API Key (v2)
  2. Lowercase everything: setting up your api key (v2)
  3. Remove punctuation that is not a letter, number, space, hyphen or underscore: setting up your api key v2
  4. Replace spaces with hyphens: setting-up-your-api-key-v2

So the link is:

[Set up your key](#setting-up-your-api-key-v2)

Duplicates, CJK headings and other renderers

  • A second heading with the same text gets -1 appended, a third gets -2.
  • CJK characters survive on GitHub, so ## 安裝步驟 becomes #安裝步驟.
  • Emoji and most symbols are removed entirely.
  • Slug rules differ slightly between renderers, so guessing is unreliable.

Tip: When a jump link does nothing, stop guessing the slug. Open the rendered page, hover the heading, and copy the anchor from its own link icon. That takes five seconds and is right every time.

Linking to a heading in another document

Combine a path and a fragment. The path rules above still apply, and the fragment comes from that document's heading:

[Install the CLI](docs/setup.md#installing-dependencies)
[Rate limits](https://example.com/api/reference#rate-limits)

This is the backbone of navigation in multi-file documentation. Linking a section rather than a whole file is what actually helps the reader.

Awkward URLs, escaping, and opening in a new tab

Spaces in a URL

A space ends the destination, so [Report](my report.pdf) breaks. There are two fixes. Percent-encode the space, which is the portable option, or wrap the destination in angle brackets, which CommonMark and GitHub both support:

[Q3 report](my%20report.pdf)
[Q3 report](<my report.pdf>)

Parentheses in a URL

A closing parenthesis can end the link early. CommonMark allows balanced pairs, so a Wikipedia URL ending in _(disambiguation) usually survives on GitHub. An unbalanced one does not, and older renderers fail on both. Escape it with a backslash, or encode it as %28 and %29:

[Markdown](https://en.wikipedia.org/wiki/Markdown_%28disambiguation%29)
[Release notes](https://example.com/notes\(final\))

The same escape works for a literal square bracket in link text. Write \[ to show a bracket that should not start a link.

Markdown has no syntax for this, by design. The format describes structure, not behaviour. If you genuinely need it, drop to raw HTML:

<a href="https://example.com" target="_blank" rel="noopener noreferrer">Open the dashboard</a>

Always pair target="_blank" with rel="noopener noreferrer". Without it, the destination gets a scriptable handle back to your page. Many platforms strip raw HTML from Markdown anyway, and most site generators have a setting or plugin that adds the attribute to external links for you. Our Markdown versus HTML comparison maps the boundary between the two formats.

Common mistakes and their fixes

Five failures cover almost every link that will not render:

  1. Brackets the wrong way round, with the text in parentheses.
  2. A space between ] and (, which prints the brackets.
  3. Full-width brackets from a Chinese or Japanese IME.
  4. An anchor copied from the heading text, capitals and punctuation included.
  5. An unencoded space in the URL, which truncates the destination.

Bracket order and the extra space

Text goes in square brackets, the URL in parentheses. Broken, then fixed:

(Markdown guide)[https://mdeditor.tw/markdown-guide]
[Markdown guide](https://mdeditor.tw/markdown-guide)

The space is fixed by deleting one character. Broken, then fixed:

[Markdown guide] (https://mdeditor.tw/markdown-guide)
[Markdown guide](https://mdeditor.tw/markdown-guide)

Full-width brackets from a Chinese IME

This is the failure that costs CJK writers the most time. With the input method set to full-width punctuation, typing brackets produces ［］ or （） instead of ASCII [] and (). They look almost identical on screen, but the parser sees ordinary text and renders nothing. Broken, then fixed with ASCII punctuation:

［Markdown 指南］（https://mdeditor.tw/markdown-guide）
[Markdown 指南](https://mdeditor.tw/markdown-guide)

Tip: Fix this once at the source. Switch the IME to half-width punctuation before writing Markdown; both the Chinese and Japanese input methods on macOS and Windows have that toggle. The same trap catches full-width ＃ in headings and ｀ in code spans, so one setting saves you three separate debugging sessions.

Anchors and unencoded spaces

Capitals and punctuation do not survive slug generation. Broken, then fixed:

[Setup](#Setup Guide!)
[Setup](#setup-guide)

An unencoded space is the last one. Everything after the space is treated as a title or discarded, so the link points at a truncated address. Percent-encode it as shown above.

Paste the line into the editor and watch the preview. It is nearly always one of these five.

The complete Markdown guide puts links in context, the cheat sheet keeps the syntax one glance away, and the sibling references for lists, tables and code blocks cover where links most often live.

Support data verified

Frequently Asked Questions

How do I make a Markdown link open in a new tab?

Markdown has no syntax for it. Use raw HTML: <a href="https://example.com" target="_blank" rel="noopener noreferrer">text</a>. Platforms that strip HTML will drop the whole tag, and most static site generators have a setting or plugin that adds the attribute to external links automatically.

Why does my anchor link not jump to the heading?

The fragment does not match the generated ID. IDs are lowercased, punctuation is stripped and spaces become hyphens, so ## API Key (v2) becomes #api-key-v2, and duplicate headings get a -1 suffix. The reliable method is to open the rendered page and copy the anchor from the heading's own link icon.

When should I use reference-style links?

When a URL repeats, when it is long enough to make the raw line unreadable, or when the file is reviewed as a diff and you want URL changes isolated at the bottom. For a single link in a comment or a short note, an inline link is simpler to follow.

Do bare URLs become clickable automatically?

Only in GitHub Flavored Markdown and similar dialects. Plain CommonMark and older renderers leave them as text. The portable options are angle brackets, <https://example.com>, or a full inline link with your own descriptive text.

Why do my links break when I type them in Chinese?

The input method is inserting full-width brackets, ［］（）, instead of ASCII [](). They look nearly the same but the parser does not recognise them. Switch the IME to half-width or English punctuation before typing Markdown syntax and the problem disappears for headings and code spans too.

Keep learning

Markdown lists

Bullets, numbering, nesting indentation, checkboxes and the spacing rules.

Markdown images

Embedding images, alt text, sizing, and why an image is a link with a bang.

The complete Markdown guide

Every element explained in order, with examples you can paste and test.

Try the Editor

Try the Editor