# Include diagrams without a runtime rendering dependency

Canonical: https://githtml.com/guides/static-diagrams-in-html-reports
Published: 2026-09-26
Publisher: WaveTech LLC / gitHtml

Render the diagram during authoring and include a static visual in the finished HTML document. Add a nearby explanation of the relationships the diagram communicates. Do not require a client-side diagram library to transform source notation after the page opens, especially when your reader keeps JavaScript disabled.

## Separate diagram authoring from viewing

A diagram language can be an excellent source format without being a dependable reading format. The author may maintain a text definition locally, generate a static SVG or image, and publish the result inside the HTML artifact. The reader should not need the original build environment merely to see the relationships being discussed.

Consider a service architecture report. Its source may define nodes and arrows in a diagram tool, but the delivered report should already show the gateway, worker, and storage relationships. If the HTML only contains a block of diagram source and a script import, the visual depends on runtime behavior. That is a different package with different failure modes.

## Design for narrow viewing

A diagram that looks balanced on a desktop slide can become a collection of tiny labels on a phone. Reduce the number of nodes, split independent flows, and place explanatory detail in the adjacent text. A vertical sequence often fits a reading document better than a very wide network. Preserve important branching, however; changing the layout must not change the system's meaning.

For inline SVG, provide a viewBox and avoid a fixed CSS width that forces the entire page sideways. Review exported content before embedding it, especially when it comes from an untrusted source. Remove unnecessary scripts and external references from the authoring output. Static should describe the delivered artifact, not merely the filename extension.

## Write the nonvisual equivalent

A useful caption identifies what the reader should learn. A separate paragraph can state the actual sequence: the client sends a request to the gateway, the gateway queues work, and the worker stores a result. Explain retries or failure branches in text when they affect the conclusion. This also helps a reader who can see the picture but cannot decipher a small label.

1. Export the diagram locally and confirm the finished HTML does not need a rendering script.
2. Check every label at normal phone reading size.
3. Write a concise relationship summary beside the visual.
4. Include important numeric values or decision conditions as text, not only inside shapes.
5. Inspect the document with optional remote resources unavailable before considering the diagram dependable.

## Sources and further reading

- [W3C WAI: complex images](https://www.w3.org/WAI/tutorials/images/complex/)
- [MDN: SVG viewBox](https://developer.mozilla.org/en-US/docs/Web/SVG/Reference/Attribute/viewBox)

## Related guides

- [Add useful section navigation to a long HTML document](https://githtml.com/guides/table-of-contents-for-long-html)
- [Format code samples for reading on an iPhone](https://githtml.com/guides/code-blocks-for-iphone-reading)
- [Make a comparison table usable on a small screen](https://githtml.com/guides/comparison-tables-small-screens)
- [Use native disclosure sections for optional appendices](https://githtml.com/guides/native-details-for-html-appendices)

Editorial approach: https://githtml.com/guides/about