In Part 1 we create a Vanilla Jekyll Blog, serve it for local development and bring it online, all for free and within one hour.

The Basics - what are we talking about today?

GitHub Pages

First I stumbled over GitHub Pages a couple of years ago when creating an automatic documentation for a customer project. GitHub allows you to host a static generated website for free for your open source projects. We can use this to get rid of annual hosting costs without showing ads or suffering in speed, which is a pretty good deal. Static in this context means that there is no database involved and that you can’t do server-side magic, but you’ll see that this is not a big disadvatage as it may sounds in the first place.

Jekyll

Even though you could crank out static HTML websites by yourself or use any other Static Site Generators (as Hugo, Blosxom, Nanoc), I went with Jekyll since it officially supported by GitHub and I like to work with it. It’s very flexible and easy and the Liquid Template Language is backed by the great Shopify community. To install it for local development, just follow the installation steps.

Preparations

a) Register at GitHub if you don’t already have an account

b) Create a new Repository

Let’s create a new Jekyll website

a) Go to your development directory and install Jekyll and Bundler with RubyGems

~/development/websites
▶ sudo gem install jekyll bundler

Fetching jekyll-4.1.1.gem
Successfully installed jekyll-4.1.1
Parsing documentation for jekyll-4.1.1
Installing ri documentation for jekyll-4.1.1
Done installing documentation for jekyll after 1 seconds
Successfully installed bundler-2.1.4
Parsing documentation for bundler-2.1.4
Done installing documentation for bundler after 2 seconds
2 gems installed

b) create the new website with the help of the jekyll new command

sudo jekyll new my-new-website
Running bundle install in /Users/ras.yen/development/websites/my-new-website... 
  Bundler: Fetching gem metadata from https://rubygems.org/..........
  ...
  New jekyll site installed in ~/development/websites/my-new-website. 

c) To avoid issues when building the very first time I had to run

development/websites/my-new-website                                                                                                                            
▶ mkdir _site && mkdir .jekyll-cache && jekyll build --future 
...
Configuration file: ~/development/websites/my-new-website/_config.yml
Source: ~/development/websites/my-new-website
Destination: /~/development/websites/my-new-website/_site
Incremental build: disabled. Enable with --incremental
Generating... 
Jekyll Feed: Generating feed for posts
done in 0.293 seconds.
Auto-regeneration: disabled. Use --watch to enable.

d) Now we are good to go to have a look at the newly created website. Use the bundler exec jekyll serve command to run it on your localhost

▶ bundler exec jekyll serve
...
Auto-regeneration: enabled for '~/development/websites/my-new-website'
Server address: http://127.0.0.1:4000/
Server running... press ctrl-c to stop.

e) In your browser open up http://localhost:4000/

Congratulations

Let’s bring it online then

To serve the page to the world we need to add the project to our newly created repository. Luckily, that’s easy enough.

a) Open your empty repository at GitHub and copy its URL

b) Go to your local website folder and initiate the new repository

development/websites/my-new-website 
▶ git init
Initialized empty Git repository in ~development/websites/my-new-website/.git/

c) add all the files and commit them

development/websites/my-new-website 
▶ git add .
▶ git commit -m"initial commit"
[master (root-commit) a1b8c0f] initial commit
 8 files changed, 248 insertions(+)
 create mode 100644 .gitignore
 create mode 100644 404.html
 create mode 100644 Gemfile
 create mode 100644 Gemfile.lock
 create mode 100644 _config.yml
 create mode 100644 _posts/2020-07-22-welcome-to-jekyll.markdown
 create mode 100644 about.markdown
 create mode 100644 index.markdown

d) add the origin and push it

▶ git remote add origin https://github.com/Solomonic/my-new-website.git
▶ git push -u origin master
Counting objects: 11, done.
Delta compression using up to 4 threads.
Compressing objects: 100% (11/11), done.
Writing objects: 100% (11/11), 4.28 KiB | 4.28 MiB/s, done.
Total 11 (delta 0), reused 0 (delta 0)
To https://github.com/Solomonic/my-new-website.git
 * [new branch]      master -> master
Branch 'master' set up to track remote branch 'master' from 'origin'.

Configure GitHub Pages

Now we need to tell GitHub that it should serve this. We go to the Settings tab of your repository, scroll down to the GitHub Pages section and set the Source to the master branch.

We now see an URL where we can see our blog online. It is available at https://YOUR_USERNAME.github.io/YOUR-REPO-NAME. We’ll setup a custom domain a little later, for now that will do.

When we click the provided link we get a rather disappointing result though, since the assets/main.css file is not found and links leading us to non-existing locations.

Fix the broken online GitHub page

If we inspect the page source we see that the css points to a reative URL /assets/main.css which resolves to the invalid location https://YOUR_USERNAME.github.io/assets/main.css (/YOUR-REPO-NAME is missing). It is working fine in local development, since the path is correct here with https://localhost:4000/assets/main.css but online is the website living in a sub-directory instead. We need have to update our _config.yml to set the paths correctly with the help of the properties url and baseurl.

# _config.yml
...
baseurl: "/YOUR-REPO-NAME" # the subpath of your site, e.g. /my-new-website
url: "https://YOUR_USERNAME.github.io"
...

We commit and push the changes and finally things look good as expected.

Adjust baseurl for local development

The setting of the baseurl has an unfortunate side-effect for local development though. When we run our jekyll serve command something odd is happening:

development/websites/my-new-website 
▶ bundle exec jekyll serve
...
Server address: http://127.0.0.1:4000/my-new-website/
Server running... press ctrl-c to stop.

Our baseurl is mappend to the server address and if we navigate to http://localhost:4000/ we just see a messed up 404 Page not found. What we’ll need to do is to override the baseurl for local development and we can do that by serving jekyll with the help of the –baseurl parameter.

development/websites/my-new-website 
▶ bundle exec jekyll serve --baseurl ""
...
Server address: http://127.0.0.1:4000/
Server running... press ctrl-c to stop.

Awesome, everything works now online and in local development.

Pro Tip: Create an Alias

If you are a little lazy in tipping like me you can add a permanent Alias for your terminal in your ~/bashrc or ~/bash_profile Open this file with your favorite editor

development/websites/my-new-website 
▶ nano ~/.bash_profile

and add a shortcut command for convinience sake

 # .bash_profile
 ...
alias jekyll_local="bundle exec jekyll serve --baseurl ""

and activate it with

development/websites/my-new-website 
▶ source ~/.bash_profile

Now you can serve your blog locally just by using our custom command

development/websites/my-new-website 
▶ jekyll_local
...
Server address: http://127.0.0.1:4000/
Server running... press ctrl-c to stop.

Conclusion

We managed to created a new Jekyll Blog, can work on it locally and just push it to GitHub to get it online. In the following parts we’ll customize the theme so we actually serve an AMP page and connect the repo to Travis CI. We want to add a deployment pipeline to test that the online page doesn’t break and use custom gems which are prohibited by the standard build of GitHub Pages to make our site feature rich.

Stay tuned.