To preview a website publicly, publish it with GitHub Pages. For a private check before you push, run the site locally instead. A GitHub repository displays files; GitHub Pages turns a selected source into a hosted static website. A single raw HTML file can also be rendered by a third-party preview service, but that is not the same as testing a Pages build.
Choose the preview that matches what you need to check
There are three useful routes, and they answer different questions. Use a local preview to inspect work before committing or pushing. Use GitHub Pages when you need a shareable, hosted version of the site. Use an HTML-file preview service only when you need a quick look at one simple file and do not need to reproduce the Pages build.
| Method | Best for | What it shows | Who can open it |
|---|---|---|---|
| Local Jekyll preview | Checking a draft before publishing | A local build of a Jekyll-based Pages site | You, on the computer running it |
| GitHub Pages | Sharing and checking the hosted site | The site published from the selected repository source or artifact | Anyone with the Pages URL, subject to the site’s availability and settings |
| HTMLPreview | Quickly viewing one static HTML file | A rendered HTML file, not the complete GitHub Pages build | Anyone with the third-party preview URL |
If your site uses Jekyll, a Pages theme, Liquid templates, or build-time asset paths, local Jekyll or GitHub Pages is more informative than a raw-file renderer. If you only have a small HTML file with its assets already in place, HTMLPreview may be the quickest way to see it.
Preview a draft on your computer with Jekyll
GitHub’s local-testing guide describes building a Pages site locally to preview and test changes. This route lets you catch layout, Markdown, Liquid, and asset-path issues before you publish. It does require a Ruby and Jekyll setup, plus the dependencies declared for the site.
#1 Best Overall
- Open a terminal in the site repository. The repository should contain the site’s Jekyll files, including its dependency declaration if it uses Bundler.
- Install Ruby and Jekyll if they are not already available. Follow the installation instructions appropriate to your operating system and project. Sites can depend on particular versions, so use the versions required by the project rather than assuming any installed version will work.
- Install the declared dependencies. For a Bundler-managed site, run
bundle installfrom the repository directory. Bundler uses the project’s Gemfile and lockfile when present. - Start the local server. Run
bundle exec jekyll servefrom the repository directory. When it reports that the server is running, openhttp://localhost:4000/in a browser. - Make a change and check it locally. Keep the server running while you edit. Reload the page to inspect the result; if the server reports a build error, address that before relying on the preview.
When the local URL has the wrong asset paths
A project site is normally served below a repository path, while the local preview starts at the root of localhost. If _config.yml sets a repository-specific baseurl, local links or assets can therefore behave differently from the hosted version. GitHub’s local-testing guide documents an option to ignore that value while serving locally. Use the documented base-URL override for your Jekyll version when this applies, then check both the local result and the published Pages URL. Do not permanently remove a repository’s production base URL merely to make the local preview work.
What this preview can and cannot confirm
A successful local build is useful evidence that Jekyll can process the site with the dependencies on your computer. It does not prove that GitHub has published the same revision or that the hosted site has identical environment settings. Check the public Pages URL after publishing when the final hosted result matters.
Publish a preview with GitHub Pages
GitHub Pages publishes static website content from a repository. You configure Pages in the repository’s settings, choose its publishing source, and make sure that source includes an entry file. GitHub’s documentation says Pages looks for index.html, index.md, or README.md at the top level of the selected source or artifact.
- Choose the repository and its site files. Put the static site or its supported build source in the repository. Decide whether this should be a user site or a project site before sharing a URL.
- Open the repository’s Settings and find Pages. In the Pages settings, select the publishing source for the site. The selected source must contain an entry file, or Pages will not have the expected page to publish.
- Save the Pages configuration. Allow GitHub to build and publish the selected content. For a site that needs a build process, make sure the configured source or artifact is the output intended for publication.
- Open the matching Pages address. A user site uses
https://username.github.ioand its repository is namedusername.github.io. A project site generally useshttps://username.github.io/repository/. - After pushing an update, wait for publication before diagnosing a stale page. GitHub’s quickstart documentation says a pushed change can take up to 10 minutes to publish. Refresh after the build has completed.
Make sure you are checking the right URL
The difference between a user-site address and a project-site address is easy to miss. If the repository is a project rather than the special username.github.io repository, include the repository name in the URL. Also make sure links to CSS, JavaScript, and images work from that path; a page that opens at the root of a local server can still have broken assets when served below a project path.
What’s actually slowing this PC down?
Pick the symptom - the matching free tool is one click away.
How long does a GitHub Pages update take?
GitHub says publication can take up to 10 minutes after a push. Treat that as a service timing estimate, not a guarantee that every update will take exactly that long. If the old version remains after a push, first allow the Pages build and publication to finish, then reload the correct Pages address. If it still does not update, check that the change reached the selected publishing source and that the site build succeeded.
Preview one HTML file with HTMLPreview
For a single static HTML file, HTMLPreview accepts a GitHub file URL and renders it through a URL in this form: https://htmlpreview.github.io/?<github-file-url>. Use the full GitHub URL of the file after the question mark. This is a convenience for viewing simple HTML, not a complete simulation of GitHub Pages, a Jekyll build, or a custom Actions build.
That distinction matters when the page relies on generated files, templates, or relative paths that depend on the site’s published base URL. A third-party renderer can be useful for a quick visual check, but use the local Jekyll route or Pages itself when you need to validate the actual site build.
Independent reader supportYour contribution helps us test, update, and keep practical guides available for everyone.Or skip the browser setup
If your site is already reachable at a public URL, ScreenshotNeo can capture that published page without you setting up a browser automation tool. It cannot preview an uncommitted local draft or publish a GitHub repository; use local Jekyll or Pages for those jobs.
Best Value
For example, replace the sample URL with your published Pages address and use your ScreenshotNeo access key. See the ScreenshotNeo API documentation for the available request options.
curl -G "https://api.screenshotneo.com/v1/shot" -d access_key=YOUR_API_KEY --data-urlencode url=https://username.github.io/repository/ -o shot.webpBefore capture, ScreenshotNeo accepts the cookie or consent banner as a visitor and removes more than 60 known consent platforms, newsletter popups, and chat widgets; each of these steps can be turned off. Bot checks or CAPTCHAs, blank pages, timeouts, failed loads, and cache hits cost nothing, and the response identifies the page verdict and billing status in headers. Its MCP server offers take_screenshot, get_page_info, and capture_pdf to AI agents and other MCP clients. The free plan includes 1,000 shots a month with no card; paid plans start at $5 for 3,000 shots. Sign up for ScreenshotNeo and get 1,000 free screenshots a month with no card.
Troubleshoot the preview
The Pages URL shows a 404 or no site
- Confirm Pages is configured for the repository and that the selected source contains a top-level
index.html,index.md, orREADME.md. - Check whether the address should be a user-site URL or a project-site URL. A project site’s URL generally includes the repository name.
- If you just pushed, allow the documented publication window of up to 10 minutes and check again after the build completes.
The page opens, but styling or images are missing
- Check the browser’s requested asset paths against the project site’s repository subpath. Root-relative paths that work at
localhost:4000may not point to the right location on a project site. - If Jekyll’s
baseurlis set for the hosted repository, use the local serve override documented by GitHub when testing on localhost; check the hosted page separately. - Make sure the files the HTML references are included in the selected publishing source or artifact.
The local server fails to start or build
- Run the commands from the repository directory, where the Gemfile and site configuration are located.
- Install the project’s declared dependencies with Bundler and use the Ruby/Jekyll versions the project expects.
- Read the first build error reported by Jekyll. A syntax or dependency failure needs to be fixed before the local site can render.
The preview differs from the final site
- Determine whether the preview is raw HTML, a local Jekyll build, or the published Pages result; those methods do not reproduce the same processing.
- Use Pages to verify the deployed output, especially if your site has a build step or path-dependent assets.
- For an HTMLPreview check, limit expectations to the single rendered file rather than the full Pages or Actions environment.
Which method should you use?
For a draft you do not want to publish, run Jekyll locally. For a shareable preview that reflects the hosted static site, configure GitHub Pages and open its user-site or project-site URL. For a quick view of one straightforward HTML file, HTMLPreview can save setup time, but it is not the Pages build. If the hosted page is already public and you need an image or PDF capture, ScreenshotNeo can capture that URL; it does not replace the draft-preview or publishing steps.
Quick Recap
Product prices and availability are accurate as of the date/time indicated and are subject to change. Any price and availability information displayed on Amazon at the time of purchase will apply.
Free tools Windows power users keep installed
One-click scans. No signup required.
