THE GITHTML FIELD GUIDE
Build a heading outline that makes a long report navigable
Use headings to describe the document's structure, not to obtain a particular font size. Start with a clear document title, give major sections meaningful labels, and nest subsections according to their relationship. Review the heading outline by itself; it should reveal the report's purpose, evidence, and conclusion without requiring the paragraphs.
Outline the argument before styling
Write the major section names as a plain list before building the layout. A decision report might contain Context, Constraints, Options, Decision, and Follow-up. Those labels describe how the argument works. If the list contains vague names such as Overview two or More details, refine the structure before adding visual treatment.
A heading should predict the content that follows. Use a specific label such as Rollback conditions when a reader will return to find that information. Decorative or clever titles can be appropriate in some writing, but reference material benefits from direct language. Readers navigating by headings do not receive the same visual hints as someone scanning the whole page.
Use levels for relationships
A subsection belongs under the section it develops. Choose its heading level accordingly, and use CSS to control appearance separately. Making a heading smaller does not require demoting it in the hierarchy. Conversely, a large bold paragraph is not automatically a heading that assistive technology can use for navigation.
When combining exported chapters, review the resulting outline rather than trusting each source in isolation. Several components may each assume they own the main title. A table of contents can help expose awkward nesting, but it is not a substitute for correct headings in the document itself. Keep labels consistent between navigation and destination sections.
Check the outline in actual reading
Read only the headings in sequence and ask whether the progression makes sense. Then navigate through them with a screen reader in the intended environment when possible. This is a targeted check, not a claim that the whole document meets every accessibility requirement. Record any skipped content or confusing transition you discover.
- Write one clear title describing the report.
- Label major sections by the questions they answer.
- Nest subsections according to meaning, not visual size.
- Check merged exports for duplicate or misplaced top-level headings.
- Verify that warnings and conclusions sit under appropriate headings.
- Use a real paragraph for a short emphasized statement that does not introduce a section.
Sources and further reading
AI-assisted writing with source-linked guidance and illustrative examples. Read our editorial approach or report a correction.