Attach to Process

jekyll

As I alluded to in my previous post, part of the limitations with creating a blog using the Jekyll Now repository, is that it didn't come with Archive and Tags support out of the box. Considering how easy it was to get a blog up and running with Jekyll Now, we shouldn't hold this against it or its creator/contributors. Instead, we should take this as an opportunity to learn more about Jekyll and start writing some code. So here is a quick guide on how you can add an Archive page to your Jekyll Now blog.

Step 1: Add a new archive.html file inside the _layouts folder in your repository.

The content of this file will be a mixture of HTML and Liquid. Liquid is a template language that you can use with Jekyll to help control the pages that are generated for your static site. Think of it as some programming code that gets processed when your static site is generated.

I actually struggled with this for awhile as I could not reconcile how a static site had, what looked like server side code in its pages. What I didn't realize then was that the Liquid code is only used to generate a static page/site. From a .NET developer's perspective, it is almost like Razor, except it is only used to generate a static site/page. It is not going to run as server side code.

The content of the archive.html file will be as follows:

---
layout: default
---

<article class="page">
  <h1>{{ page.title }}</h1>
  <div class="entry">
    
    {% assign previousYear = "" %}
    {% for post in site.posts %}
      {% capture currentYear %}
        {{ post.date | date: "%Y" }}
      {% endcapture %}
    
      {% if currentYear != previousYear %}
        {% assign previousYear = currentYear %}
        <h3>{{ currentYear }}</h3>
      {% endif %}
    
      {{ post.date | date: '%B %d, %Y' }} - <a style="font-weight: bold" href="{{ post.url }}">{{ post.title }}</a>
      <br />
    {% endfor %}    
  </div>
</article>

All I'm trying to do here is get all the blog posts on this site and list them down by year. *Note that I am relying on the fact that the list of blog posts returned by the Jekyll Site Variable site.posts remains in reverse chronological order. For now, that seems to be the case and I don't have to add Liquid code to correctly sort the entries.*

If you're wondering what the line of code ”| date: '%B %d, %Y'” does, that is what is called a Liquid filter and that simply formats the date value to a format I specify. This is similar to calling the ToString() method on a DateTime object in C# and passing in a custom datetime format string.

The default.html file is also found in the _layouts folder in your repository. The link we want to add is this:

<a href="{{ site.baseurl }}/archive">Archive</a>

To find where to insert that line, just find the block of code in the default.html file, where it has the links to the About and Blog page. The code below is an example of what you are looking for.

  <nav>
	<a href="{{ site.baseurl }}/about">About</a>
	<a href="{{ site.baseurl }}/">Blog</a>
	<a href="{{ site.baseurl }}/archive">Archive</a>
	<a href="{{ site.baseurl }}/tags">Tags</a>
  </nav>

As you can see in the code above, I have added the link to the Archive page after the link to the Blog. This is also the code to modify if you wanted to change the order that the links show up on your website.

Step 3: At the root of your repository, add an archive.md file.

The content of the archive.md file will be as follows:

---
layout: archive
title: Archive
permalink: /archive/
---

Adding a .md (Markdown file) at the root of your repository will force Jekyll to generate a html page for that .md file. This is also how Jekyll decides to create the About page, because there is an about.md file in the root of the repository.

Some notes on the content of the archive.md file:

  • The layout entry simply tells Jekyll to reference the archive.html file that you added to the _layouts folder. So basically when this Archive page is generated, it will use the layout/html that you have specified in the archive.html file.
  • The Title entry is simply the Title text that will show up on the Archive page.
  • The Permalink entry is used to ensure that the generated Archive page shows up on “yourdomainname.com/archive/”. You can also supposedly set this in the configuration file, but I just chose to do it here.

There you have it, that wasn't too hard I think. For reference, you can view the source code for this website on Github to see how I implemented it.

#Jekyll #Liquid #Blog

Discuss... or leave a comment below.

If you are a software developer, this is probably the quickest and most fun way to get a blog up and running in like 5 minutes. If you are not a developer and don't have time to tinker with your blog, I think you might be better off creating a blog using a CMS like Wordpress. At the very least, you would need to learn how to write content using Markdown if you are going to follow this approach to creating and maintaining your blog. (Markdown is very easy to learn though, even for non developers.)

Regardless of whether you are a developer or not, this approach is pretty easy to follow and you will end up with a simple blog that just works. You don't even need a custom domain to try this out and your blog will be hosted for free on Github pages.

This is how this blog/site was previously created. I have since updated this blog to be powered by write.as.

There are a number of articles/posts about this topic already so I won't rehash what others have already written. I'll keep this short and simple and just point you to where you need to go to get this done.

  1. Sign up for a Github account.
  2. Find the Jekyll Now repository on Github and start reading the readme info. Actually, you can jump straight to the Quick Start section and follow the instructions there.
  3. That's pretty much it actually. If you follow Step 2 and go through the instructions from the Quick Start section, the end result is your very own blog up and running on the web, hosted on Github Pages for free!

Barry Clark, the creator of the Jekyll Now repository also wrote a more detailed tutorial on how to create a blog using Jekyll Now and Github pages. If you made it this far, I suggest reading that as well.

There are some limitations to creating a blog using this approach, namely, your blog will not have an Archive and Tags pages out of the box. Those are features that I think people would normally expect to be built-in on a blog website. It is not the case here, most likely due to the restrictions Github Pages has on Jekyll plugins. Fear not, as these are easy to add/implement yourself. I will cover adding an Archive and Tags page in a future post.

I hope this post has at least helped you get started on a blog. Good day everyone!

#Jekyll #GithubPages #Blog

Discuss... or leave a comment below.