THE GITHTML FIELD GUIDE
Keep citations and footnotes usable on a phone
Place short source references near the claims they support and put longer explanatory notes in a clearly labeled section. Use stable fragment IDs, meaningful link labels, and a return link where a note sends readers far from the original paragraph. Keep essential caveats in the body rather than burying them in footnotes.
Separate evidence from qualification
A citation points to evidence; a footnote can provide a secondary explanation. Neither is a good hiding place for a condition that changes the main recommendation. If an estimate excludes storage costs, say that in the relevant paragraph. A reader reviewing the document quickly should not need to inspect every tiny marker to discover the boundaries of the argument.
For a technical report, name the source sufficiently to identify it later. A bare link labeled here makes little sense when extracted from its paragraph. Prefer labels such as Browser viewport reference or Capacity estimate worksheet. Include a publication or retrieval date when the timing of the evidence matters, and distinguish that date from the report's own revision date.
Build a predictable reading loop
A same-document footnote link can move a reader many screens away from the original passage. Add a return link next to the note when that jump would otherwise be disruptive. Give each reference and destination a unique identifier. Repeated IDs introduced by merging several exported chapters can make the apparent navigation unreliable.
Avoid making reference markers so small or crowded that tapping one becomes difficult. A short Sources paragraph under a section may be easier to use than superscript numbers after every sentence. Choose the pattern based on reading flow and citation density. Consistency within the document matters more than copying the style of an academic PDF.
Keep the document useful without visiting sources
External sources provide verification and further detail, but the report should contain its own explanation. A source may become unavailable, require authentication, or be inappropriate to open during a meeting. Summarize the relevant reasoning in original prose while preserving the link for readers who need to investigate.
- Follow every note link in the exported artifact.
- Check that the source label identifies the destination.
- Keep caveats that affect a decision beside the decision itself.
- Avoid implying that linked documents are automatically available offline.
<p id="estimate-ref">The estimate excludes archived copies.
<a href="#estimate-note">Read estimate assumptions</a>.</p>
<section id="estimate-note">
<h2>Estimate assumptions</h2>
<p>Only the current export is counted.</p>
<a href="#estimate-ref">Return to the estimate</a>
</section>Sources and further reading
AI-assisted writing with source-linked guidance and illustrative examples. Read our editorial approach or report a correction.