GitHub is currently the most popular tool that companies and individuals use to host and version control source code repositories. The platform itself has been constantly improving developer experience and keeps launching new features to enhance automation and encourage even more collaboration between dev teams. GitHub Actions — the integrated CI/CD tool — and Codespaces, a cloud dev box, are just a few of these toolsets.
GitHub Pages is another powerful tool that lets you host websites from GitHub repositories and make them publicly available or even keep them privately accessible within your team and organization.
From your personal website and portfolio to your project’s documentation, GitHub Pages can help you launch static websites in a matter of minutes. The good thing with GitHub actions is that you don’t have to worry about server management or database configuration — GitHub will take care of all of this. You will even get a URL in the form
https://.github.io that you can share with the world to make your website(s) accessible to others.
But how do you do that? Well, I promise it’s not going to take more than a couple of minutes. In the following sections I’m going to outline a step-by-step process you can follow to get started with GitHub Pages and bring your first GH-hosted website to life.
1. Create a GitHub Repository
Login to your GitHub account and create a new public repository named
<username>.github.io where the username should either be your personal GitHub one or the one your organization uses.
2. Clone the Repository on Your Local Machine
Now that you’ve created the public repository on GitHub, you’ll then have to clone it to your local machine. To do so, simply open the terminal and run the following command (in whatever directory/folder you prefer):
git clone https://github.com/username/username.github.io
Again, make sure to replace the
username references to your own GitHub username. Note that, while cloning the repository, you will get the following warning message
Cloning into 'gmyrianthous.github.io'... warning: You appear to have cloned an empty repository.
This is absolutely fine, however, given that the repository is currently empty. So, let’s move on to the next step.
3. Create an Index.html File in Your Project’s Directory
Now head to your recently cloned repository, create an
$ cd <username>.github.io $ touch index.html $ echo "Hello, world! This is my personal page hosted on GitHub pages." > index.html
And let’s double-check that the content we have just appended to the
index.html file is indeed there:
$ cat index.html Hello, world! This is my personal page hosted on GitHub pages.
4. Push the Local Changes to the Remote Host
Now that we have created the index file that is supposed to be presented on the website, we need to create a commit and push it to the remote host. To do so, let’s run the following commands.
$ git add index.html $ git commit -m "Add index.html file" $ git push -u origin main
5. Open a Browser and Observe the Magic
Open your preferred browser and voila! Your page should now be hosted through GitHub Pages and publicly accessible to the outside world.
Note that if you attempt to access the page immediately, you may get a 404 error. Just be patient and wait for a minute or so and you will then be able to access your page.
6. Customizing the Deployment of Your Page
Note that, by default, GitHub Pages will deploy the content of your repository from the main branch. If you’d like to alter this behavior, take these steps:
- Click on the repository settings tab.
- From the left-hand side menu, click Pages under the Code and Automation section.
- In the Build and Deployment section, choose the branch (and optionally sub-directory) from which you would like GitHub Pages to deploy your website.
Using a Custom Domain
Note that GitHub Pages supports the use of custom domains as well as the change of the root URL to any sub-domain you own. It supports the following three types of domains:
- www subdomain (e.g., www.mysite.com )
- Custom subdomains (e.g., portfolio.mysite.com )
- Apex domains (e.g., mysite.com)
To alter the default domain:
- Click on the repository settings tab
- From the left-hand side menu, click Pages under the Code and Automation section
- In the Custom domain section, pick your custom domain
Get Started With GitHub Pages
If you are looking to host static websites easily and for free, look no more — GitHub Pages should be among the top options on your list. Whether it comes down to your personal website or project page, you can use this guide to get it up and running in just a few minutes.