Setting Up an Angular 5 site on Github Pages

Getting Started

This article will go over all the steps to setup an Angular site on GitHub pages.  The site will use Angular's AOT compiling and be served from the docs folder of the repository.

To start with you can follow the guide here to setup a new Angular project. Then you will need to setup a repository on Github.com.  The name of the repository doesn't matter, this site will use the docs folder, not the specially named repository with USERNAME.github.io as the name.





Project Changes

After that open up the project in your editor and open the .angular.cli.json file.  Change the "outDir" to "docs".  This is where the files will be created when you build the project.  The contents of .angular.cli.json are shown below with all the changes discussed in the article.

Custom Domain

To use a custom domain for your site you need to create a file name CNAME that contains only the domain name.  The GitHub help page explains how to setup DNS and everything else you need for this.  Create the file in the src folder of your project.  Then you need to add "CNAME" to the "assets" setting in your .angular.cli.json.  You can see this in the example file below.

If your site is using routing and you want the links to pages, other than the home page, to work you will need to setup a custom 404 page on your GitHub site.  There is a help document here explaining how to do that.  If all you do is add a custom 404.html file to the site it still won't make your links work.  For the Angular site to work correctly the easiest way is for your 404.html file to be the index page of your site.  In your src folder make a 404.html file and copy the contents of the index.html file into the 404.html file.  Then in the .angular.cli.json change the "index" setting to 404.html.

This is the .angular.cli.json with all the changes.


Site Setup

Now you are ready to build the site and commit all the changes.  Run the following command in your project folder:

ng build --aot --prod --env=prod

This should create a docs folder with files similar to the following:

Then you need to add all the changed files and commit everything.  Run the following commands to send everything up to GitHub.

git add .
git commit -m 'initial commit'
git push

At GitHub.com on your repository there is a Settings section.  Scroll down to the GitHub pages section.  Change the Source dropdown to the "master branch /docs folder" option.  After this your site should be up and running.  You can access it at your custom domain if you set one up, or the standard GitHub url for your repository.

Here is the output of "ng --version" for the setup used for this article.  Things could change as time goes on, but I am happy to answer any questions in the comments below.  Let me know if anyone has handled the index.html / 404.html situation differently.