GitHub will not render HTML from a repository. Raw files are served as plain text on purpose, so clicking through to a page in a branch shows you source, not a page.
This is a security decision, not an oversight. If raw files rendered as HTML, anyone could host an executable page on a trusted domain and use it for phishing. The consequence is that previewing a branch takes a deliberate step, and there are five reasonable ones depending on how much setup you want.
Table of contents
- Why raw HTML does not render
- Option one: run it locally
- Option two: third-party raw renderers
- Option three: deploy previews
- Option four and five: Codespaces and the diff itself
- Picking one
- How this fits the rest of the stack
- FAQ
Why raw HTML does not render
Files fetched from the raw content domain are served with a content type that instructs the browser to display them as text, and with headers that prevent the browser from guessing otherwise.
That single decision blocks a whole family of abuse. Without it, any user could push a convincing login page to a public repository and share a link on a domain people trust. The same applies to scripts: a raw JavaScript file that executed in the browser would make the platform a free host for anything.
So there is no query parameter or header trick that makes it render. Every working approach either serves the file from somewhere else or renders it outside the browser’s normal navigation path.
The related question people ask alongside this one is why a GitHub Pages site does not update after a push. That is a different problem with a different cause - usually the build workflow has not finished, or the browser is holding a cached copy. Pages only ever serves one configured branch, so a push to a feature branch will not appear there at all.
Option one: run it locally
The most reliable answer, and the one that behaves closest to production. Fetch the branch and serve it.
git fetch origin
git switch feature/new-landing
# Python, no install needed
python3 -m http.server 8000
# Or Node
npx serve .
# Then open http://localhost:8000Use a server rather than opening the file directly from disk. A file opened over the file protocol has a different origin behaviour: fetch requests fail, module scripts fail to load, and root-relative paths resolve against the filesystem instead of a site root. Pages that work when served often appear broken when opened as files, and you end up debugging a problem that does not exist.
If you want to compare against the main branch, a worktree avoids switching back and forth.
git worktree add ../preview-branch feature/new-landing
cd ../preview-branch
python3 -m http.server 8001
# main on 8000, the branch on 8001, both open at onceThat side-by-side comparison is the part that makes reviewing a visual change actually possible. Reading a diff of HTML and CSS tells you what changed; two browser windows tell you whether it looks right.
Option two: third-party raw renderers
There are services that fetch a raw file from a repository and serve it with an HTML content type, so it renders. They take a URL to the raw file and return a rendered page.
They are convenient for a single self-contained page and unreliable for anything else. Relative paths to CSS, JavaScript, and images are rewritten by the proxy, and the rewriting works for simple cases and fails for nested directories, module imports, and anything loaded at runtime.
Two more cautions. The service sees your URL, so this is for public repositories only - a private repository will not fetch anyway. And these are volunteer-run proxies that come and go, so a link you share today may not work next month.
Reasonable for a quick look at one page. Not something to put in a review process.
Option three: deploy previews
The version that scales, and what most teams settle on. A hosting platform builds every branch or pull request and gives you a URL for it.
The mechanics are the same everywhere: connect the repository, the platform watches for pushes, each branch or pull request gets its own build and its own address. A bot comments the link on the pull request, so a reviewer clicks rather than clones.
What makes this different in kind from the local option is that non-developers can use it. A designer, a copywriter, or whoever asked for the change can look at the actual page without installing anything, which usually removes an entire round of back-and-forth.
It also catches a class of bug the other options miss: anything that only appears once the site is built and served over HTTPS from a real domain. Mixed-content warnings, absolute paths that assumed a root, and service worker behaviour all fall into that category.
On RunxBuild, a static site builds from a repository with custom domains, headers, redirects, rewrites, and SPA fallback, with 120GB of bandwidth included. Deploy history means the previous version is one rollback away when a preview turns out to be the better one.
Option four and five: Codespaces and the diff itself
GitHub’s own cloud development environments will check out a branch, run a server, and forward the port to a URL you can open. For a repository you already have configured, this is the fastest path to a rendered page without touching your local machine, and it is genuinely useful when you are reviewing on a device that has no toolchain installed.
The last option costs nothing and is underrated: read the rendered diff carefully rather than previewing at all.
# What changed in this branch, HTML only
git diff main...feature/new-landing -- '*.html'
# Just the filenames
git diff --name-only main...feature/new-landing
# Ignore whitespace-only churn from a reformat
git diff -w main...feature/new-landingThe three-dot form is the one you want for reviewing a branch. It compares against the point where the branch diverged, so changes that landed on main in the meantime do not show up as differences. The two-dot form compares the current tips and will show you main’s commits as removals, which is almost never what you meant.
For a copy change or an attribute fix, the diff is faster and more precise than any preview. Save the rendered preview for changes where layout, spacing, or interaction is the actual subject.
Picking one
- One self-contained page, quick look - a third-party raw renderer, accepting that assets may not load.
- You have the repository locally - fetch the branch and serve it. Use a worktree to compare against main side by side.
- Reviewers include non-developers - deploy previews. This is the one that removes work from other people rather than adding it.
- No local toolchain available - a cloud development environment with port forwarding.
- Text-level change - read the three-dot diff and skip the preview.
The pattern worth building toward is the third one. A preview URL on every pull request turns “can you check this looks right” from a request into a link, and the cost of setting it up once is smaller than the cost of the fourth time someone clones a branch to look at a heading.
How this fits the rest of the stack
A branch preview is only useful if getting one is cheaper than asking someone to imagine the change. Building a static site from a repository on RunxBuild gives you a live route, custom domains, headers and redirects, and rollback to the previous deploy when a preview turns out to be the version you wanted. The RunxBuild hosting calculator shows the static site line alongside any service and database behind it, with 120GB of bandwidth included before per-gigabyte pricing starts.
Useful related references:
- TanStack Query with WebSockets: Push Updates Into the Cache, Not Around It
- Deploy a Static HTML Website for Free
- Git Rename Branch: The Local Move, the Remote Move, and the Part That Breaks CI
- Deploying from GitHub on RunxBuild
FAQ
Why does GitHub show my HTML file as code instead of a page?
Because raw files are served with a plain-text content type and headers that stop the browser guessing otherwise. It is a deliberate security measure - if raw HTML rendered, the domain could be used to host phishing pages. There is no parameter that changes it.
How do I preview a branch without merging it?
Fetch the branch and serve it locally with a static server, or connect the repository to a host that builds deploy previews per branch. For non-developer reviewers, deploy previews are the option that does not require them to install anything.
Why is my GitHub Pages site not updating after a push?
Usually the build has not finished yet, or your browser is serving a cached copy - try a hard refresh or a private window. Also check which branch Pages is configured to serve: a push to a feature branch never appears, because Pages only publishes the one branch you configured.
Can I preview HTML from a private repository?
Not through third-party raw renderers, which cannot authenticate. Use a local server after fetching the branch, a cloud development environment with port forwarding, or a hosting platform that has authenticated access to the repository and can build previews.
Why does my page break when I open the HTML file directly?
Opening a file from disk uses a different origin model than serving it over HTTP. Fetch requests fail, module scripts do not load, and root-relative paths resolve against the filesystem rather than a site root. Serve the directory with a local static server instead.