THE GITHTML FIELD GUIDE
Distinguish a GitHub file page from an image resource URL
An image element needs image data, not an HTML page that displays a file in GitHub's interface. Inspect the destination and response type before changing the document. For private or portable material, embedding an approved image may be more dependable than constructing a remote URL with uncertain authorization or lifetime.
Recognize the wrong response
A URL copied from the browser address bar while viewing a repository image may identify a GitHub file page. That page includes navigation, controls, and a preview, but it is still HTML. Placing its URL in an image src attribute asks the browser to decode an HTML response as an image, which does not produce the intended picture.
Do not diagnose this solely from the visible URL shape. Redirects and authentication can change the final response. Open the destination through an appropriate authorized inspection path and check what it actually returns. A login page can also masquerade as a successful page load while providing no image bytes to the document.
Avoid leaking authorization into the document
Private repository assets add a second question: who is allowed to retrieve the image? A link that works in your signed-in browser may fail in a different rendering context. Do not paste access tokens, session information, or temporary signed credentials into an HTML file to make the request succeed. Committing such values can expose access and still leave the document dependent on expiry.
Use the repository's supported interface to obtain an appropriate resource location when remote loading is intentional. If the document must be portable, consider embedding a permitted copy during authoring. Confirm that the image itself is approved for the document's audience; changing its packaging does not change its confidentiality.
Keep a useful fallback
The report should explain the image's purpose even when retrieval fails. A caption and meaningful alternative text help, but complex evidence may also need a paragraph or table. In gitHtml, remote resources are optional and off by default, so a remote image should be treated as a declared dependency rather than an invisible assumption.
- Check whether the current URL returns an image or an HTML interface.
- Verify that the destination is suitable for the document's audience.
- Remove any credentials or sensitive query parameters from examples and committed files.
- Choose either an authorized remote resource or a reviewed embedded asset.
- Reopen the finished document with remote resources unavailable and confirm its central explanation still makes sense.
Sources and further reading
AI-assisted writing with source-linked guidance and illustrative examples. Read our editorial approach or report a correction.