How to Preview HTML in GitHub

Short answer: GitHub’s normal file view is not a live HTML preview. Raw HTML is served as text/plain, so the browser displays source code. For a permanent, shareable URL, publish the repository with GitHub Pages. For a one-off check, use a hosted preview service or a local extension. For private or sensitive code, keep the preview on your machine.

Why GitHub shows HTML code instead of the page

A GitHub blob page is a code viewer. Its Raw link returns the file contents, but GitHub sends raw HTML with a plain-text content type. The browser therefore prints the tags instead of interpreting them as a document. The html-preview project documents the same behavior: opening a raw HTML, CSS, or JavaScript file directly from GitHub shows its source code.

To render HTML, the browser must receive it as an HTML document from a web server. GitHub Pages supplies that hosting layer; a local server, extension, or preview proxy can also do it.

Choose the right preview method

Need	Best method	Trade-off
Stable link for teammates or a portfolio	GitHub Pages	Requires repository settings and deployment; a push can take up to 10 minutes to appear.
Fast check of a public file	Hosted HTML preview	No setup, but your source and loaded data pass through a third-party proxy.
Private repository or source privacy	Local Chrome extension or local clone	Runs on your machine; scripts and external assets may need explicit setup.
Full browser behavior	GitHub Pages or a controlled local server	Most faithful for scripts, modules, fonts, and network requests.

Method 1: Publish the file with GitHub Pages

GitHub describes Pages as a static hosting service that takes HTML, CSS, and JavaScript from a repository, optionally runs a build process, and publishes a website.

Put your site in a new or existing GitHub repository.
Make sure the published folder contains an entry file named index.html, index.md, or README.md. For a normal HTML site, use index.html.
Open the repository’s Settings, then Pages.
Under the publishing source, choose a branch and folder, or choose a GitHub Actions workflow that builds your site.
Save the settings and wait for the deployment.
Return to Settings → Pages and select Visit site.

A user or organization site normally uses a repository named <owner>.github.io and appears at https://<owner>.github.io. A project site normally appears at https://<owner>.github.io/<repositoryname>. GitHub says a pushed change can take up to 10 minutes to publish.

Repository layout that works

my-site/
├── index.html
├── styles.css
├── script.js
└── images/
    └── hero.png

Use relative paths such as styles.css and images/hero.png. A project site is served below a repository path, so root-relative URLs such as /styles.css can point at the wrong location. Prefer relative URLs or configure your build tool’s base path.

What GitHub Pages can and cannot run

Pages publishes static files. It does not execute server-side PHP, Ruby, or Python. Move that logic into browser JavaScript or use a build process that emits static HTML, CSS, and JavaScript before deployment. API calls made by browser JavaScript still need a reachable endpoint and must obey CORS rules.

Visibility and secrets

Published Pages sites are publicly available on the internet, including sites built from private repositories under plans that allow private publication. Never place API keys, passwords, private tokens, or other credentials in the repository or generated site. Use server-side code for secrets; a static page cannot keep a secret from its visitors.

Method 2: Preview one public file with html-preview

For a quick check of a public repository, the html-preview project documents a URL pattern that fetches a GitHub HTML file through a CORS proxy:

https://html-preview.github.io/?url=GITHUB_HTML_URL

For example, copy the URL of an HTML file’s GitHub blob page and URL-encode it as the value of url. The service then processes linked scripts, styles, frames, and other assets.

This is a convenience workflow for non-sensitive material. The project’s documentation warns that freely hosted CORS proxies can be a security risk: cookies or localStorage used by a script could become accessible to other repositories opened through the service. Do not enter secrets while previewing, and clear site data afterward if you used it.

Method 3: Preview a GitHub file with a local Chrome extension

The GitHub Local HTML Preview extension adds a Preview button beside Raw on .html and .htm blob pages. It processes the source locally and can work with private repositories that your current GitHub session can already open.

Open the HTML file’s GitHub blob page.
Select Preview beside Raw.
Leave active content disabled for an untrusted file.
Use Allow active content only when you understand the code and need scripts or HTTPS assets.

By default, inline CSS and data/blob assets work while scripts and external resources are blocked. That safer default means a complex app may look incomplete until you explicitly allow the required content.

Method 4: Clone the repository and open it locally

A local clone keeps source and assets on your machine and avoids sending them through a hosted proxy. Open the HTML file in a browser, or serve the directory with the local development server provided by your editor or framework. A local file can behave differently from a deployed site because file:// URLs, browser security rules, module imports, and server-relative paths are not the same as HTTP hosting.

Use a local HTTP server when the page uses JavaScript modules, fetch requests, routing, or server-relative asset paths. Check the browser console and network panel for missing files and CORS errors.

Capture a rendered GitHub page as an image or PDF

Once the HTML is available at a real HTTP URL—usually your Pages URL—you can create a screenshot or PDF for a review, visual regression check, or documentation attachment.

Or skip the browser setup

ScreenshotNeo captures a URL with one request. Give it your GitHub Pages address (or any publicly reachable page) and save the returned image. The API accepts PNG, JPEG, WebP, or PDF output and has options for full-page capture, a CSS element, dark mode, device presets, retina scale, custom CSS and JavaScript, waits, headers, cookies, blocking, resizing, caching, and more. See the ScreenshotNeo documentation for the complete parameter list.

curl -G "https://api.screenshotneo.com/v1/shot" -d access_key=YOUR_API_KEY --data-urlencode url=https://owner.github.io/repository/ -o shot.webp

import requests

r = requests.get(
    "https://api.screenshotneo.com/v1/shot",
    params={"access_key": "YOUR_API_KEY", "url": "https://owner.github.io/repository/"},
    timeout=90,
)
r.raise_for_status()
open("shot.webp", "wb").write(r.content)

const q = new URLSearchParams({
  access_key: 'YOUR_API_KEY',
  url: 'https://owner.github.io/repository/'
});
const res = await fetch(`https://api.screenshotneo.com/v1/shot?${q}`);
if (!res.ok) throw new Error(`Screenshot failed: ${res.status}`);
const buffer = Buffer.from(await res.arrayBuffer());
require('fs').writeFileSync('shot.webp', buffer);

Cookie banners, newsletter popups, and chat widgets are removed before the shot. Bot checks, blank pages, timeouts, failed loads, and cache hits cost nothing, and the response identifies the result with X-Page-Verdict and X-Billed headers. ScreenshotNeo also provides an MCP server with take_screenshot, get_page_info, and capture_pdf tools for Claude, Cursor, and other MCP clients. The Free plan includes 1,000 screenshots per month with no card; paid plans start at $5 for 3,000. Create a free ScreenshotNeo account.

GitHub Pages options and configuration details

Branch and folder versus Actions

Branch/folder: publish an existing directory directly when your repository already contains ready-to-serve static files.
GitHub Actions: build a project first, then publish the generated artifact. This fits static site generators and projects that need a package install or asset compilation.

Custom domains and HTTPS

GitHub Pages can be reached at its default github.io address or a domain you configure in the Pages settings. Verify that links, redirects, and asset paths work under the final path and protocol.

Client-side routing

Single-page applications may return a 404 when a visitor reloads a deep route because Pages serves files rather than performing server rewrites. Use hash-based routing or a build strategy that creates matching static files.

Troubleshooting

Symptom	Likely cause	Fix
Raw HTML shows as text	You opened the Raw URL, which is served as `text/plain`.	Use GitHub Pages, a local preview, or a preview service.
Pages returns 404	There is no entry file in the published folder, or the URL path is wrong.	Add `index.html` and check the selected branch/folder and project-site path.
Changes are not visible	Deployment is still running or the browser has cached the old page.	Check the Pages deployment status, wait up to 10 minutes, then hard-refresh.
CSS or images are missing	Root-relative paths point to the domain root instead of the project path.	Use relative paths such as `styles.css` and `images/hero.png`.
JavaScript works locally but not on Pages	Server-side code, unsupported routes, mixed content, or CORS restrictions.	Move server logic to a backend, use HTTPS endpoints, and inspect the console/network panel.
Hosted preview is blank	The proxy cannot fetch an asset, a script requires a server, or active content was blocked.	Use Pages or a local server for full browser behavior.
Private file cannot be previewed by a hosted service	The service cannot authenticate to your private repository.	Use the local extension or clone the repository locally.
Local extension lacks scripts or fonts	Its safe default blocks scripts and external resources.	Enable active content only for code you trust, or use Pages/local HTTP hosting.
Screenshot captures a loading page	The page needs more time, a selector wait, or network idle before capture.	Configure an appropriate wait in your capture tool and ensure the URL is publicly reachable.

Performance, reliability, and cost considerations

Build time: direct branch publishing is usually simpler; Actions adds a build step but makes generated sites reproducible.
Propagation: plan for up to 10 minutes after a push before a Pages change is visible.
Asset weight: large images and third-party scripts slow both Pages and screenshot capture. Optimize images and remove unused dependencies.
Privacy: a hosted preview proxy receives the page and may expose browser storage to other previews. Keep sensitive repositories local.
Static limitations: Pages has no server-side runtime. Use an API or backend for authentication, secrets, form processing, and private data.
Screenshot cost: with ScreenshotNeo, only clean shots are billed; bot checks, blank pages, failed loads, timeouts, and cache hits are free. Choose caching TTLs and image dimensions that match your review frequency.

Practical checklist

Choose Pages for a durable shareable URL.
Put index.html in the published folder.
Use relative asset paths for project sites.
Keep credentials out of the repository and published output.
Use a local extension or clone for private source.
Use Pages or a local HTTP server when scripts and external assets matter.
Capture the final URL after deployment if you need an image or PDF.

FAQ

Can I open a GitHub HTML file directly without downloading it?

Yes, but not by opening its Raw URL as a live page. Use GitHub Pages, a preview extension, a hosted preview service, or a local clone.

Does GitHub Pages support PHP or Python?

No. Pages serves static output. Run server-side PHP or Python elsewhere and have the static page call that service.

Can I preview HTML from a private repository?

Use the local extension or a local clone. A public hosted proxy is not appropriate for confidential source.

Why does my page look different in a preview extension?

Extensions may block scripts and external resources by default. A deployed site or controlled local HTTP server provides a more complete browser environment.

What URL should I give a screenshot API?

Give the deployed HTTP(S) URL, such as your GitHub Pages project URL, rather than a GitHub blob or Raw URL. The page must be reachable by the capture service.