Many developers and designers have chosen to use Jekyll, a static-page generator, for some of their web-based projects for its ease of use and simple design. In this post, we will be building a minimal blog with the help of Jekyll. In an upcoming post, I’ll discuss hosting a jekyll-based blog on Github through Github Pages. This post is intended to be read by programming beginners who want to build and host a blog “the hacker way”. Since we are building this blog “the hacker way”, this tutorial expects basic command-line experience.
What is Jekyll
Jekyll is an open-source static page generator written in ruby, which can be used to build blogs, documentation, and other types of communication tools. Some features of Jekyll include:
- text-based configuration
- liquid templating for custom layouts
- a plugin system
- a cli tool
To see a full set of features Jekyll offers check out the project home page.
Getting Started with Jekyll
To get started with Jekyll, you will need ruby installed on your machine. To check if
ruby is installed on your machine, run the following command in your CLI program:
ruby was not found on your machine, you can find installation notes here.
Next, let’s install
bundler, a ruby gem for managing ruby project dependencies. Run the following command to install these gems:
Generating a Blog
So far we have setup ruby and installed jekyll, next we will generate our blog. To generate the blog, run the following command:
You’ll see that a new directory called
my-first-blog has been created and inside the directory contains some markdown and yaml files and a new directory called
_posts. Jump into the newly created directory, by running the following command:
Next, we’ll start up the blogging generation process by running the command:
We’ll be running
bundlebefore each of our
jekyllcommands, which is the “de-facto”
rubygemdependency manager for the jekyll project. To learn more about
bundlercheck out the following link.
After a few moments, you should see a newly created folder called
_site. Now, head over to your browser and type
http://localhost:4000 and press enter. You should be seeing a boilerplate-filled web page such as the one below ↓.
Editing the Blog
When your blog was created using
jekyll new my-new-blog, the following files and folders were created:
_posts-> folder containing your blog posts.
_config.yml-> file for configuring project settings and global variables.
index.markdown-> your index file which relies on a home layout.
about.markdown-> another markdown file which we can ignore for now.
Gemfile-> file for describing your
Gemfile.lock-> file for version controlling your
404.html-> no explanation necessary.
When your blog was generated using
bundle exec jekyll serve, a
_site folder was created. Each time your blog is built, this
_site folder will be regenerated with your latest changes to your blog. A common workflow when making changes to your blog is the ability to “watch” for changes.
Run the following command to watch for changes as your editing your blog:
To see new changes to your blog, just change anything contained in
_posts folder and your pages (such as
Writing new Blog Posts
bundle exec jekyll serve -w command is running in the background, create a new file in
2018-11-24-my-new-blog-post.markdown. Run the following command to create the new blog post:
Next, jump into your favorite editor (mine happens to be vim when I’m trying things out) to start editing this file. For Jekyll to understand our blog-post we’ll need to give it some attributes the file’s “header”. Let’s start with the following attributes to describe our new post content.
Next, save the file and look at the output of your terminal window running the
jekyll serve -w command. You should be seeing a newly added blog post called
my-new-blog-post. Refreshing your browser should show your new blog post, however there is no content to view. That’s because we need to write the rest of our blog post!
Before making any more changes to your new blog post, checkout the
_site/jekyllfolder to see that your new blog post has been generated and placed here. This
_site/jekyllfolder layout can be changed by updating your site configuration file
To continue writing your blog post, begin by writing beneath the last trip dashes and save. Check out your changes in the browser, edit, save, and repeat! For more information on the Markdown system supported by Jekyll, check out the following link.
There is still much to explore in what Jekyll offers. I left out some features worth discussing such as Theming and Site Configuration because Jekyll’s documentation is just good enough. I hope you were able to start off blogging “like a hacker” with this short Jekyll tutorial.
If you happened to catch any missing or incorrect details in the post, please drop me an email. And as always, thank you for reading and I hope you catch my next blog post soon!