Skip to content

github pages

Jump to bottom
Andrew Hick edited this page Nov 26, 2025 · 4 revisions

This page covers how to set up a basic GitHub Pages site, and do things like redirects on it. This page already assumes you know the basics of using Git and writing webpages.

In short, the steps are:

  • create a site, by creating an username.github.io repository, then either
  • add subfolders and pages to that repository
  • OR create separate repositories which will deploy to your site

Some terminology:

  • Jekyll is the static site generator that underpins GitHub Pages - you'll probably spot references to this
  • GitHub Actions is the tool used to deploy your pages to live

Set up a new GitHub Pages site

Follow the GitHub guidance on Creating a GitHub Pages site.

Site setup in brief:

  • Create a new repository for your username or organisation, for example andrewhick / andrewhick.github.io
  • Create a readable webpage in the root directory, like an index.html file - this will appear as your homepage (for example, andrewhick.github.io). If there's no index.html file, a README.md file will also work.
  • Specify that you want to publish from the main branch - see Configuring a publishing source for your GitHub Pages site

Then, under the default configuration, when you make changes to main, a GitHub Action will run to publish your page.

Add folders and pages

You can then add folders and pages to your github.io repository. For example, if you add a subfolder called pages containing an index.html file, you can access it by going to /pages from your site homepage.

Starting page

Here is a really basic index.html file you can use to start you off.

<!DOCTYPE html>
<html lang="en">
  <head>
    <title>Hello world!</title>
    <style>
      body { color: #333; font-family: "Helvetica Neue", Helvetica, Arial, sans-serif; padding: 40px; }
      a { color: #2b8cc4; }
      p { font-size: 1.4em; line-height: 1.5em; max-width: 66%; }
    </style>
  </head>
  <body>
    <nav><a href="../">Home</a></nav>
    <h1>Hello world!</h1>
    <p>
      Here is my GitHub Pages page.
    </p>
  </body>
</html>

Deploy from a separate repository

To deploy to GitHub pages from a separate repository, for example pages-test, follow GitHub's guidance on Creating a repository for your site.

Set up a redirect

If you want to redirect from your page to somewhere else, you can add the following to your home page:

Within the <head> tag:

<meta http-equiv="refresh" content="0; https://www.andrewhick.com/">

Within the <body> tag:

<p>If your browser doesn't automatically redirect you, please go to <a href="https://www.andrewhick.com/">AndrewHick.com</a>.</p>

Rename a repository

If you rename a GitHub repository, any links to the main GitHub repository will automatically redirect.

However, any GitHub Pages sites will not automatically update. You will need to set up a redirect on GitHub Pages yourself.

The following instructions assume that you are renaming a repository from pages-old to pages-new on the site example.github.io, and that you're using the default configurations of GitHub Pages and Actions.

  1. Within the pages-old repository, prepare a pull request to reflect the name change. For example, make sure that all the content, URLs and the site configuration reflect the new name.
  2. Within the example.github.io repository, start working on a pull request.
  3. Add a subfolder for the old address, for example example.github.io/pages-old.
  4. In this subfolder, add an index.html file containing a redirect to example.github.io/pages-new using the "Set up a redirect" steps above.
  5. Submit the pull requests for review and approval, but don't merge them until you're ready to complete the rename.
  6. The remaining steps should all be done as close as possible to each other, to minimise downtime.
  7. On the agreed renaming date, merge both pull requests around the same time.
  8. Wait a few minutes for GitHub Actions to run in both repositories.
  9. Check if example.github.io/pages-old redirects to /pages-new - however this page won't exist yet, and you will get a 404 error message.
  10. Rename the pages-old repository in GitHub to pages-new.
  11. Wait a few minutes for GitHub Actions to deploy the site to the new address.

Then check that:

  • example.github.io/pages-new contains the updated content that was originally in pages-old
  • example.github.io/pages-old redirects to /pages-new, which now works - if it doesn't work straight away it's worth trying this from a fresh browser or deleting your cache, as the previous version of the page will probably be cached and you won't be able to refresh it due to the redirect
  • github.com/example/pages-old redirects to github.com/example/pages-new, along with any wikis
  • internal links within example.github.io/pages-new still work

You will also need to update any references to pages-old from elsewhere.

Clone this wiki locally