# Write links that remain meaningful outside their paragraph

Canonical: https://githtml.com/guides/descriptive-links-html-reports
Published: 2026-09-26
Publisher: WaveTech LLC / gitHtml

Use link text that identifies the destination or action in context, and avoid repeated labels such as here or read more when they lead to different places. Make section links, source references, and downloads distinguishable. A reader should understand the likely destination without needing to inspect a raw URL or remember nearby visual placement.

## Name what the reader will find

A link labeled Review the storage estimate gives more information than Click here. The label should describe the destination, not merely the physical action of tapping. When the same document contains several links, keep their names distinct enough that a reader navigating a list of links can make a useful choice.

Do not make every label excessively long. Include the information needed to choose: topic, purpose, and an important format or access condition when relevant. For example, Original benchmark data communicates a different destination from Benchmark summary. If a link opens a large external reference rather than another section of the report, make that expectation clear in the wording or surrounding sentence.

## Separate local navigation from external dependencies

Same-document links help readers move through a long artifact without leaving it. External citations provide evidence or further detail. Treat those roles differently in the editorial structure. A source list can identify references clearly, while a concise contents list identifies the report's own sections. Do not disguise a remote application route as though it were a local appendix.

If a destination requires authorization, state that where useful. A reader should not spend time diagnosing a sign-in page as a broken report. Avoid including credentials in the URL, and remove unnecessary tracking parameters when you control the link and can preserve the destination. Keep essential explanations in the report rather than outsourcing the whole answer to linked material.

## Check the complete link inventory

Read every link label without its surrounding paragraph and note ambiguous repetitions. Then test the destinations in the exported artifact. A good label cannot repair an incorrect href, and a working destination does not make a vague label understandable. Both the wording and the target need review.

1. Replace generic labels with a concise subject or action.
2. Distinguish multiple links that lead to different documents.
3. Identify downloads or restricted destinations when that affects the reader's choice.
4. Check same-document fragments separately from external URLs.
5. Keep links visually recognizable without relying only on color.
6. Ensure a missing external reference does not remove the document's central explanation.

## Sources and further reading

- [W3C: understanding link purpose in context](https://www.w3.org/WAI/WCAG22/Understanding/link-purpose-in-context.html)

## Related guides

- [Build a heading outline that makes a long report navigable](https://githtml.com/guides/heading-hierarchy-readable-html)
- [Use landmarks to separate navigation from the report body](https://githtml.com/guides/document-landmarks-for-html-reading)
- [Write screenshot alternatives that explain the useful information](https://githtml.com/guides/alt-text-for-document-screenshots)
- [Describe architecture diagrams as relationships, not shapes](https://githtml.com/guides/text-descriptions-for-architecture-diagrams)

Editorial approach: https://githtml.com/guides/about