GitHub Pages: A Complete Tutorial

What is GitHub Pages?

GitHub Pages are public web pages for users, organizations, and repositories, that are freely hosted on GitHub’s domain or on a custom domain name of your choice. GitHub Pages are powered by Jekyll behind the scenes, so they’re a great way to host your Jekyll-powered website for free.

Your site is automatically generated by GitHub Pages when you push your source files. Note that GitHub Pages works equally well for regular HTML content, simply because Jekyll treats files without front matter as static assets. So if you only need to push generated HTML, you’re good to go without any further setup.

The GitHub Pages Documentation is comprehensive and includes a a guide to setting up a GitHub Pages site using Jekyll. We recommend following this guide.

This page contains some additional information which may be useful when working on GitHub Pages sites with Jekyll.

GitHub has a feature called GitHub Pages, which makes it easy and free for you to create a multi-file website hosted at

What is the use of GitHub Pages?

GitHub Pages offers a lot of features and flexibility, all for free. Some of the benefits include:

  • Easy setup
  • Seamless collaboration using Git and GitHub
  • Free hosting with >95% uptime
  • Live updating with normal GitHub workflow

Types of GitHub Pages

There are two types of GitHub Pages:

  • User/Organization Pages (https://<USERNAME|ORGANIZATION>
  • Project Pages (https://<USERNAME|ORGANIZATION><PROJECT>/)

Please refer to the GitHub Pages documentation to decide which type of site you would like to create as it will determine which of the below methods to use.


Github Pages are a feature of GitHub that allows users to host static websites for individuals, projects, or organizations from a repository


  • Dynamic ones have pages that are generated in real-time
  • Static ones have pages that are converted (or written directly) as static HTML.
  • Does this mean it is also static vs. ‘interactive’? No, doesn’t have to be the case!


  • Free!
  • Static sites are more secure(ish*)
  • Manage all the different content for your project(s) in the same place and etc.




  1. Create a new repository (
  • There are 4 types of GitHub Pages site (in the table above and on GitHub)
  • following naming conventions is really important! for user and organizations

2. Navigate to Settings and click Automatic Page Generator
Or just go to generated_pages url for your repository:<username>/<repository>/generated_pages/new

  • Make some edits to the content
  • Select a theme/layout
  • Publish!

3. We have a website!

  • Let’s check it out

4. Make an update

5. Check out the commit history

Getting started with GitHub Pages

Steps to use GitHub pages in our repository

1. Create a GitHub Repository

Login to your GitHub account and create a new public repository named <username> 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

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 ''...
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 index.html file

$ cd <username>
$ 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.

It supports the following three types of domains:

  • www subdomain (e.g., )
  • Custom subdomains (e.g., )
  • Apex domains (e.g.,

If you’d like to alter this behavior, take these steps:

  1. Click on the repository settings tab.
  2. From the left-hand side menu, click Pages under the Code and Automation section.
  3. In the Build and Deployment section, choose the branch (and optionally sub-directory) from which you would like GitHub Pages to deploy your website.

For full detail of Github Page, Click here.

Deployment on GitHub Pages

Deploying to GitHub Pages is automatic. Once it’s set up, deploying happens whenever you push your local changes to your remote, GitHub-hosted repository. Head to GitHub Pages’ setup instructions and follow the steps exactly to get your main GitHub Pages page setup.

When you first navigate to your newly deployed site it is possible that you will receive a 404 error. If this happens, and you are confident that you have followed all the steps as written, check back in 30 minutes to see if the deploy has successfully gone through.

Viewing Your Live Web Page

That’s it! Your website is deployed to the Internet! You and anyone with whom you share this link can view your project by navigating in your browser to the URL http://<your-github-username>

Adding GitHub Pages Projects

Since GitHub Pages runs from a *.html file in your GitHub repo, you need to make sure your code is actually on GitHub. You can set up your GitHub Pages to deploy every one of your repositories in addition to <username> This will allow you to ensure all of your sites are deployed automatically whenever you push to GitHub.

In GitHub, navigate to your <username> repository and click Settings.

Within Settings, navigate to the Source section within the Github Pages section. From the dropdown menu, select master branch and then click Save.

Now, all of your repositories can be found at http://<username><repository-name>. Try creating a new repo with an HTML project inside it (perhaps push an old project to GitHub) and then navigate to the deployed page.

Deploying New Changes

Now that your GitHub Pages site is set up, deploying new changes is easy. Every time you make a change to your site, use the normal GitHub flow. That is, use git commit and git push to send your changes to GitHub. After this, the GitHub site should update within a few seconds. Just refresh the page in your browser, and you’re good to go!

Development steps in shorts:

As testing purpose i have tried with existing repository JsonBasedDynamicUi_kotlin and add a new file(index.html) and under this file add a text with H2 Html tag and commit this changes.

After commit just go to setting page and click on Page section.

Here i have already done it but for first time just tap on branch section and select master or main branch and after that click on save.

After save a link will be generated and it will show the top of the page.

When you click on Visit site it will show the content what you have saved in index.html file. Here i have only mention my name so it is showing when i tapped.

Like as

Generated page you can open any where and any browser, So using this step your static site will be available for everyone.

Thanks for reading.



Abhishek Srivastava

Abhishek Srivastava


Senior Software Engineer | Android | Java | Kotlin |Xamarin Native Android |Flutter |Go