THE GITHTML FIELD GUIDE
Write links that remain meaningful outside their paragraph
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.
- Replace generic labels with a concise subject or action.
- Distinguish multiple links that lead to different documents.
- Identify downloads or restricted destinations when that affects the reader's choice.
- Check same-document fragments separately from external URLs.
- Keep links visually recognizable without relying only on color.
- Ensure a missing external reference does not remove the document's central explanation.
Sources and further reading
AI-assisted writing with source-linked guidance and illustrative examples. Read our editorial approach or report a correction.