Not all launches go as smoothly as planned, and launching this blog wasn’t as easy as I though it would be. I had already setup Jekyll and a github repository to host my static pages, but something was off… I couldn’t serve them from the base url https://aclima93.github.io as I had initially planned, at least not yet. 🤨
# Limitations
It turns out that while GitHub offers free static page hosting, and even integrates nicely with Jekyll, it has some safety limitations in place. Here’s the gist of it:
- you can enable “Github Pages” for any repository (private or public) and they will be publicly available from
<username>.github.io/<repository_name>(project Github Page) - if you want a page to be served from
<username>.github.io(personal Github page) you have to create a<username>.github.iorepository and enable “Github Pages” on it - github will serve whatever HTML you have on your repository under the
masterorgh-pagesbranches - you can configure your project’s “Github Pages” to be served from the
docs/directory instead of the root of your repository, but not for your personal “Github Page” - github will ignore your
_site/directory if you push it - github will ways attempt to serve your website by building it with Jekyll unless you provide a
.nojekyllfile in the root of your repository - github will run Jekyll using the
--safeflag, so that only pre-approved extensions will be run - github pages does not allow you to use Jekyll’s Generators (we talked about them )
And… I don’t think I missed anything but just in case, here’s the official documentation for all of these tidbits.
So, you must be wondering, what’s the big deal with these limitations? Well, there’s plenty of problems if you want to build more than just a simple Jekyll website, as you’ll soon find out 😅
# Issues Issues Issues
When I first started this website, I didn’t quite realize how much those limitations would limit my creativity right off the bat.
- you can enable “Github Pages” for any repository (private or public) and they will be publicly available from
<username>.github.io/<repository_name>(project Github Page)- if you want a page to be served from
<username>.github.io(personal Github page) you have to create a<username>.github.iorepository and enable “Github Pages” on it
Firstly, being the programmer that I am, I want to keep track of how I’ve built this website, that means having a repository for its code, but I also want to be able to serve it from aclima93.github.io and not from aclima93.github.io/Blog (it just doesn’t have the same nice ring to it), and I don’t want to have the former just forwarding my single-digit-readers to the latter. I want aclima93.github.io.git to be my blog and aclima93.github.io/Blog.git to be the host of code I use to build the blog.
Secondly, I want to be able to use Jekyll’s Generators and “unsafe” plugins to build my website. Don’t get me wrong, Github has made a fine selection of the “safe” plugins and they should be more than enough for anyone that just wants an medium to share their thoughts. But for those of use that like to tinker with and break stuff, it’s just not as appealing. I had already built some features (read time estimate, and post categories and tags) using generators and “unsafe” plugins, and already had plans for adding more features in the same way.
The limitations were starting to pile up and they finally broke the camel’s back. How do I get out of this mess? How can I maintain github’s free hosting, serve everything from aclima93.github.io, and keep using generators and unsafe plugins? And then I remembered the following limitations:
- you can configure your project’s “Github Pages” to be served from the
docs/directory instead of the root of your repository, but not for your personal “Github Page”- github will ignore your
_site/directory if you push it- github will ways attempt to serve your website by building it with Jekyll unless you provide a
.nojekyllfile in the root of your repository
And then it hit me. _site/ is where Jekyll will place your publishable website after building it, so maybe I could just copy its contents into docs/! Damn it! You can’t do that for a personal Github Page, just for a project’s Github Page. No matter, what if aclima93.github.io.git only serves the contents of _site/ from aclima93.github.io/Blog.git? I can do that by adding the .nojekyll file to the aclima93.github.io.git repository, that way it will serve whatever I put there and won’t try to build it with Jekyll. Then I can also serve it from docs/ on the aclima93.github.io/Blog.git repository as a staging environment, all the while building the static pages with no limitations in my local environment.
In the end, I decided to automate this whole process and create a script that would let me type my blog entries in the Blog repository, and after having been built by Jekyll, automatically publish them to my personal Github Page.
# Hosting
The final step that i had in mind was to serve this website from a simpler URL. Unfortunately, as with almost all websites I try to create an account on, my intended handle of aclima had already been taken (www.aclima.com belongs to a norwegian textile and clothing company) so I had to settle for what I always settle for: aclima93. Thankfully, this .com domain wasn’t nearly as expensive as other more premium ones 😌.
And that’s why this website is hosted at https://aclima93.com even though I’m still going to brand it as aclima.
Once I got the domain, I got to learn a bunch about CNAME registries and how to bridge github’s free hosting from aclima93.github.io to aclima93.com, and suffice it to say, I messed up a couple of times along the way. But as you can witness, I eventually got it all sorted out.