A Simple Guide to Hosting a Website on GitHub

Create a portfolio website and host your frontend apps on GitHub with a few simple steps.

What Are GitHub Pages?

GitHub pages are free way to host your webpages and frontend apps. Each GitHub page you make will host content from an associated repo. Pages come in two types: User & Organization Pages, and Project Pages.



User & Organization Page

  • This is your main wesite/app/webpage. Any other projects/apps/sites you create will be subdomains of this page and will be Project Pages.
  • Only one User and Organization Page is allowed per account.
  • Your repo must be named username.github.io. Make sure you use your exact GitHub username.
  • The page will be served under the address username.github.io


Project Pages

  • You can have any number of Project Pages.
  • You will need to create a "gh-pages" branch of a repo in order to make it a Project Page.
  • Project Pages are served under subpaths of the User Page like so: username.github.io/projectname

Tips

  • Read more about GitHub Pages on GitHub Pages Help
  • GitHub Pages are served over HTTP not HTTPS.

Keep in Mind

GitHub is generally suitable for hosting frontend apps that only run in the browser. It will not run server-side code or provide a SQL database.
You can use Angular, jQuery, and other Javascript frameworks. You can use AJAX calls to connect to firebase or other remote servers.
You can include images, pdfs, and other content related files in your repo and link to them in your HTML.
Search Google for suggestions on getting your server side code live on the web, that topic is outside the scope of this guide.

How To Setup a User Page

  1. Add a new repo, and name it username.github.io. username should be your username.
  2. Add the files that will make up your site to GitHub.
    • If you are using Visual Studios you can connect your solution to your repo in the usual way.
    • Otherwise use a version of Git (command line, for Windows, etc.) to clone a local copy of the repo to hold your site's files.
  3. Thats it, your site is now hosted! There may be a delay of up to ten minutes before your page is accessable on the web.
  4. Once your site is ready you can naviage to http://username.github.io to view your User Page.
  5. In the repo for your User Page, just above the list of contents, you can add a description and website link for the live site.

Tips

  • Make sure to check intenal links (href, src, script tags, etc.) to ensure they are all working.
  • If you are using relative paths you may need to make slight adjustments to find your targets.
  • Unlike a Project Page, the User Page's content is based off the master branch. You do not need to make a gh-pages branch.

How To Setup a Project Page

  1. Create a repo and add the files your app needs.
  2. The name of your repo will be used in the URL to access you site. The url will look like: username.github.io/project_page_repo_name
  3. Your site will not be live (accessable by it's URL) until you create a new branch called "gh-pages".
    • From the repo for your project, click on button: "branch: master". In the textbox that drops down type gh-pages and press enter.
    • A new branch will be created and your page will be accessable in a browser within ten minutes using its URL.

Tips

  • Remember: Only changes to the gh-pages branch of a repo will be reflected on a Project Page.
  • One option for updating your gh-pages branch with changes that have already been made to another branch is to merge branches.
  • GitHub Help page for merging branches.
  • A Project Page can link to script, stylesheet, and other files on your User Page.
Top