THE GITHTML FIELD GUIDE
Decide which images belong inside a portable HTML report
Include an image when it contributes information that the surrounding text cannot communicate efficiently. For portable reading, embed selected essential visuals when practical and write their important conclusions as text. Leave decorative or very large galleries outside the core document, clearly labeling any external destinations and their limitations.
Classify images by purpose
Begin with the reader's task rather than the available screenshots. A migration guide may need one annotated settings screen, while a decision memo may need no images at all. Classify each candidate as evidence, instruction, context, or decoration. Evidence and instruction deserve the strongest handling because losing them could change the reader's understanding.
Ask what happens when the image is absent. If a step becomes impossible to follow, rewrite the step to name the control and its location in words. If a chart's conclusion disappears, state the conclusion and relevant values nearby. This is useful even when the image loads, because a phone may make small labels difficult to inspect.
Balance independence and file size
Embedding a visual can remove a network dependency, but it also increases the HTML file's size. A document with dozens of large screenshots may become inconvenient to transfer and update. Crop to the relevant region, remove redundant captures, and use appropriate export dimensions. Keep an original elsewhere if the review process requires full-resolution evidence.
External image references are a different tradeoff. They can keep the HTML smaller, but their availability depends on the resource location, authorization, network conditions, and reader settings. gitHtml does not promise automatic full asset mirroring. Do not label a report fully self-contained merely because all image URLs point to the same repository as the HTML.
Use an image review checklist
Each image needs a clear job and an appropriate text alternative. Decorative images generally should not interrupt assistive reading with meaningless filenames. Informative pictures need wording that conveys their purpose in this document, rather than a generic description that could fit any screenshot. A visible caption can explain why the evidence matters.
- List the decision or instruction supported by each image.
- Remove pictures that repeat nearby text without adding useful context.
- Check the final rendered size on a narrow screen, especially annotations.
- Keep essential facts in the HTML body even when the visual is embedded.
- Review the exported file size and open the delivered artifact without remote resources before calling it portable.
Sources and further reading
AI-assisted writing with source-linked guidance and illustrative examples. Read our editorial approach or report a correction.