The essentials
Quick reference
One focused task per row. Jump to the related section for complete, working examples.
| Use | Syntax | Examples |
|---|---|---|
| Link within the site | <a href="/guides/setup/">Setup guide</a> | View examples |
| Link beside the page | <a href="api.html">API reference</a> | View examples |
| Link to another site | <a href="https://example.com/status">Service status</a> | View examples |
| Link to a section | <a href="#installation">Installation</a> | View examples |
| Link to another section | <a href="/docs/cli/#options">CLI options</a> | View examples |
| Start an email | <a href="mailto:support@example.com">Email support</a> | View examples |
| Start a phone call | <a href="tel:+15550100100">Call support</a> | View examples |
| Suggest a download | <a href="/files/report.pdf" download>
Download the report
</a> | View examples |
| Name a download | <a href="/exports/data.csv" download="customers.csv">
Download customer CSV
</a> | View examples |
| Open a new tab safely | <a
href="https://example.com/docs"
target="_blank"
rel="noopener noreferrer">
External documentation
</a> | View examples |
| Create primary navigation | <nav aria-label="Primary">
<a href="/docs/">Docs</a>
<a href="/support/">Support</a>
</nav> | View examples |
| Create breadcrumb navigation | <nav aria-label="Breadcrumb">
<ol>
<li>
<a href="/">Home</a>
</li>
<li>Docs</li>
</ol>
</nav> | View examples |
| Mark the current page | <a href="/docs/" aria-current="page">Docs</a> | View examples |
| Add a skip link | <a class="skip-link" href="#main-content">
Skip to content
</a> | View examples |
| Hint the target language | <a href="/pt/ajuda/" hreflang="pt-BR">
Ajuda em português
</a> | View examples |
| Hint the resource type | <a href="/files/guide.pdf" type="application/pdf">
PDF guide
</a> | View examples |
A link should take the user to a resource or location and explain that destination in its accessible text. Use buttons for in-page actions, group major destinations in named navigation landmarks, expose the current page, and preserve predictable browser behavior unless opening a new context is genuinely useful.
Step by step
Detailed examples
Choose a URL that matches the destination
Root-relative URLs remain anchored to the current origin, document-relative URLs depend on the current page location, and absolute URLs name the full destination. Link text should make sense out of context and should not expose a raw URL unless the URL itself is useful content.
<p><a href="/guides/setup/">Setup guide</a></p>
<p><a href="api.html">API reference</a></p>
<p><a href="https://example.com/status">Service status</a></p>Connect links to stable fragment targets
A fragment matches an element ID in the destination document. IDs must be unique, stable, and URL-safe enough for sharing. A fragment navigation changes the URL and can support browser history; use a button instead when the control only changes interface state.
<nav aria-label="On this page">
<a href="#installation">Installation</a>
<a href="/docs/cli/#options">CLI options</a>
</nav>
<section id="installation" tabindex="-1">
<h2>Installation</h2>
</section>Offer email and telephone actions
mailto and tel URLs delegate to applications configured on the user's device and may do nothing when no suitable handler exists. Keep visible contact details available as text, and avoid pre-populating sensitive message data in a URL because URLs can be logged or shared.
<address>
<a href="mailto:support@example.com">Email support</a><br>
<a href="tel:+15550100100">Call support</a>
</address>Handle downloads and new browsing contexts carefully
download is a suggestion and is most reliable for same-origin resources. target blank should be disclosed when the context change may surprise users; modern browsers imply opener isolation in many cases, but explicit noopener documents the intent. Add noreferrer only when suppressing the Referer header is also desired.
<a href="/files/report.pdf" download>Download the report</a>
<a href="/exports/data.csv" download="customers.csv">Download customer CSV</a>
<a href="https://example.com/docs" target="_blank" rel="noopener noreferrer">External documentation (opens in a new tab)</a>Provide advisory destination metadata
hreflang identifies the linked resource's language and type gives an advisory MIME type. These hints do not replace clear link text, do not force the server to return that language or type, and should stay consistent with the actual response.
<a href="/pt/ajuda/" hreflang="pt-BR">Ajuda em português</a>
<a href="/files/guide.pdf" type="application/pdf">PDF guide</a>Local code tester
Try navigation markup
Edit the named navigation, current-page link, skip target, and destinations, then render them locally.
Sources and further reading
References
Authoritative documentation used to verify and expand this cheat sheet.
Help us improve
Found a typo or missing example?
Tell us what would make this cheat sheet clearer, more complete, or more useful.