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.”
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.
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
- 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.
Follow installation instructions and look through the theme code to understand its structure first, you’ll save a lot of time afterward.
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.yamlfile. See this guide to build a simple text logo with Gimp
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 text can be updated by editing the
footer.htmlfile located in
The menu has the
Home item and is populated automatically with pages you create in
Further customization options
_config.yamlfile contains the main customization options for this theme
_sass/0-settingsfolder 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_nameso to relate the branch to the issue you just opened on Gitlab
write your post with your code editor
add your post in
_postfolder (remember Jekyll posts naming convention)
check the results in your local server, by typing
bundle exec jekyll serveon your blog folder and then
http://localhost:4000on 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 masterand then
git merge #[issue_number]issue_name
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!!