THE GITHTML FIELD GUIDE
Troubleshoot broken relative image paths in repository HTML
Resolve each relative image URL from the HTML document's location, then verify that the referenced file exists with the same spelling and case. A correct repository path still does not guarantee that a reader fetches or caches the asset. Use a portable export when essential images must travel with the HTML.
Work through one concrete path
Suppose a repository contains reports/review.html and reports/images/flow.png. From review.html, images/flow.png expresses that relationship. If the image instead lives at the repository's top-level images directory, the relative reference would need to move up a directory first. Write down the actual tree before editing paths; guessing by filename often produces a different broken reference.
A leading slash changes the meaning to a root-relative URL in a web context. It does not mean repository root in every possible reader. Likewise, a path copied from a local computer can contain directories that do not exist for anyone else. Avoid absolute filesystem paths in published HTML and check the final output after any export process rewrites resource locations.
Check names and retrieval separately
Filename case can be overlooked when local development happens on a case-insensitive filesystem. A reference to Flow.png should match the committed filename exactly. Spaces and special characters also deserve attention, particularly when an author manually constructs a URL. Compare the actual committed path rather than the display name shown by an image editor.
After the path is correct, ask how the image will be retrieved. It may require network access, repository authorization, or a resource-loading behavior that the reader does not provide. gitHtml does not promise automatic full asset mirroring. A path fix addresses naming and location; it does not turn a multi-file document into a self-contained one.
Choose the appropriate repair
For a small essential diagram, an embedded representation may be the simplest portable solution. For a large optional gallery, preserve a useful caption and link to an authorized source instead. If the image contains the only copy of a critical instruction, add that instruction to the HTML body so a resource failure does not erase it.
- Record the HTML file's committed directory.
- Resolve one broken reference relative to that directory.
- Compare capitalization and extension with the actual asset.
- Check for a base element that changes URL resolution.
- Verify the asset under the intended authorization and resource settings.
- Recheck the final artifact rather than only the original local folder.
Sources and further reading
AI-assisted writing with source-linked guidance and illustrative examples. Read our editorial approach or report a correction.