Featured site: Get your life organized with an Erin Condren LifePlannerâ„¢
     Tuesday, January 31, 2023
For men, women, and teens

How to publish and display an html page on GitHub (illustrated)

Twitter share Share on Linked In Face Book Share Pinterest share

Last updated on .

Screenshot of GitHub Pages for publishing html

If you have an html page you want to display as a functional web page on GitHub, this can be done. And yes, you can do it point and click, you don't need to use the command line to set this up. Here is a step-by-step illustrated tutorial for displaying an html page on GitHub.

Typical use cases for publishing an html page on GitHub

The most common use cases why you'd want to do this are:

  1. Your repository is a functional html page itself and you want to display it (for example, you've created a landing page). You want to show users how it looks at a glance in just one click. Or
  2. Example output is generated from your repository that you want to display (for example, you've created a program for generative fiction whose output is in html format). You want to show users example output.

In both cases, you want users to see the html page displayed as a functional page on GitHub in just 1 click, without them having to leave GitHub or download your repository first. You want to make it easy for users to see what they'd be getting.

There are other use cases for publishing html on GitHub, but the above two are the most common. Let's move on and show you how to do this point and click, but first I'll cover a few restrictions you should be aware of.

Restrictions on publishing html pages on GitHub

There are a few restrictions; most are obvious and common-sense.

If you're in the typical use cases I mentioned in the previous section, you should have no problems.

1. Log into GitHub, go to your repository that contains your html

After you log into GitHub.com, go to the repository that contains your html file. In the example below, you can see I called my repository test-html.

Screenshot of a GitHub repository containing an html file and other files

Make sure your html file is called index.html - if not, change its name to index.html. In the image above, you can see it is called test.html so change it to index.html.

Then click on Settings, as shown circled in red towards the top right.

2. After Settings, look for Pages

So after step 1, your screen will look like this.

Screenshot of the repository settings in GitHub

Look for Pages in the menu on the left (circled in red in the image above) and click on that.

3. After Pages, select the branch of your repository (typically main)

After the previous step, your screen will look like this:

Screenshot of the GitHub Pages screen of a repository, showing the branch selection option

Under "Branch", choose the branch of your repository that you want to use the html from, as circled in the image above. This branch will typically be "main" unless you're doing something more complicated. After making the selection, you still have another step, so let's move on.

4. Specify the folder your html is in

At this point, you'll have your branch selected as in the image above. Now still need to tell GitHub where in your repository it's in. Unfortunately, GitHub only gives you 2 options: root or docs so you can't do anything more complicated than that. Most likely your html is in the root of your repository, as is the case for mine in the very first screenshot in step 1, so that's what I've selected here:

Screenshot of GitHub Pages in repository settings, showing folder selection option

Alternatively, you can opt to create a docs folder and put your html file in that, but I prefer not to unless I have a strong reason for doing so.

Then press Save, and you're done!

Finally! To view your published html page

To view your freshly published html page, navigate to the page using the following formula: https://yourgithubusername.github.io/repo-name

In other words, if your GitHub username is Acidity985 and the repository you used for this is called landing-page-test, then you would navigate to https://acidity985.github.io/landing-page-test to view your web page.

Tips and tricks

  1. It always takes GitHub several minutes to update any changes you have made to your html page, including publishing it. So don't worry if you can't see the page right away, just wait and try again.
  2. Likewise, be aware of this delay when making changes to your html file - you'll need to wait awhile for any changes to go live. Yes, this is frustrating. Ideally you would make all your changes offline (on a copy of that file on your local computer) and later upload that file into your repository, replacing the old html file.
  3. You probably want to update your repository's README file to include a link to your published html page. Otherwise no-one else will ever know it's viewable as a published page.
  4. If you have placed or will place your html file in a docs folder instead of the root of your repository, remember to move over any other files needed also such as your css file, images, etc into the docs folder as well.
  5. If your html page is not viewable, double-check the basics: your html file needs to be renamed to index.html, and wait a few minutes to be certain that the changes have had time to go live.

Do you have more complex needs?

This article covered how to publish and display an html page on GitHub in the simplest possible way: manually via the graphical user interface. For the common simple use cases described here such as display of a landing page or of sample html output, this is the quick and easy way to do it via point and click.

However, if you have more complex requirements, here is additional information. If you want to set up a Jekyll site on GitHub, they have one guide here and another here. If you're not planning on Jekyll but have other complex needs, they have a separate guide on GitHub Pages and all its features and in particular GitHub Actions may be of interest to you.

Twitter share Share on Linked In Face Book Share Pinterest share

In: For menFor womentech

↑ top

Worldwide deals we recommend


Find Weird Books at AbeBooks.com

We highly recommend AbeBooks.com for the ease of finding any book: new, used, rare, or collectibles. Check out our Bargain Books page!

Productivity and personal growth

Seeking to get your life on a better track? BestSelf.co has beautiful journals, planners and productivity items which you'll love. They ship to many countries: U.S., Canada, Mexico, U.K., Iceland, Switzerland, Australia, New Zealand, South and Central America. Besides journals, there are also icebreaker decks for talking points, and other items that can help you with relationships.

Artisan-made gifts on Etsy.com

Etsy.com is my number one place for buying gifts for my relatives, whether they live nearby or overseas. You can filter by geographic location or shipping location. Here are some more examples: