Why you should build your blog

I guess it might sound a bit weird, and recursive maybe, that my second post in my blog is about building your blog.

The reason is probably best explained here:

“If you want to learn something, read about it. If you want to understand something, write about it. If you want to master something, teach it.”

Yogi Bhajan

Writing blog articles can be a powerful tool to deepen your understanding of topics you’re passionate about or just interested in.

I encourage you to build your blog locally: as soon as your posts are published on your local machine, nobody out there on the internet we’ll see them, and you can safely practice writing.

I’ve done it too: before publishing this blog, I kept it local for a while.

Jekyll

My blog is written with Jekyll.

Jekyll handles your posts “as code”, by using the markdown languange, thus leveraging code management tools and best practices, such as versioning.

This post summarizes the steps to build a local blog on your machine.

We’ll see how to make it public on the internet in later posts.

How to start your standard Jekyll blog

I use macOS Catalina, but you can easily install it on different OSs too.

So, let’s start:

install Jekyll
choose a code editor: Sublime works fine for me
install git if not yet done on your machine
go to your blog folder and start a local repo by typing git init
set-up the remote repo on Gitlab or your preferred git-repository manager.

There’s a whole world behind each of the above steps: you need to be confident with using your terminal shell, run commands, managing SSH keys, basic versioning, and used to read technical documentation.

Even if you’re not familiar with such tools and practices, I recommend trying: struggle with them and look for help when you’re stuck, by googling or searching the immense stackoverflow resources. That’s what I usually do.

“For the things we have to learn before we can do them, we learn by doing them.”

Aristotle, The Nicomachean Ethics

Change and versioning

Choose a branching stategy to “develop” your blog: I use Issue tracking with GitLab flow

Changing your blog means making a commit of a new version of part of its code (i.e. a new post, a configuration change, a new theme).

I recommend practicing with the branching method, essentially to understand how it works and to be able to develop changes without disrupting your stable version, just as you’d do (or should do) with standard application code.

How to customize your Jekyll blog

Photo by Bluehouse Skis on Unsplash

Once your Jekyll blog is installed, let’s see how to customize it. Open your terminal and enter the blog folder.

When you install jekyll you get the standard theme.

There are lots of themes for Jekyll. I chose Recked.

Follow installation instructions and look through the theme code to understand its structure first, you’ll save a lot of time afterward.

Logo

Changing the logo image is a little tricky, as the Recked logo is a .svg file and you need to build a new image file:

download Gimp or use your preferred image management application
if you need to add text to your logo, use a text editor (i.e. MS Word or alternatives) and add the font used in the recked theme; the font will be installed to your system and Gimp will be able to use it with its text tool
build a new logo image and change the logo image name accordingly in _config.yaml file. See this guide to build a simple text logo with Gimp

Hero image

You can hide or use the hero image which appears on your main page. The _config.yaml file must be updated accordingly.

footer image can be changed by updating the footer_image value in _config.yaml file.
footer text can be updated by editing the footer.html file located in _includes folder.

The menu has the Home item and is populated automatically with pages you create in _pages folder

Further customization options

the _config.yaml file contains the main customization options for this theme
see _sass/0-settings folder for more style customization options.

Write your first post

Photo by Florian Klauer on Unsplash

As mentioned earlier, a new post can be considered a piece of software to be committed to your repo and then published. We’ll take advantage of CI/CD approach to automate posts publishing on the internet (we’ll see it in a coming post), but to update your blog locally the following steps are recommended:

open an issue on your Gitlab repo with the post you want to add and when you are ready to code start a branch locally for the issue from the master branch. The name of this branch should start with the issue number, for example ‘15-require-a-password-to-change-it’
I suggest to arrange your post issues into categories by using Gitlab labels and boards; so you’ll have all your committed and prospect posts in one place
locally on your local repo, type git checkout -b #[issue_number]issue_name so to relate the branch to the issue you just opened on Gitlab
write your post with your code editor
add your post in _post folder (remember Jekyll posts naming convention)
check the results in your local server, by typing bundle exec jekyll serve on your blog folder and then http://localhost:4000 on your browser (or, if already running, just refresh the page)
if you’re good, commit the change and merge the branch into master locally, by switching to master typing git checkout master and then git merge #[issue_number]issue_name
type git branch, where you should see an asterisk on the master branch
sync your remote Repo on GitLab by typing: git push origin master
delete locally your issue-related branch, by typing git branch -d #[issue_number]issue_name
on Gitlab, you can close the issue related to the post you just published.

You can repeat the above steps for your next posts. Happy writing!!

(Photo on top by Clark Tibbs on Unsplash)