View a GitHub HTML file as a rendered page instead of source code

What GitHub shows you today

When you click an .html file in a repository, GitHub opens its code viewer. You see line numbers, Blame, and a Raw button, but not the page the markup describes. GitHub's documentation for non-code files says it does not directly support rendered views of HTML documents, even though it renders images, PDFs, CSV tables, and Markdown previews.

That design is reasonable. An HTML file can contain scripts, forms, and references to other hosts, and rendering arbitrary repository files inside github.com would run untrusted content in a trusted context. The result for a reader, though, is that a carefully written report looks like a wall of tags.

Why the Raw button does not help

The Raw button sends you to raw.githubusercontent.com. In current behavior that host labels HTML files as text/plain and adds a nosniff header, so browsers display the characters instead of interpreting them. It also sends a restrictive content security policy that would block scripts and outside resources. Treat this as observed behavior rather than a documented contract; the point is that Raw is for retrieving the file, not for reading it as a page.

This is the right time to stop trying URL tricks. Third-party preview proxies exist, but they fetch your file through someone else's server, they cannot see private repositories without credentials, and they add a dependency you do not control.

Choose a reading route

Pick the route that matches where you are and who needs access. On a computer, a clone gives you the exact revision in your own browser. On an iPhone or iPad, a reader that indexes repository HTML files can render the document directly from your GitHub account. If many people outside the repository need the page, a hosting service is the appropriate tool; note that GitHub Pages deploys through GitHub Actions workflow runs and publishes to the internet, so evaluate that against your own policies before choosing it.

1. Desk, one-off read: clone or pull the repository and open the file in a browser.
2. Desk, file uses root-relative paths or fetch: serve the folder locally instead of double-clicking.
3. Phone or tablet: open the indexed .html file in gitHtml and keep JavaScript and remote resources off unless the document needs them.
4. Wide audience outside the repository: use a hosting service you have reviewed for access control and deployment requirements.

Local commands for an exact revision

Cloning is the most faithful option because the browser sees the file alongside its sibling stylesheets and images. Double-clicking opens a file URL, where root-relative paths such as /css/site.css and JavaScript fetch calls may fail. A small local server avoids those problems for the length of your reading session and stops when you close the terminal.

git clone https://github.com/OWNER/REPO.git
cd REPO
git switch --detach v2.4.0   # optional: read a tagged revision
open docs/report.html         # macOS; use xdg-open on Linux

# If styles or data fail to load from a file URL:
python3 -m http.server 8000
# then visit http://localhost:8000/docs/report.html

Make the file worth rendering

Whatever route you choose, the document is easier to read when it does not depend on its surroundings. Put essential CSS inside a style element, describe diagrams in text, and avoid making the body empty until a script runs. Then the same file reads correctly in a local browser, in gitHtml, and in a hosted copy, and readers can trust that what they see is the committed revision.

Read next

• Find actual HTML documents in a GitHub repository
• Build a single-file HTML document that travels well
• Share a GitHub document at an exact revision
• Map an unfamiliar documentation repository before reading

All github documentation workflows guides →