THE GITHTML FIELD GUIDE
Write HTML callouts that clarify warnings and decisions
Make each callout express one clear function: warning, note, decision, or example. Put that function into visible text, keep the content concise, and use normal semantic HTML rather than a custom interactive widget. Important warnings belong before the action they qualify, not in a collapsed appendix after it.
Choose the message before the treatment
A colored box is not automatically useful. Decide what the reader should do differently after reading it. A warning might say that a local command overwrites generated output. A note might explain a platform-specific variation. A decision callout might summarize the selected option and its constraint. If you cannot identify the function, the paragraph may not need special treatment.
Use a small vocabulary consistently throughout the document. If every section contains Important, Tip, Caution, and Remember boxes, readers must learn the styling system before understanding the content. Reserve prominent treatment for information that genuinely changes an action or interpretation. Routine background can remain in the normal reading flow.
Keep meaning in the text
A warning should say Warning, not merely have a red border. The distinction matters for readers with color-vision differences, monochrome printing, missing styles, and screen-reader use. Avoid using a symbol by itself as the entire label. Icons can supplement the words, but the words should carry the meaning.
Use a heading or a strong introductory label appropriate to the document hierarchy. Not every box needs to become a separate navigation landmark. For a short static note, a plain paragraph with a clear label can be enough. Do not apply live-region attributes to ordinary content merely because the box looks important; a static report is not announcing an event as it happens.
Position the callout where it helps
Place a risk statement before the command or procedure it affects. A reader skimming on a phone should encounter the condition before reaching the action. Keep examples and supplemental explanations close to the relevant paragraph, but avoid squeezing them into a narrow sidebar that breaks the reading order.
- Read the callout with its background and border removed.
- Check whether its position precedes the relevant action.
- Remove repeated warnings that do not add a new condition.
- Verify that enlarged text fits without a fixed-height box clipping the message.
<section class="warning" aria-labelledby="overwrite-warning">
<h2 id="overwrite-warning">Warning: preserve your source</h2>
<p>Export into a separate output directory. Do not replace your editable notes.</p>
</section>Sources and further reading
AI-assisted writing with source-linked guidance and illustrative examples. Read our editorial approach or report a correction.