THE GITHTML FIELD GUIDE
Use landmarks to separate navigation from the report body
Use semantic elements such as main and nav to identify the document's major regions. Keep the principal report content in one clear main region and label separate navigation areas when their purposes differ. Landmarks should simplify orientation, not create a long inventory of every callout, card, and decorative container.
Map the large regions
A standalone report usually has fewer meaningful regions than a full website. It may need a title area, a document contents list, the main article, and a source or revision footer. Begin with those large roles. Do not copy an application's complex shell into the artifact if its sidebars, account controls, and search panels are absent or nonfunctional.
The main region should contain the report's central reading content. Navigation should contain actual navigation links, not arbitrary groups of buttons or highlighted facts. Native HTML elements provide a useful baseline without requiring custom scripting. Choose them because their meaning matches the content, not because a CSS framework happens to use the same class names.
Give repeated regions distinct purposes
If the document has both site navigation and a section contents list, identify their purposes clearly. A reader using landmark navigation should be able to distinguish them without entering each one. In a portable report, you may decide that site navigation adds little value and remove it entirely, leaving only the document's own contents.
Avoid creating a named region for every two-sentence callout. Excessive landmarks can make navigation noisy and less helpful. Headings already provide a finer-grained outline inside the main content. Use regions for substantial areas that readers may reasonably want to jump between, and headings for the structure within those areas.
Test navigation without visual position
Imagine entering the document without knowing where anything appears on the screen. Can the main report be found quickly? Can a repeated navigation block be bypassed? Do region names explain their function? These questions reveal whether the markup supports orientation rather than merely describing the visual boxes.
- Inspect the document's landmarks with assistive technology when available.
- Remove empty navigation shells inherited from a template.
- Give genuinely distinct navigation regions clear names.
- Keep the reading order sensible when all layout styling is removed.
<nav aria-label="Report sections">
<a href="#findings">Findings</a>
</nav>
<main>
<h1>Quarterly service review</h1>
<h2 id="findings">Findings</h2>
<p>The main report begins here.</p>
</main>Sources and further reading
AI-assisted writing with source-linked guidance and illustrative examples. Read our editorial approach or report a correction.