If you already have a set of HTML, Javascript and CSS pages ready to go and want to host it some place, GitHub Pages tied to a repository may not be a bad way to host it easily. This post explains what I did to achieve exactly that.

I already use Jekyll to host my site but not on GitHub Pages. The problem I wanted to solve was as below.

I recently wrote a post about using CSS filters to style OpenLayers maps and wanted to find a way to share the code that people could access. So, yes, it made sense to host it on GitHub. But since the code was practically just an HTML file with JS and CSS, it also made sense to put it online so that someone could also see what the page looks like in a browser. I didn’t want to go through a setup where I needed to upload the HTML files to a repository on GitHub for people to access but then also have to put it up on a host as HTML so that people can view the pages. That’s when it seemed like looking at GitHub Pages might be sensible.

You can see the general quick start guide to GitHub Pages on landing page but there were a few things that I wanted to do differently:

• I did not want to use Jekyll
• I wanted it to be a custom domain name
• I wanted to be be able to have some other files also, if needed
• I wanted it to be simple

The Solution

There are three parts to this:

• Repository organisation
• GitHub Pages Custom Domain
• Linking everything up

Repository Organisation

This is how the repository was set up:

• Create a repository that will hold the pages that you want. In my case, this was openlayers-recipes
• I added files such as README.MD that explain the purpose of the repository for people who come to the repository
• I created a docs folder to hold the actual HTML, CSS and JS files. The reason for doing this is: GitHub Pages can serve raw HTML files either from the root of the repository or from the docs folder. So, I chose to create a docs folder – this is the easy way.
• Next, I added files under docs – there must be an index.html will serve as the landing page. Other than that, you can decide where your Javascript, CSS and image files go – I added folder js, css and img for these. Some people prefer to put these under another folder called assets or resources so the paths to these files might become assets/js or resources/css – the folder hierarchy does not matter to GitHub Pages. It’s important only for you to remember to point paths correctly.
• I also prefer to use a separate folder for each post/ page – so, I ended up with folders such as 02_grayscale-maps that have an index.html under it with the code. This would then translate to a path of site.example.org/02_grayscale-maps/ when accessed.
• Now, on to configuring GitHub Pages

GitHub Pages Custom Domain

I wanted to use a custom domain, and this is best added before you configure GitHub Pages.

• Decide what the domain name will be. I chose openlayers-recipes.onghu.com
• Then, I followed the instructions here to verify the domain (this shows GitHub that you own the domain)
  • Logged in to my registrar’s domain management portal and created a TXT record according to the information that GitHub asked me to
  • Saved the changes
  • Waited for GitHub pages to recognise the changes that had been made
• I did this for a sub-domain, so I also had to follow the instructions for configuring a subdomain in the DNS setup
  • Set a CNAME record to point openlayers.onghu.com to mohits.github.io – note: always, the user name and nothing about the repository

Linking everything up

This is what I did then to finally link the repository to the domain via GitHub Pages:

• Go the settings page of the repository and find the link to Pages – should be under Code and Automation on the left
• In the source, choose the drop-down and select Deploy from a branch
  
• This then brings up the option below in which you should select you main branch
  
• Finally, ensure that you select /docs and click on Save
  
• If you did set up the custom domain, you can now enter that in the Custom Domain field and save it:
  

If all is done, you should now be able to view your site on the custom domain page after a while. So, now:

• I can invite them to see the pages live at https://openlayers-recipes.onghu.com or to a specific page like https://openlayers-recipes.onghu.com/02_grayscale-maps/index.html
• They can also get the raw HTML file from the mohits/openlayers-recipes repository on GitHub

Since both are served from the same repository, changes are always in sync without extra effort for me.

Feel free to share the post (you can start a conversation or tag me as @onghu on X or on Mastodon as @onghu@ruby.social ) or leave a comment below.