THE GITHTML FIELD GUIDE
Use native disclosure sections for optional appendices
Use details and summary for genuinely optional explanations, not for the core answer or a critical warning. Give each disclosure a descriptive label and keep its contents logically structured. Native disclosure elements avoid a custom JavaScript dependency, but still need inspection for keyboard, touch, and screen-reader use in the delivered document.
Choose what may be collapsed
A long report often contains two reading modes: a quick decision review and a detailed evidence inspection. Disclosure sections can separate those modes without creating additional files. Suitable candidates include a calculation walkthrough, a verbose log sample, or background assumptions. The recommendation and its major caveats should remain visible in the ordinary reading flow.
Ask what a reader would misunderstand if they never expanded the section. If the answer is the risk of deleting data, the reason a recommendation does not apply, or a required prerequisite, do not hide that information. Collapsing material is a presentation choice, not permission to demote facts that affect a safe decision.
Write summaries that invite the right action
The summary label should predict the content. Read the capacity calculation is more informative than More or Advanced. When several disclosures appear together, distinguish them by subject rather than repeating the same generic label. Keep the entire label short enough to read comfortably on a narrow screen, while allowing it to wrap naturally.
Inside the disclosure, use paragraphs, lists, and headings as needed. Avoid nesting many disclosure levels; readers can lose track of what is open and where they are. If an appendix is long enough to need its own navigation, a regular section may be simpler. Do not rebuild native behavior with clickable divs merely to change the appearance of the indicator.
Inspect both states
The closed state should make the document scan well, and the open state should behave like ordinary readable content. Check that opening a large section does not obscure the next heading or create an oversized fixed container. When exporting or printing, verify what the particular rendering path includes rather than assuming closed material will appear automatically.
- Keep the headline result outside the disclosure.
- Open and close each summary using touch and keyboard when available.
- Check a long label and enlarged text.
- Ensure essential instructions remain clear when every disclosure is closed.
<details>
<summary>Read the storage estimate</summary>
<p>The estimate assumes twelve monthly snapshots.</p>
<ul><li>Count retained copies.</li><li>Include expected growth.</li></ul>
</details>Sources and further reading
AI-assisted writing with source-linked guidance and illustrative examples. Read our editorial approach or report a correction.