THE GITHTML FIELD GUIDE
Why raw.githubusercontent.com shows HTML as plain text
raw.githubusercontent.com currently serves .html files with a text/plain content type, an X-Content-Type-Options nosniff header, and a sandboxing content security policy. Browsers therefore display the markup as text and will not run it as a page. The fix is not a different raw URL; use a reader or host that is meant to render HTML.
Confirm the symptom with headers
A page that shows angle brackets instead of formatted content is usually a content-type problem, not broken HTML. You can confirm it in a few seconds by requesting only the response headers. The same file opened from your disk renders normally, which tells you the markup itself is fine.
In a header check against a public repository, the raw host returned text/plain with a UTF-8 charset, nosniff, and a policy beginning with default-src 'none' plus sandbox. Each of those alone is enough to keep a browser from treating the response as a web page.
curl -sI https://raw.githubusercontent.com/OWNER/REPO/main/docs/report.html \
| grep -iE 'content-type|x-content-type-options|content-security-policy'
# Typical result (observed behavior, may change):
# content-type: text/plain; charset=utf-8
# x-content-type-options: nosniff
# content-security-policy: default-src 'none'; style-src 'unsafe-inline'; sandboxWhat each header does
Content-Type tells the browser what the bytes are. With text/plain, the browser chooses its plain-text viewer. Older browsers sometimes guessed and rendered HTML anyway; the nosniff header, defined in the Fetch standard and described on MDN, tells the browser not to second-guess the declared type.
The content security policy is a second wall. default-src 'none' forbids loading images, fonts, scripts, and external stylesheets, and the sandbox directive treats the response as an isolated origin. Even if you could force rendering, a typical report would lose its images and any script-driven content.
Avoid these dead ends
People often try appending query strings, swapping branches, or changing the file extension. None of those change the headers. Browser extensions that rewrite response headers can force rendering locally, but they weaken a protection for every page that matches the rule. Public proxy sites that re-serve raw files with an HTML type work only for public repositories and route your document through an unknown server.
- Do not paste private-repository raw URLs containing tokens into third-party previewers.
- Do not install header-rewriting extensions just to read documentation.
- Do not rename report.html to report.htm or add query parameters expecting a new content type.
Routes that do render
Clone the repository and open the file locally, or serve the folder with a small local server when the document uses root-relative paths. On iPhone and iPad, gitHtml lists .html files from repositories you connect and renders them with WebKit, with JavaScript and remote resources off by default. For public distribution, use a hosting service and accept its deployment model deliberately.
When you control the document, make it resilient to any of these routes: keep essential CSS inline, embed or describe key images, and put the meaningful text in the HTML body rather than generating it at runtime.
Sources and further reading
- MDN: X-Content-Type-Options
- MDN: Content-Security-Policy sandbox directive
- GitHub Docs: Working with non-code files
AI-assisted writing with source-linked guidance and illustrative examples. Read our editorial approach or report a correction.