This is an archived blog post that is no longer listed. That's because this is an old post, from a previous blog I've had in this domain, years ago. I'm keeping this post up only in the interest of link preservation.
This is the last part of my small series of tutorials about building your own blog with Jekyll, no autogenerated code included. You can read the previous posts, part 1 and part 2. In this last tutorial we’ll be working with the same blog example code as in the previous ones. However, if you’re just looking for a particular solution to a problem you might be facing, these examples should be self-contained enough to help.
Just to recap from the previous tutorials: we’re using the gem
Jekyll to generate our blog’s
static pages. We do that by running jekyll serve
,
which also allows us to test it in our browser locally. Our blog
code structure is currently looking like this:
And now let’s improve it.
RSS feed
What’s a blog without an RSS feed to let readers subscribe to it?
To get one, you need an XML file complying with the RSS spec, and
then a link to that file from your default layout, so that it’s
available for every page of your blog. Let’s start with the XML
file. You can simply create a feed.xml
in your
project root, like you have for index.html
. Let’s
fill it with the blog’s latest posts:
This code fetches relevant information from
site.name
, site.description
,
site.url
and site.posts
. That last one
we already used in the first tutorial for building the initial
index page, so should be no surprise. The other ones are values we
can define in _config.yml
. We’ve previously set the
value of name
. Now we can add
description
and url
as well:
Now, Jekyll should have generated a
_site/feed.xml
file that includes the blog’s posts.
The last thing we need to do is including the feed in the blog
pages. We can do that in _layouts/default.html
, so
that all pages include it, by placing the relevant line inside the
<head>
element:
And that’s all you need to do to set up a feed so that your readers can start subscribing to your blog.
And now for something completely different: styling.
Styling with SASS
Given the choice between something terrible and an improvement,
you’d probably go for the improvement. So our blog’s style will be
in SASS instead of plain CSS. Those files will live in the new
_sass
directory of our project (didn’t see that one
coming). For every jekyll serve
, the SASS files will
be compiled and the necessary CSS will be generated in the
_site
directory, like the rest of the generated
static pages.
Let’s start this exercise with a simple refactor. Just by looking
at the last code example, we can see some ugly inline CSS in an
HTML file. That’s not what any serious codebase should look like.
Let’s separate those styles into their own styling file (like
_sass/style.scss
) and leave the HTML alone:
We’re applying those rules to a DOM element with id
body
. So now, in _layouts/default.html
,
we can replace:
with:
Great, so now if you check the newly generated pages… you’ll see
that we’ve just broken the previous style. That’s because we still
need to include the generated CSS file, css/main.css
,
in the layout. The final code should now look like this:
Now we should get our old style back.
Because SASS augments CSS in some interesting ways, we can explore new things in our new styles file:
Some things this code does, if you’re not too familiar with SASS:
-
Nesting: if we’re styling links and want to ad additional styles
to its
hover
status, we only need to define&:hover
insidea
, instead of having a separatea:hover
. Great for avoiding scattering things all over the place; - Saving commonly used values like colours into variables that can be used in CSS properties. Great for DRY;
- Using mixins to define different styles for different situations, like setting a smaller margin for smartphones. Also great for DRY.
Studying the things we can do with SASS is out of scope of this tutorial, so if you want to know more, I encourage you to explore the great tutorials that can be found online.
Categories
Now that the blog is looking more complete, we want to be able to categorise posts. Every post starts with a front matter that configures, in YAML, the post’s metadata. So if we want to add a category to a post, we just need to define it like this:
And now we can change index.html
to include the post
category:
And we can also change _layouts/post.html
to do the
same change:
Great. Now we want categories to link to their own pages, where we can see the list of all the posts with that category. Unfortunately, Jekyll doesn’t support that. Fortunately, it lets us build our own custom plugins, so we will do just that to solve our problem.
Plugins in Jekyll can be Generators, Converters, Commands and
Tags. You can check the
documentation for
more details on each type of plugin. We’ll build a generator that
will, unsurprisingly, generate new pages for the blog’s
categories. That generator will use a new layout, similar to our
existing index.html
, but showing only the posts for
that category, and including the category name as a page title.
Let’s then create a _layouts/category_index.html
with
the following code:
We can now start developing the plugin. It will go into the new
_plugins
directory. Let’s call it
_plugins/categories.rb
. Its classes will live inside
the Jekyll
module. The first step will be to define
the category index page for the generator to use:
If you’ve noticed the new page.category
in the
_layouts/category_index.html
code, you can now see
that it comes from this CategoryIndex
, from this
line: self.data['category'] = category
. We can now
add the generator that will create a new
CategoryIndex
for every category of the blog and save
it as a blog page:
We now finally have category pages. So we can update
index.html
and _layouts/post.html
to
link to them:
And now we finally have categories fully working. Please beware
that if you’re using Github Pages to host your blog, it blocks
most plugins (including all custom ones) from running. So if
you’re using it, you should make sure that you’ve generated the
_site
directory (that way it doesn’t matter that it
doesn’t run your plugins, because the static pages have already
been generated).
Tags
One more thing: post tags. These are very similar to categories: you can just define them in the post’s front matter, but there’s no Jekyll support for individual tag pages, so we must create our own. Fortunately, because it’s so similar to categories, we can draw inspiration from the previous section.
First, we’ll add a list of tags to our posts:
Now we can create the layout for the tag individual pages, where
we’ll show a list of posts with that tag. Let’s call it
_layout/tag_index.html
:
We can now adapt the code in
_plugins/categories.rb
to generate these tag index
pages and their generator, and save it in the new
_plugins/tags.rb
:
And finally we add the list of post tags to
index.html
and _layouts/post.html
:
And we also have tags working. Last section’s warning is still
relevant for this: if you’re using Github Pages to host your blog,
make sure you upload the generated _site
directory,
otherwise this plugin won’t work, because of their plugin
restrictions.
Summary
After having improved our blog in this last tutorial, we should now have a structure like this:
We now have a fully functional blog with categories, tags, proper styling, a feed to subscribe to and all the other features shown in the previous parts of this tutorial, like comments and pagination. There is, of course, a lot more that we can do. If you’ve followed through, I’d recommend you to take a look at the official documentation, where you can find more detailed information about each thing.
Update from 2024: This blog no longer uses Jekyll. I haven't been following its progress, so I also don't know how many breaking changes it may have gotten, and how broken this tutorial may be today.