📍 The GitHub Pages Guidepost

If you’re just getting started with GitHub Pages but don’t know where to start, you’ve come to the right place.

Here’s a collection of topics, solutions and resources organized as an additional resource to the documentation to help you get started.

Featured Co-author: @ernest-phillips

Official Documentation

Getting Started with GitHub Pages

Commonly asked questions when creating a GitHub Pages site

Why is one or more parts of my Pages site showing a 404 Not Found or not updated with the latest content?

How do I add new HTML pages to my Pages project?

You can add new HTML pages to the repository and cite them in the respective paths, being mindful of absolute versus relative paths as illustrated in this topic. Check out MDN Web Docs’ What is a URL? - Absolute URLs vs relative URLs for more information.

There are three types of GitHub Pages sites: project, user, and organization. The source files for a project site are stored in the same repository as their project. Unless you’re using a custom domain, project sites are available at http(s)://<username>.github.io/<repository> or http(s)://<organization>.github.io/<repository>. Ensure that GitHub Pages are setup for those repositories as well if you’d like to have those repositories accessible using this URL structure.

Why are my assets/resources not rendering?

Case sensitivity:

On Pages sites, URLs are case sensitive. To avoid the issue of a rendered but blank site, ensure that any references point to the correctly cased path.

Absolute versus relative paths:

Depending on where the assets are stored, it may be a case of updating the absolute path to a relative one (or, the other way around)). Check out MDN Web Docs’ What is a URL? - Absolute URLs vs relative URLs for more information.

Here are some example topics showcasing instances of different resources not rendering:

Themes: how do you add or remove them?

Are there any known limitations to Pages?

Here are some examples:

You’re welcome to share any product feedback about GitHub Pages with our product team and consult our public roadmap for any upcoming features.

Setting up a GitHub Pages site with Jekyll

Configuring a custom domain for your GitHub Pages site

Commonly asked questions when troubleshooting custom domains and GitHub Pages

If you found something helped you, help our community by acknowledging it as a solution.

What’s something that you found most helpful from this list? Is there a collection of existing topics with solutions that you’d like to see posted here? Leave a comment below!


Hosting a single page application (SPA) with GitHub Pages is tricky, because the routes are virtual, i.e. not backed by actual files. This will result in 404 errors because GitHub Pages won’t find a corresponding file based on the URL path. The SPA routing will work if you start at the homepage, because that page is actually file based and subsequently takes over the routing. But it won’t work if you start at any other virtual page, unless you use a clever workaround utilizing the custom 404 page feature: GitHub - rafgraph/spa-github-pages: Host single page apps with GitHub Pages

That’s a great point to bring up, @Simran-B! I was interested in learning more about this and asked one of my teammates more familiar with Pages to help illuminate me in this area. They’ve tackled a handful of topics related to GitHub Pages and shared some interesting themes (and their associated topics) around building single-page applications with the feature.

I’m sharing it on their behalf to expand on the conversation and to see what others think about these approaches (and perhaps, alternatives for handling these interesting cases :wink: ).

Blank homepage/assets not loading

When the Pages project is successfully deployed but a blank homepage appears or assets don’t load, there’s a likelihood that the repository name is missing from the site’s asset URLs. In this case, fetching a specific asset will return a 404 Not Found.

While the following topics mostly apply to React, they could apply to other SPA frameworks:

Ensuring npm run deploy is run as a part of the build process

There are cases when someone may push changes to their site but forget to run the deploy step (via npm run deploy). Sometimes, this may be necessary in order to push to the Pages source branch (which is configurable per repository). Running the appropriate deploy command may help:

Configuring the publish source for the compiled site

One may find that the Pages site is serving the source code rather than the compiled site. It’s possible to configure the publishing source for your GitHub Pages site appropriate to the project’s setup:

Software Router Issues

As @Simran-B mentioned earlier, routing can be tricky! Routers vary from project-to-project as they do framework-to-framework. This may cause issues such as capturing traffic for other sites and redirecting to the wrong one, or not resolving routes correctly. There are some related topics on this theme, and we’ll share them here for perspective (rather than them being authoritative sources for being the “only” way to do it):

1 Like