How to Preview a Website on GitHub

Short answer: use GitHub Pages when you need a public preview URL, run Jekyll locally when you need to check the exact Pages build before pushing, and use HTMLPreview only for a quick rendering of one static HTML file. A repository by itself stores source files; GitHub Pages builds and hosts the website.

For a user site, create username.github.io and open https://username.github.io. For a project site, open https://<user>.github.io/<repository>/. The selected Pages source must contain index.html, index.md, or README.md. A pushed change can take up to 10 minutes to publish.

Choose the preview that matches your goal

Goal	Best method	What you get
Check a draft privately	Local server or Jekyll	Immediate, private preview at localhost
Preview the real GitHub Pages build	Jekyll locally, then GitHub Pages	Build and asset paths close to production
Share a working URL	GitHub Pages	Public URL tied to your repository
Render one plain HTML file	HTMLPreview	Third-party URL for a simple static file
Capture a clean image or PDF	ScreenshotNeo	Automated screenshot or PDF without maintaining a browser

1. Preview a plain HTML site locally

If your repository contains static HTML, CSS, and JavaScript and does not need Jekyll, start a local HTTP server from the repository root. Opening the file directly with file:// can hide path and browser behavior problems, so use HTTP instead.

Python

cd my-site
python3 -m http.server 8000

Open http://localhost:8000/. Stop the server with Ctrl+C.

Node.js

cd my-site
npx serve .

Open the local URL printed by serve. This checks relative links, CSS, JavaScript modules, and fetch requests under HTTP.

Quick checklist

• Put the entry file at the server root as index.html.
• Use relative asset paths such as ./styles.css and ./images/photo.png.
• Open browser developer tools and fix console errors and failed network requests.
• Test navigation, forms, responsive breakpoints, and JavaScript that calls an API.
• Check the page at the same URL depth you will use on GitHub Pages, especially for project sites.

2. Preview with GitHub Pages

GitHub Pages publishes static content from a repository. GitHub’s documentation describes it as hosting directly from your repository: edit, push, and the changes become live after the Pages build completes.

Configure Pages in the repository

1. Push your site to a GitHub repository.
2. Open the repository and select Settings.
3. Open Pages in the Code and automation section.
4. Under the publishing source, choose the branch and folder that contain your site (for example, the main branch and /(root)).
5. Save the configuration and wait for the deployment workflow to finish.
6. Open the URL GitHub displays in the Pages settings.

GitHub Pages looks for index.html, index.md, or README.md at the top level of the selected source (or in the generated artifact). If none exists, add an entry file or change the source folder.

User site versus project site URLs

Site type	Repository name	Typical URL
User site	username.github.io	https://username.github.io
Project site	Any repository name	https://username.github.io/repository/

Project sites live below a path. Absolute asset URLs such as /styles.css point at the domain root and often break there. Prefer relative URLs or set the correct Jekyll baseurl.

How long does GitHub Pages take to update?

GitHub says a pushed change can take up to 10 minutes to publish. First confirm that the Pages deployment completed, then hard-refresh the page and check the deployment log. A browser cache or a service worker can make an older page appear after the deployment is already complete.

3. Run the GitHub Pages build locally with Jekyll

Use this path when your site has Markdown, Liquid templates, collections, plugins supported by Pages, or a _config.yml. GitHub’s local-testing guide recommends installing Ruby and Jekyll, using Bundler for dependencies, and serving the result at http://localhost:4000/.

Install and serve

# From the site repository
bundle install
bundle exec jekyll serve

Open http://localhost:4000/. Keep the server running while editing; Jekyll rebuilds changed files and reports errors in the terminal.

Respecting a project-site base URL

A project site commonly sets baseurl in _config.yml. That value is needed on GitHub Pages but can make local links awkward. GitHub’s local-testing instructions provide an option to ignore it while serving locally:

bundle exec jekyll serve --baseurl ""

Use the setting that matches what you are checking. Test once with the production base path as well, because a link that works only at the domain root can still fail after deployment.

Minimal Jekyll structure

.
├── _config.yml
├── _layouts/
│   └── default.html
├── _posts/
├── assets/
│   └── css/style.css
└── index.md

# _config.yml
baseurl: ""

---
layout: default
title: Home
---

# My site

This page is generated by Jekyll.

4. Preview a single HTML file with HTMLPreview

For a simple static file, HTMLPreview can render a GitHub file through a URL in this form:

https://htmlpreview.github.io/?<github-file-url>

Replace the placeholder with the encoded GitHub file URL. This is convenient for a one-file demo, but it is a third-party renderer. It does not reproduce your GitHub Pages Jekyll or Actions build, repository routing, custom domain, or server-side behavior.

5. Verify the preview before sharing

1. Entry point: confirm the selected source contains index.html, index.md, or README.md.
2. Paths: open the deployed CSS and JavaScript URLs directly; a 404 usually means a leading slash or incorrect baseurl.
3. Build output: read the Pages deployment log for Markdown, Liquid, or dependency errors.
4. Browser behavior: check the console for mixed-content, CORS, module, and JavaScript errors.
5. Responsive layout: test narrow and wide viewports, touch interactions, and reduced-motion behavior.
6. Links: click internal links from both the home page and a nested page; project-site paths expose mistakes quickly.
7. Freshness: compare the commit shown in the deployment with the commit you intended to publish.

6. Troubleshooting GitHub previews

Symptom	Likely cause	Fix
404 at the Pages URL	Pages source is wrong or there is no entry file	Check Settings → Pages, branch, folder, and add index.html, index.md, or README.md.
Old content is still visible	Build is still running or browser/service-worker cache	Check deployment status, wait up to 10 minutes, then hard-refresh or clear the relevant cache.
CSS and images return 404	Root-relative paths ignore the project-site subdirectory	Use relative paths or configure Jekyll’s baseurl and generate URLs with relative_url.
Jekyll fails locally	Missing or mismatched Bundler dependencies	Run bundle install, then serve with bundle exec jekyll serve; read the first error in the terminal.
Markdown or Liquid appears as text	Front matter is missing or malformed	Put valid YAML front matter between the opening and closing --- lines.
JavaScript works locally but not on Pages	Incorrect base path, module URL, or HTTPS restriction	Inspect the deployed request URLs and browser console; use HTTPS API endpoints and correct project paths.
HTMLPreview is blank	The file needs a build step, server-side data, or blocked resources	Use a local server or GitHub Pages; HTMLPreview is for simple static files.
Changes never deploy	Push went to another branch or the workflow failed	Confirm the branch selected in Pages and inspect the Actions or Pages deployment log.

7. Performance, reliability, and cost considerations

• Local preview: fastest feedback and no hosting dependency, but only you can access it.
• GitHub Pages: produces a shareable URL and repeats the repository build, but a push is asynchronous and may take up to 10 minutes to appear.
• HTMLPreview: has almost no setup for one file, but adds a third-party dependency and does not emulate Pages.
• Build size: compress images, remove unused JavaScript, and avoid loading large assets on every page so the public preview becomes interactive sooner.
• Dynamic features: GitHub Pages serves static output. Put forms, databases, authentication, and server-side rendering behind an appropriate external service.
• Custom domains: GitHub Pages supports custom domains; configure the domain after the default Pages URL works.

Or skip the browser setup

If the goal is a repeatable screenshot or PDF rather than a human review session, ScreenshotNeo accepts one GET request and returns PNG, JPEG, WebP, or PDF. See the ScreenshotNeo API documentation for the complete option list.

curl -G "https://api.screenshotneo.com/v1/shot" -d access_key=YOUR_API_KEY --data-urlencode url=https://username.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://username.github.io/repository/"}, timeout=90)
open("shot.webp", "wb").write(r.content)

const q = new URLSearchParams({ access_key: 'YOUR_API_KEY', url: 'https://username.github.io/repository/' });
const res = await fetch(`https://api.screenshotneo.com/v1/shot?${q}`);

Before capture, cookie and consent banners, newsletter popups, and chat widgets are removed. Bot checks, blank pages, failed loads, timeouts, and cache hits are not billed; response headers identify the page verdict and whether it was billed. An MCP server provides 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 to capture up to 1,000 screenshots a month without a card.

FAQ

Can I preview a private GitHub repository with GitHub Pages?

Pages availability depends on your GitHub plan and repository visibility. If the published site cannot be public, use a local server or a private preview workflow appropriate for your organization.

Does GitHub display an HTML file as a webpage in the repository view?

The repository view is for source code. Use GitHub Pages for a hosted site or HTMLPreview for a quick rendering of one static file.

Why does my project URL include the repository name?

That is the project-site URL format: https://username.github.io/repository/. Only a repository named username.github.io uses the user-site root URL.

Should I use Jekyll if my site is only HTML, CSS, and JavaScript?

No. A plain local HTTP server and a Pages source containing index.html are enough. Add Jekyll when you need Markdown, Liquid, collections, or a generated build.

Can a screenshot prove that the latest commit is live?

Only if you first verify the Pages deployment commit and then capture the deployed URL. A screenshot of localhost or an old cached page does not establish which commit is published.