Markdown links

Square brackets hold the visible text, round brackets hold the address, and nothing goes between the two — not a space, not a newline. That gap is the single most common reason a link renders as [text] (url) in plain characters.

The link text can contain other inline formatting: bold, italic, inline code, even an image. It cannot contain another link. The URL can be absolute, relative, or a fragment such as #pricing, and it can be any scheme the renderer allows — https:, mailto:, tel:.

Write link text that describes the destination. "Click here" and a bare "read more" are useless to anyone navigating by links alone.

Read the [pricing page](https://example.com/pricing).

Or the **[migration notes](/docs/migrate)**.

A quoted string after the URL becomes the link's title attribute, which browsers show as a tooltip on hover. Put a space between the URL and the opening quote. Single quotes and parentheses work too, but double quotes are the convention.

Titles are optional and easy to overuse. They are invisible on touch devices and are not a substitute for clear link text, so reserve them for genuinely supplementary detail — a file size, a warning that the link leaves the site, the full title of a document you have referred to by shorthand.

[The 2026 report](https://example.com/report.pdf "PDF, 4.2 MB")

Angle brackets around a URL make it a link whose text is the URL itself. This is the CommonMark autolink, and it is the portable way to show a raw address. It requires a scheme: <https://example.com> works, <example.com> does not.

Separately, most modern renderers — this one included, and GitHub — run a linkifier that turns a bare URL into a link with no markup at all. That is convenient but not universal, so if the document has to travel, use angle brackets or a proper inline link. A bare URL that ends in punctuation is a classic trap: the linkifier often swallows the full stop.

Docs: <https://example.com/docs>

Or bare: https://example.com/docs

Split the link in two. Where the link appears, put the text in brackets followed by a label in brackets. Anywhere else in the document — conventionally at the bottom — define that label with its URL. The definitions never render.

This pays off in two situations: a long paragraph where inline URLs make the source unreadable, and a URL you cite several times and want to change in one place. Labels are case-insensitive and may contain spaces. If you omit the second pair of brackets entirely, the link text doubles as the label, which keeps prose clean.

See the [style guide][style] and the [API reference][api].

The [style][] link again.

[style]: https://example.com/style
[api]: https://example.com/api "v3"

Most renderers give every heading an id derived from its text, so you can link to it with a fragment. The usual rule — GitHub's, and close to universal — is: lowercase the text, replace spaces with hyphens, drop punctuation. So ## Rate limits (v3) becomes #rate-limits-v3.

Two caveats. Duplicate headings get a numeric suffix, #setup, #setup-1, and so on. And the rule is a convention, not a specification: a different renderer may slugify differently, and some — including this viewer — do not add heading ids at all, so the anchor simply does nothing. When the link matters, check the rendered page and copy the id from it rather than guessing.

Jump to [rate limits](#rate-limits-v3).

## Rate limits (v3)

In a README or a docs folder, link to other files by path rather than by full URL. [contributing](CONTRIBUTING.md) resolves against the current file's location, so it keeps working when the repo is cloned, forked, or mirrored to another host. A leading slash means the root of the site, not the root of the repo, which is a common mix-up.

GitHub resolves ../ normally, and links to a .md file open the rendered version. Two things that do not survive: links into the repo's own web interface, like /issues/12, break outside GitHub, and case matters on Linux even if it did not on your Mac.

- [Contributing](CONTRIBUTING.md)
- [Architecture](docs/architecture.md)
- [Back to root](../README.md)

An email address in angle brackets becomes a mailto: link automatically. For custom link text, write it inline with an explicit mailto: URL, and you can append a subject as a query string. Phone numbers work the same way with tel:.

One caution: a plain address on a public page is scraped for spam. That was the reason for the character-entity obfuscation the original Markdown did automatically; modern parsers, including ours, no longer bother, so use a contact form if that matters to you.

<support@example.com>

[Email support](mailto:support@example.com?subject=Bug%20report)

A space inside the round brackets ends the URL, so the rest becomes a broken title and the link points at a fragment. Encode each space as %20, or wrap the whole URL in angle brackets, which is the more readable of the two.

Parentheses inside a URL — common in Wikipedia articles — close the link early. Angle brackets fix that too, or escape the offending bracket with a backslash. Underscores in a long URL can trigger emphasis in older parsers; angle brackets avoid that as well. When in doubt, the angle-bracket form is the one that survives.

[Report](<https://example.com/Q3 report final.pdf>)

[Turing (computer scientist)](<https://en.wikipedia.org/wiki/Alan_Turing_(scientist)>)

Opening in a new tab is not possible in pure Markdown. There is no syntax for target="_blank". On platforms that permit raw HTML you can write an anchor tag by hand; this viewer disables raw HTML, so a tag pasted here shows as text. Most renderers, including ours, do add rel="noopener noreferrer" to every link for safety.

Other frequent causes: a space between ] and (; smart quotes around the title after pasting from Word; a reference label that is defined but never matched because of a typo; a URL that lost its https:// and is treated as a relative path; and link text containing an unescaped ]. If a link renders as literal brackets, check those five before anything else. The cheat sheet has the working forms side by side.