In this second part of Making a Blog, I go through the actual set-up of a website with Jekyll, as well as deploying it on GitLab pages. If you’re interested in the why I chose these two tools, have a look at Part I, otherwise, if you just want to get things up and running, read right on.

Creating the page with Jekyll

The easiest way to get your page up and running quickly is probably to create it from bundled template right in GitLab as described here. Another option would be to fork the Jekyll repo and midify it from there. I chose the third option which is to create your page locally with Jekyll and then publish it to a new repo. I felt like this would give me the most complete learning experience and most freedom in setting everything up.

Since Jekyll has an excellent documentation, I strongly encourage everyone to take a look there as a first step. Here I will describe what I did and emphasise important or difficult points. So, assuming you have Ruby installed, you first install jekyll and bundler gems.

gem install jekyll bundler

While bundler is not required, it’s highly recommended as it ensures you’re running the same version of Jekyll and Jekyll plugins across different environments. Next, you’ll want to create your page.

jekyll new myblog

As easy as that, you have the have the basic scaffolding of your page ready to go. If everthing went fine, you’ll now have a directory called myblog that looks something like this:

myblog/
├── 404.html
├── about.markdown
├── _config.yml
├── Gemfile
├── Gemfile.lock
├── index.markdown
└── _posts
    └── 2020-02-28-welcome-to-jekyll.markdown

The most important files here are _config.yml and Gemfile. _config.yml contains all you site-wide variables that you only change rarely. You can set any variable you like here and later reference it in your layouts as site.variable. Gemfile specifies your jekyll version as well as any plug-ins or themes that you might use. You can check out what this care minimum site looks like by changing into your new directory and running jekyll serve. Prepending bundle exec to all you jekyll commands ensures that your using the gems specified in your local gem file.

cd myblog
bundle exec jekyll serve

Styling

One of the requirements for my SSG was that it would be easy to customise the styling and layout of my site. In my opinion, it is always easiest to find a theme that you like and then adjust it according to your liking. Jekyll has more than enough themes available and it is incredibly easy to install them. If you don’t want fiddle around with the styling at all and just use a theme that you like, it is as easy as installing the gem and specifying the theme in your _config.yml. This has the additional advantage that your directory layout is very clean, since all the theme’s files are stored elsewhere.

In my case, however, I wanted to find a very minimal theme that I can adjust, so I did not go for a gem-based theme. After some looking around, I chose to use the default theme Minima for my base, because it contains all the basics, but no fancy additional things that make things more complicated. While it is possible to only override parts of the theme by just creating your own directory (for example, you could create a file /layouts/post.html to override the default template), I don’t really like having the external dependency on the theme’s gem and want to have everything I work on present in my project directory.

That means, I had to convert the Minima gem-based theme to a regular theme, which is basically the same as copying all the theme’s files into your project directory. Jekyll has en excellent guide on how to do this here. Since I am on Linux, this is how I did it.

rsync -rv -P "$(bundle info --path minima)"/* . --exclude LICENSE* --exclude README*

This copies over all the files apart from LICENSE and README. The directory structure of my blog now looks like this:

myblog/
├── 404.html
├── about.markdown
├── assets
│   ├── main.scss
│   └── minima-social-icons.svg
├── _config.yml
├── Gemfile
├── Gemfile.lock
├── _includes
│   ├── disqus_comments.html
│   ├── footer.html
│   ├── google-analytics.html
│   ├── header.html
│   ├── head.html
│   ├── icon-github.html
│   ├── icon-github.svg
│   ├── icon-twitter.html
│   ├── icon-twitter.svg
│   └── social.html
├── index.markdown
├── _layouts
│   ├── default.html
│   ├── home.html
│   ├── page.html
│   └── post.html
├── _posts
│   └── 2020-02-28-welcome-to-jekyll.markdown
└── _sass
    ├── minima
    │   ├── _base.scss
    │   ├── _layout.scss
    │   └── _syntax-highlighting.scss
    └── minima.scss

To remove the gem-based theme, I also had to remove it from the Gemfile and _config.yml and in turn include the references and plugins.

# ./Gemfile

source "https://rubygems.org"

gem "jekyll", "~> 4.0.0"

group :jekyll_plugins do
  gem "jekyll-feed", "~> 0.12"
  gem "jekyll-seo-tag", "~> 2.6"
end

In _config.yml I removed theme: minima and added

plugins:
  - jekyll-feed
  - jekyll-seo-tag

Now you have the Minima theme installed locally and can start adjusting it. In my case, I took some inspiration from here and there, mostly changed some spacing and headers so far. I also added a welcome paragraph and navigation.

Content

Now, content is obviously the most important, so I will share some tools here that make creating it much easier. For the development of this whole site I use Atom, one of my favourite text editors, since next to its great functionalities out of the box, the jekyll and the markdown-writer make writing blog posts a breeze.

Deploying the website to GitLab

This part is pretty easy, I just followed this guide. The most important file you need to add is .gitlab-ci.yml and there is a template for it available on GitLab (more info). The only thing I needed to adjust in was before scripts to specifically install bundler, because apparently, the default version installed on GitLab is lower than 2. Additionally, I had to set baseurl in _config.yml, because GitLab automatically prepends the project name to your site.

# ./.gitlab-ci.yml

before_script:
  - gem install bundler jekyll
  - bundle install

# ./_config.yml

baseurl: /myblog

I then made my project a git repo, added the GitLab remote, and pushed the repo.

cd myblog
git init
git remote add origin git@gitlab.com:namespace/myblog.git
git add .
git commit -m 'initial commit'
git push

GitLab will then automatically build your site, provided everything is set up correctly. And that’s it, the website is up and running at https://namespace.gitlab.io/myblog/.