Nicholas Nooney’s Blog

Improving Navigation

2019-05-21T17:23:52+00:00

The original menu on the front page was lacking. It only contained a list of the categories of each post I’ve written. However, after adding support for series of posts, I think it would be nice to show the series’ titles in the menu as well. This required making a custom plugin jekyll-groupby and the creation of a new layout called group to display groups of items. The result of the code in this post leads to the menu on the sidebar.

Eariler in the development of this site, I added support for a series of posts, which allowed me to provide controls to navigate from post to post within a series. However, I still lacked a way to see all of the posts that belong to a series in a readable manner. I also cannot view all the posts belonging to a category or tag (which we’ll see later is similar to viewing all of the posts in a series).

I’ve also never worked with plugins to modify content in Jekyll static sites. The documentation contains several examples of what can be done with plugins, including generating content (which will be used here to create landing pages for each of the series, categories, and tags). The result of this post is the plugin jekyll-groupby, which allows for dynamic configuration of groups of posts.

Since I have never programmed in Ruby before, I based my plugin off of the existing plugin jekyll-archives. This plugin allows for creation of achives by date, tag, and category. The plugin itself consists of two parts: a custom page class to store information pertaining to the generated page, and a custom generator used to construct a page and populate it with content from the site’s data. My plugin will also use this structure.

Implementing the Plugin

The plugin is implemented as a single Ruby source file and placed in the _plugins directory in the website’s source tree. I found this to be the easiest method (other methods supported by Jekyll require the plugin to be installed as a Ruby gem).

The Jekyll documentation describes that a Generator must define a function generate that is provided an instance of the site. By modifying the variable site.pages, it is possible to generate any new content for a site. The page can use Jekyll’s existing layout system to create the layout; this plugin needs to provide details about the posts that belong to a particular series or category or tag.

To begin this plugin, I want to look at the configuration used in _config.yml. A look at the configuration describes the settings I’ve arrived at and need to implement.

jekyll-groupby:
  permalink: ":group/:name.html"
  groups:
    - name: "series"
      layout: "group"
    - name: "category"
      layout: "group"
    - name: "tags"
      layout: "group"

The top-level key is the name of the plugin. This is a common theme when using plugins so that a _config.yml file can organize all of it’s settings. Inside this hash are two keys permalink and groups. The permalink describes how to format the URLs for this generated page. It uses the placeholders :group, which is the name of the group (“series”, “category”, “tag”), and :name, which is the name of an item in the group (“code” or “web” for the group “category”). The groups key is an array of objects that provide the name of each group and the layout used to format the group page. The site currently uses three groups, each with the same layout group (which is shown later).

The structure of this config can provide context for implementing the generator. What we need to do is loop over each object in groups, and for each object, find the posts that use that group and divide them into lists by group. This is best shown with an example; we’ll use this set of posts (available via site.posts as an example for the plugin):

#	post	category
1	C++ overview	code
2	Chrome vs Firefox	web
3	Python 2 and 3	code
4	Javascript	code, web
5	WebSockets	web

The groupby page will generate pages for each category, and each page will show a list of posts with the matching category. The plugin will use a Generator and Page in order to create the category pages. With the example site above, there are 2 generated pages: /category/code and /category/web. Each page will contain a list of posts belonging to that category, accessible via the variable page.posts. This is the reason we need a custom Page class instead of using Jekyll’s default Page class; with our custom class, we can provide any of the data that we want to provide for rendering with liquid templates.

The Page Class

Below is the source for the Page class.

module Jekyll
  module Groupby
    class GroupbyPage < Jekyll::Page
      attr_accessor :posts, :slug
      attr_reader :group, :title, :layout, :config

      # Attributes for Liquid templates. Every member in this array is
      # accessible to use in the layout file for the rendered page.
      ATTRIBUTES_FOR_LIQUID = %w(
        posts
        group
        title
        slug
        name
        path
        url
        permalink
        config
      ).freeze

      # Initialize a new Groupby Page. Here we setup all the member variables
      # of the page so that it can be accessed and processed by Jekyll.
      #
      # site - The Site object.
      # title - The value of the key being grouped.
      # config - The specific configuration for this page
      # posts - The array of posts in this group.
      def initialize(site, title, config, posts)
        @site = site
        @title = title
        @config = config
        @posts = posts

        Jekyll.logger.debug "Page:", " ... #{title}"

        # Generate slug for the title
        @slug = Utils.slugify(title)

        # Store a reference to liquid variables.
        @layout = @config["layout"]
        @group = @config["name"]

        # Save the generated file information
        @ext = File.extname(relative_path)
        @path = relative_path
        @name = File.basename(relative_path, @ext)

        @data = {
          "layout" => layout,
        }
        @content = ""
      end

      def permalink
        data && data.is_a?(Hash) && data["permalink"]
      end

      def url
        @url ||= URL.new({
            :template => @site.config["jekyll-groupby"]["permalink"],
            :placeholders => { :group => @group, :name => @slug },
            :permalink => nil
          }).to_s
        rescue ArgumentError
          raise ArgumentError, "Template provided is invalid."
      end

      def relative_path
        path = URL.unescape_path(url).gsub(%r!^\/!, "")
        path
      end

      def inspect
        "#<Jekyll:GroupbyPage @path=\"#{@path}\">"
      end
    end
  end
end

The class itself is scoped within a special namespace to avoid collisions with other Ruby code that runs during the generation process. The most important function is the initialize function. It accepts the title (item in a group, such as “code” and “web”), config (the object with “name” and “layout”), and a list of posts belonging to that category. All of the other functions provide variables that can be used to access data in the page when it is time to render it.

The Generator Class

Below is the source for the generator class.

module Jekyll
  module Groupby
    class Groupby < Jekyll::Generator
      safe true

      DEFAULTS = {
        "permalink" => ":group/:name.html",
        "groups" => []
      }.freeze

      GROUP_DEFAULTS = {
        "name" => "",
        "layout" => "",
        "multiple" => false
      }.freeze

      def initialize(config = nil)
        @config = Utils.deep_merge_hashes(DEFAULTS, config.fetch("jekyll-groupby", {}))
      end

      # The provided generate method performs 3 steps:
      #   1. It processes each groupby archive
      #   2. It resolves the configuration settings
      #   3. It stores each groupby archive as a new page and in site.config.
      def generate(site)
        @site = site
        @posts = site.posts
        @group_pages = []

        Jekyll.logger.info  "Jekyll Groupby:", "Generating group pages"
        Jekyll.logger.debug "Jekyll Groupby:", "Begin Generation..."

        # Ensure expected config variables are present
        @site.config["jekyll-groupby"] = @config

        # 1. Process all of the posts; this function will populate the
        # group_pages array and update the configuration.
        process

        # 2. Save the updated config to the site's config.
        @site.config["jekyll-groupby"] = @config

        # 3. Add all of the group_pages to the site's pages so that they get
        # rendered by later stages in the Jekyll pipeline.
        @site.pages.concat(@group_pages)

        Jekyll.logger.debug "Jekyll Groupby:", "Generation complete!"
      end

      # To process each group archive, loop over each value and create a new
      # groupby page from it. Don't do it for groups of posts that do not have
      # the groupby key present.
      def process
        @config["groups"].each do |config|
          Jekyll.logger.debug "Group:", "Creating pages for \"#{config["name"]}\":"

          # Ensure the default variables are present in the config at the group
          # level.
          config = config.merge!(GROUP_DEFAULTS) { |k, v1, v2| v1 }

          # Use the groupBy method below to generate a hash where each entry in
          # the hash is a single member for the provided key and the values are
          # an array of posts containing that entry. See the groupBy function
          # below for more details.
          group_posts = groupBy(config["name"])

          # Using our hash, convert it to an array in order to support accessing
          # the config from liquid templates and sort the array by the names of
          # each entry. The sorting allows for alphabetical iteration of each
          # group.
          config["posts"] = group_posts.map {
            |k, v| { "name" => k, "list" => v }
          }.sort {
            |a, b| a["name"] <=> b["name"]
          }

          # For each value in the hash, create a group page.
          group_posts.each do |val, posts|
            @group_pages << GroupbyPage.new(@site, val, config, posts)
          end
        end
      end

      # Group each post by the 'key' argument. The key is the name of a front-
      # matter variable used to define a grouping. This will create an array of
      # posts with one entry for each value of the attribute encountered. Each
      # entry looks like this:
      #   {value: [Array of posts with that value]}
      #
      # For example, if there were three posts, A1, A2, and S1 belonging to the
      # "series" A and S respectively, this function would produce the following
      # output given the key "series":
      #   { "A": [A1, A2], "S": [S1] }
      # If there is a post P that does not have the "series" front-matter, then
      # it will not be included in the output hash.
      def groupBy(key)

        # What's happening here is we are accessing all posts. It turns out that
        # the Jekyll variable site.posts returns a Collection object containing
        # all posts in the site. We access the documents array of all the posts
        # because we need to access the front matter in order to determine which
        # key in the hash the post belongs to. We then filter the documents to
        # only those which contain the given key in the front-matter.
        filtered_posts = @site.posts.docs.select { |p| p.data.key?(key) }

        # Next we create a hash and add the post to each bucket in the hash with
        # the given value. If a post has multiple values for the key, then it
        # will end up in multiple buckets in the hash. This may be the case when
        # grouping by tags.
        @hash = Hash.new

        filtered_posts.each do |p|
          pval = p.data[key]

          if pval.nil?
            Jekyll.logger.debug "Post:", " !!! Skipping \"#{p.data["title"]}\""
            next
          elsif pval.is_a? Array
            pval.each do |val|
              addToHash(val, p)
            end
          else
            addToHash(pval, p)
          end
        end

        # Finally, return the hash that was created.
        @hash
      end

      # This helper method preserves the format of the hash, namely, that each
      # value is an array. When a new item is added, it is added to the array,
      # or a new array is created if the key does not yet exist in the hash.
      def addToHash(key, val)
        if not @hash.has_key?(key)
          @hash[key] = []
        end

        @hash[key] << val
      end
    end
  end
end

The Generator peforms the following actions (beginning with the generate function): Grab the configuration from _config.yml, organize site.posts by category and return a dictionary of posts for each category, then loop through the dictionary and create a Page for each category. After all the pages are generated, they are added to site.pages so that they appear in the final output.

The Group Layout

Below is the code for the group layout.

---
layout: default
---

{% comment %}
This template works closely with the groups used by the plugin jekyll-groupby.
{% endcomment %}

<p class="title is-2 has-text-info">
    {{ page.title }}
</p>
<p class="subtitle is-6">
    {% assign num_posts = page.posts | size %}
    {{ num_posts }}
    {% if num_posts > 1 %}
        posts
    {% else %}
        post
    {% endif %}
    {% if site.data[page.group].matchline %}
        {{ site.data[page.group].matchline }}
    {% else %}
        in this {{ page.group }}
    {% endif %}
</p>

{% assign group_data = site.data[page.group].items | where: "name", page.slug
    | first %}
{% if group_data %}
<p class="content">
    {{ group_data.content }}
</p>
<hr>
{% endif %}

<section class="posts-group">
    {% for post in page.posts %}
        {% include components/post-snippet.html post=post %}

        {% if forloop.last == false %}
            <hr>
        {% endif %}
    {% endfor %}
</section>

The layout uses page.posts to display an excerpt of each post in the category via the component post-snippet, which was created previously for the front page. The large amount of liquid templates provide the correct verbiage for the page materials. Some of it is also customizable via YAML data files. Specifically, a paragraph can be added to describe the group and the subtitle can be customized via the variable matchline. Here is an example of the data used to customize a series page on my site (in the file _data/series.yml).

matchline: "in this series"
items:
  - name: developing-a-custom-theme
    content: >
      This series of posts details the process I completed to design the theme
      for this site. I began exploring how gem-based themes work and build a
      working theme that contains feature-parity with Minima, Jekyll's default
      theme. I then move on to add more advanced content, including supporting a
      series of posts, adding Code Syntax Highlighting, and other features to
      complement the theme of this site. As I update the theme, I will add more
      posts to this series. You can always grab the latest copy of this theme's
      code at GitHub.

Wrapping It Up

With this flexible system, I can display any related group of posts on a single page. This greatly improves discoverability and allows for viewing the bigger picture of related content on my site.

Cambre: An exploration into RAII

2019-04-30T00:57:22+00:00

In the previous introduction to Cambre, I mentioned that I would be using GLFW, GLEW, and GLM for handling different aspects of the program. These libraries are great, but I would also like to use a recent C++ version to organize the code I write. Because the three aforementioned libraries are all C style libraries, that means that I have to do a little bit of extra wrangling in order to make them fit my application’s organization.

Every program begins with a main function, so let’s get started there:

int main()
{
    return 0;
}

Great! We have a program that we can run. It is even more basic than a “Hello, World!” program, but it does work. Next we need to initialize the libraries in order to make use of them throughout our application. Let’s expand main to create the libraries.

#include <iostream>

#include <GL/glew.h>
#include <GLFW/glfw3.h>

int main()
{
    if (!glfwInit())
    {
        std::cout << "GLFW Initialization Failure" << std::endl;
        return 1;
    }

    GLFWwindow *window;
    window = glfwCreateWindow(800, 800, "Cambre", NULL, NULL);

    if (!window)
    {
        std::cout << "GLFW Window Creation Failure" << std::endl;
        return 1;
    }

    glfwMakeContextCurrent(window);

    if (GLEW_OK != glewInit())
    {
        std::cout << "GLEW Initialization Failure" << std::endl;
        return 1;
    }

    while (!glfwWindowShouldClose(window))
    {
        glfwPollEvents();
    }

    return 0;
}

This is the basics of creating a window with GLFW and initializing GLEW. It is a bit of extra work to get this to compile; another post in this series will detail the build system that is used to compile the final executable. This post refers just to the code required to build the program. If you are unsure about what is happening here, the best place to find out is the GLFW documentation. The GLEW documentation explains how to get started with the GLEW library.

But wait just one second. This code isn’t neatly wrapped inside the paradigm of C++ and object oriented design. What can we do to make that work? The key is to place this code inside of the constructor so that when we create an instance of that object, the code is initialized for us. There is a caveat in this approach, however. Because we are moving the code here to the constructor of an object, we may end up in a situation where the code is executed multiple times. Depending on the external calls, this may or may not be the desired behavior. If the code supports being called multiple times, then it is said to be reentrant. If it is not, then we need to introduce another pattern in order to ensure the code is executed only once.

In order to place this code into a constructor, we need to create a class that will hold the code. Let’s call it Application. Here is the defintion of the class:

#ifndef _CAMBRE_APPLICATION_H_
#define _CAMBRE_APPLICATION_H_

#include <GL/glew.h>
#include <GLFW/glfw3.h>

class Application
{
public:

    Application(void);
    ~Application(void);
    void run(void);

private:

    GLFWwindow *mpWindow;
};

#endif

There’s not too much to it! We provide a constructor and destructor, and a run function. This will be the entrypoint into the while loop of the code above. It makes sense to split these because the step of initialization should be separate from the step of running the program. Below are the implementations of each method.

#include <iostream>

#include "Application.hpp"

Application::Application(void)
{
    if (!glfwInit())
    {
        std::cout << "GLFW Initialization Failure" << std::endl;
    }

    mpWindow = glfwCreateWindow(800, 800, "Cambre", NULL, NULL);

    if (!mpWindow)
    {
        std::cout << "GLFW Window Creation Failure" << std::endl;
    }

    glfwMakeContextCurrent(mpWindow);

    if (GLEW_OK != glewInit())
    {
        std::cout << "GLEW Initialization Failure" << std::endl;
    }
}

For the constructor, we copied the code in the main function above, replacing the local function variable window with the class member mpWindow. This allows us to keep a reference to the window as the object is used. Also notice that we can no longer return an error code from the constructor in the event of a failure. To do this, we need to come up with some other mechanism for preventing the code from continuing to construct an Application if an error occurs. That mechanism will be described in a later post.

Now let’s move onto the run method.

void Application::run(void)
{
    while (!glfwWindowShouldClose(mpWindow))
    {
        glfwPollEvents();
    }
}

The run method for now contains the loop that will be executed over and over while the application is still running. We will eventually expand upon this to include all of the game’s logic and functionality.

We’ve covered all of the code from the previous main function, but we still have the destructor to write! Actually, it is a good idea to clean up the window once we are done with it, which we didn’t do before. That’s a good fit for the destructor of this class; whenever an Application object goes out of scope, its destructor is called, automatically cleaning up the window’s memory.

Application::~Application(void)
{
    glfwDestroyWindow(mpWindow);

    glfwTerminate();
}

With all of the logic moved outside of our main function, it becomes very simple to run the program! All we need to do is create an Application object and call its run method. Once the main function exits, the resources used by the Application object will automatically be cleaned up via the destructor.

#include "Application.hpp"

int main()
{
    Application app;

    app.run();

    return 0;
}

Voila! This is the beauty of RAII, or “Resource Acquisition is Initialization”. By constructing (think initializing) the Application object, I’ve implicitly acquired a window to run the program in.

So what’s next? We still need to figure out how to handle errors in the constructor of the Application class, and it would be great to see some stuff drawn to the window.

Making Cambre: a voxel-based open-world game

2019-02-01T18:56:26+00:00

In my day-to-day work, I don’t get to work too much with user-facing code. Such is the world of embedded programming. So I decided to start a new project to explore a different aspect of software. I also want to seriously consider the architecture of this project, so not all of the posts will be directly related to the implementation of the project. Lastly, I want to have fun making this project, because otherwise there’s no point.

An important reason I write for this site is to share the knowledge that I gained while doing this project. At the time of writing this, I’m still deciding upon a system of feedback and updating the content.

The Project

I would like to make a Minecraft-inspired clone. It will be a 3D voxel game where I can explore an expansive world. I have some ideas that I would like to try that would distinguish this from Minecraft itself, and I’ll describe those at the time I develop them.

I did a project in college working with OpenGL. I know that the OpenGL standard is being deprecated for the newer Vulkan standard (or if you’re Apple, the Metal standard), but none of those have a good knowledgebase yet and I don’t want to deal with that. So I’m going to use OpenGL for the graphics context.

A Sidetrack Into OpenGL

OpenGL is a API for communications between a Central Processing Unit (CPU) and a Graphics Processing Unit (GPU). The OpenGL specification does not describe an implementation; this is because the API is implemented at various levels in hardware and software. A graphics vendor (Nvidia, Intel, AMD) will create a GPU and provide a driver to access it. Each graphics vendor provides their own driver specific calls that don’t necessarily represent the OpenGL API (often they include proprietary extensions) and application developers don’t want to provide many different builds of their application for each individual driver. The role of translating between OpenGL calls and driver-specific calls is performed by an OpenGL framework.

OpenGL frameworks are available on different systems:

Linux: Provided by the Mesa 3D Graphics Library.
MacOS: Provided by Apple’s OpenGL Framework.
Windows: Provided by Microsoft in the Windows SDK.

Libraries and Technologies

Using OpenGL is a large design decision, but it also represents only a single facet of this project: Graphics Rendering. I’ll also need to handle user input, provide audio support, and use a networking library to make it multiplayer. For now, I’ll decide upon a user-input library (which also handles window creation), and I’ll decide on the others later.

In college, we used GLUT to handle window creation and capturing user Input. However, in the time since I’ve learned about GLFW. Both provide the same functionality: creating a window and allowing me to respond to input; however, I prefer to use GLFW because it provides more control over the application structure than using GLUT. I can write my own game loop this way.

I also need an extension-management library so I can make the most out of my GPU. For this, I’ll use GLEW. And I want to use a math library for performing linear algebra operations easily. For that, I’ll use GLM.

This project uses the following libraries:

GLFW (This library automatically includes Apple’s OpenGL framework).
GLEW
GLM

Grab a Copy

If you would like to see the code as it has evolved, check it out on GitHub.

Using C and C++ Together

2018-09-01T00:00:00+00:00

This article describes how to write code that is available in both C and C++. The C++ website has a great FAQ section on how to mix C and C++; this article shows a concrete example for implementation.

The motivation behind this article is that at work we needed a better way to write unit tests for our code base. Much of the logic was placed into stubbed functions (we use Parasoft C++Test), which violated the principle of clear, immediately understandable, test code. Therefore, we made a framework to control the behavior of our stub functions from the test code itself. As a result, the stubs became more similar, shorter, easier to understand, and easier to maintain. This framework can be used to test both C and C++ code.

In order to succesfully compile a component that can be included and used in both C and C++ code, the basic structure we found to work well consists of the following components:

A common header file that all programs include to use the component.
A C++ specific header file for the C++ implementation.
A C++ implementation of the component.
A C specific header file for the C implementation.
A C-compatible wrapper for using the component.

Let me explain each of these parts in further detail.

The Example Component

For the purpose of making this article easier to understand, we’ll implement the following component:

A counter module that can be used to count things. It supports the following interface:

int counter(void): Register a new counter with a count of 0. Returns the id of the new counter.
int count(int ctr, int amt): Increment ctr by amt. Returns the new count of ctr.
int reset(int ctr): Reset ctr to 0. Returns the new count of ctr.

Notice that the specification uses only C-style functions. This is to ensure that the component can be used in C code.

The files we’ll create to implement this component will have the following names:

counter.h: The common include header.
counter_cpp.h: The C++ header.
counter_cpp.cpp: The C++ implementation.
counter_c.h: The C header.
counter_c.cpp: The C wrapper.

Notice that the C wrapper is compiled with the C++ compiler. This is important for allowing the wrapper to call the implemented functions.

The Common Header

Although not strictly necessary, this common header file makes it easier for all code to use the component. It makes use of the standard predefined compiler macro __cplusplus. This macro is only defined for C++ compilers, which makes it possible to redirect the code to include the appropriate header.

The implementation of the counter component would look like this:

// File counter.h
#ifdef __cplusplus
#include "counter_cpp.h"
#else
#include "counter_c.h"
#endif

The C++ Header

If the component is used as a part of C++ code, then this header will be included. Here we create the class spec for the counter component.

// File counter_cpp.h
#include <vector>

class Counter {
public:
  int counter(void);
  int count(int ctr, int amt);
  int reset(int ctr);
private:
  std::vector<int> mvCounters;
};

For brevity, I have omitted the constructors and destructor.

The C++ Implementation

The C++ implementation contains the implementation for each of the functions in the header. This is standard C++ with nothing fancy happening.

// File counter_cpp.cpp
#include "counter_cpp.h"

int Counter::counter(void) {
  mvCounters.push_back(0);
  return mvCounters.size();
}

int Counter::count(int ctr, int amt) {
  mvCounters[ctr] += amt;
  return mvCounters[ctr];
}

int Counter::reset(int ctr) {
  mvCounters[ctr] = 0;
  return mvCounters[ctr];
}

Any C++ code can include the header and begin using the implementation of the counter component. Things get interesting when allowing the C code to access the members of this class.

The C Header

The C header defines the interface for C programs to use the component. Since C++ code normally gets mangled, we use extern "C" to ensure that the code does not get mangled and C code can properly resolve the symbols during linking. The C header also uses a series of wrapper functions, since the class keyword is non existent.

/* File counter_c.h */

#ifdef __cplusplus
extern "C" {
#endif

int counter_counter(void);
int counter_count(int ctr, int amt);
int counter_reset(int ctr);

#ifdef __cplusplus
}
#endif

The C Wrapper Implementation

The trick to making this work is that the C wrapper implementation is actually compiled with a C++ compiler. This allows the C code to use the C++ class implementation.

// File counter_c.cpp
#include "counter_c.h"
#include "counter_cpp.h"

#ifdef __cplusplus
extern "C" {
#endif

Counter gCounterObj = Counter();

int counter_counter(void) {
  gCounterObj.counter();
}

int counter_count(int ctr, int amt) {
  gCounterObj.count(ctr, amt);
}

int counter_reset(int ctr) {
  gCounterObj.reset(ctr);
}

#ifdef __cplusplus
}
#endif

The C wrapper forwards each function called by the C code to the C++ object. In this instance, a global object is used to facilitate access to the C++ implementation, but it could be also implemented by using a pointer to a Counter instance and declaring a struct that can be used to pass Counter objects around in C++ code.

Wrapup

The ability to commingle C and C++ code has allowed us to avoid writing a separate implementation of a component for use with a different compiler. This pattern can be useful to work with different components. It can be extended to support using many other patterns as well.

Expanding this Site with Images

2018-08-16T01:07:43+00:00

In order to make the site stand out, and also to support media types most common to the internet, I’ve quickly styled up a featured image container. This code uses the assets plugin, and results in a simple styled image at the beginning of each post.

The images themselves are inserted via the jekyll-assets plugin. The snippet of code that renders them using the assets plugin looks like this:

<div class="featured-image-container">
  <figure>
    <div class="box">
      {% if include.post.featured-image.src %}
      {% asset
          "{{ include.post.featured-image.src }}"
          magick:resize=400x400>
          alt="{{ include.post.featured-image.alt }}" %}
      {% endif %}
    </div>
  </figure>
</div>

The asset liquid tag comes courtesy of jekyll-assets. It allows me to resize the image via ImageMagick so that the images don’t end up too large, and it uses the variables in the featured-image front matter to determine the source and alt text for the image. I’ve put this code in a component called featured-image.html. Any post can include it and provide the necessary variables to use a featured image. Including the featured image from a post looks like this:

---
featured-image:
    src: tahoe.jpg
    alt: "Lake Tahoe"
---

<div class="content">
    

<div class="featured-image-container">
  <figure>
    <div class="box">
      
      <img alt="Lake Tahoe" integrity="sha256-rJYE1ALBPyU+XSD7S4P2kJpbQGKIm5HP/wiuGtHPE+s=" crossorigin="anonymous" src="/assets/generated/237d7c-1f15e14edf15d5aad00a59ae64a0df892d82348d6e601f4d72889423413adb1b.jpg">
      
    </div>
  </figure>
</div>

</div>

I’ve added this html snippet to the post layout as well as the post-snippet component so that any post can include it for free. It’s also interesting to note that this is the first template that requires a variable to be passed into it. By default when processing a post, Jekyll stores all information about the post, including its front-matter, in the variable called page. The template passes the page variable into the component featured-image.html. All the variables passed via the include liquid tag get stored in the variable called include (fitting, huh?). That is why the YAML front-matter is referenced as include.post.featured-image instead of just post.featured-image.

To get the image just right, I needed to tweak a few CSS properties of Bulma. The current method I use to organize the styling in this theme is via a main assets/nn.scss file. It looks like this:

---
# This file needs front matter in order for Jekyll to process Sass
---

@import "nn-main";

This is a dummy file that imports another SASS file called nn-main.scss. That serves as the main entrypoint for the styling of the theme. The reason I have an additional import is so that I can separate the styles as they would be organized in a main SASS project from the portion required to make Jekyll process the styles.

Anyways, back to the style changes that needed to be tweaked. I created another SASS file called _bulma-tweaks.scss that gets imported by nn-main.scss. This file is where I can place all the custom rules to override Bulma as much as I need. Here’s the change I made for the featured-image:

.featured-image-container {
    display: flex;
    justify-content: center;
}

This just makes sure that the image shows up in the center of the containing box. There was one last thing missing that I hadn’t realized up to this point: when I looked at the front page of the site, I noticed that all the text for posts that included this image went missing. The root cause of this is how Jekyll determines what an excerpt should look like. Because the featured-image component added extra HTML, Jekyll thought that was sufficient for the excerpt and removed the text. Thankfully, there’s a way to get it back. Jekyll considers a config variable called excerpt_separator: when determining how to make post excerpts. Defining the variable in the file _config.yml will cause Jekyll to consider all text before the matching string the post excerpt.

excerpt_separator: <!-- excerpt separator -->

I’ve backfilled this comment in all earlier posts and updated the Rakefile to generate a post with an excerpt separator so that I always have control over where to split the post. With all of these small changes in place, I am able to include images in a more pleasing manner.

In the future, I plan to add a way to view the full-size original asset as well as include images throughout the post. This featured-image component provides a great starting point for all this future work.

Code Syntax Highlighting

2018-03-19T15:09:40+00:00

One aspect of this static site that was looking bland was the code snippets first presented in Customizing This Site. Originally, these snippets were presented as black text on a grey background. To improve the visual appearance of code blocks, I decided to add code syntax highlighting with Nord.

Jekyll supports SASS to compile CSS by default. Thankfully, Nord exports its syntax coloring as SASS variables already. Jekyll also supports syntax highlighting via rouge. Rouge is a ruby gem that is capable of parsing many different languages and adding syntax highlighting to them. The resulting HTML from Rouge uses the .highlight class to represent the formatted code.

In order to apply the Nord syntax highlighting to the Rouge output, I created a SASS file that maps the styles to the Nord colors. The mapping file can be found here. The result is the syntax highlighting you see throughout this site!

Below are some examples of the results of syntax highlighting. These snippets (and more) can be found here.

C

/* Hello World in C, Ansi-style */

#include <stdio.h>
#include <stdlib.h>

int main(void)
{
  puts("Hello World!");
  return EXIT_SUCCESS;
}

C++

// Hello World in ISO C++

#include <iostream>

int main()
{
    std::cout << "Hello World!" << std::endl;
}

Go

// Hello world in Go

package main
import "fmt"
func main() {
 fmt.Printf("Hello World\n")
}

Java

// Hello World in Java

class HelloWorld {
  static public void main( String args[] ) {
    System.out.println( "Hello World!" );
  }
}

LLVM

; Hello world in LLVM Assembly

@.str = internal constant [14 x i8] c"hello, world\0A\00"

declare i32 @printf(i8*, ...)

define i32 @main(i32 %argc, i8** %argv) nounwind {
entry:
    %tmp1 = getelementptr [14 x i8]* @.str, i32 0, i32 0
    %tmp2 = call i32 (i8*, ...)* @printf( i8* %tmp1 ) nounwind
    ret i32 0
}

Python 3

# Hello world in Python 3 (aka Python 3000)

print("Hello World")

Racket

;; Hello world in Racket

#lang racket/base
"Hello, World!"

Ruby

# Hello World in Ruby

puts "Hello World!"

Shell Script

# Hello world for the Unix shells (sh, ksh, csh, zsh, bash, fish, xonsh, ...)

echo Hello World

Adding Support for a Series of Posts

2018-03-08T14:45:52+00:00

Sometimes, it makes sense to relate posts in a series. A continuation of a story or an expansion of a project are all reasons to continue a post. This post is part of the series Developing a Custom Theme, which details all of the steps that resulted in the creation of this site’s theme.

There are small differences between a post in a series and a post that is not part of a series. The only difference to cause a normal post to become a part of a series is to include the special tag series: in the front matter of the post. The value of this tag is a string containing the name of the series. All posts that contain the same value become grouped into the same series.

For posts belonging to a series, such as this one, you notice a link to the series underneath the post header information. It has the nice, italicized text Part of the Series. It also includes the series name as a link to the series page. We’ll cover the specifics of the series page in a later post, but the markup to make the series identifier is fairly straightforward. All of the markup is included below:

<!-- _layouts/post.html -->

{% if page.series %}
    {% include components/series-header.html %}
{% endif %}

<!-- _includes/components/series-header.html -->
{% assign series_page = page.series | slugify | append: ".html" %}

<section class="series-header level">
    <div class="level-left">
    </div>
    <div class="level-right">
        <p class="series-header is-italic">
            Part of the series
            <a href="{{ series_page | prepend: "/series/" | relative_url }}"
                class="link-wrapper-inline">
                <span class="has-text-info has-text-weight-semibold">
                    {{ page.series }}
                </span>
            </a>
        </p>
    </div>
</section>

In the post template, we add a section to include this new component if the markup that Jekyll processes contains the series: tag inside the front matter. This section of code belongs just before the post content. The component contains some Bulma markup and a link to the series page. To get the name of the series page, I take the series tag and pass it through a filter to get a readable url and append html to the end of the name.

In addition to the markup identifying that this post is a part of a series, I also want the reader to be able to navigate through the series very easily. To do this, I decided to add navigational markup to the bottom of the post. The markup will allow the user to easily access the following items related to the series:

Another link to the series page
The first post in the series
The previous post in the series
The next post in the series
The last post in the series

Bulma’s pagination component was perfect for displaying all of this information. However, figuring out how to obtain all of the information via Jekyll was a bit complicated. I’ll try my best to explain it below.

Similar to how I handled the series header above, I created a new component to handle all of the navigational information. This time, however, the excerpt is inserted immediately after the post content.

<!-- _layouts/post.html -->

{% if page.series %}
    {% include components/series-footer.html %}
{% endif %}

This new component contains the following skeleton code:

<hr>
<section class="series-footer">
    <div class="level">
        <div class="level-item">
            <a href="{{ series_page | prepend: "/series/" | relative_url }}"
                class="link-wrapper">
                {% include components/feather-icon.html
                    icon="archive" class="has-text-info" %}
                <!-- Use this span for spacing -->
                <span class="icon"></span>
                <p class="has-text-info has-text-weight-semibold is-size-5">
                    {{ page.series }}
                </p>
            </a>
        </div>
    </div>
    <nav class="pagination is-centered" role="navigation"
        aria-label="pagination">
            <a href="{{ prev_url }}" class="pagination-previous">Previous</a>

            <a href="{{ next_url }}" class="pagination-next">Next</a>

        <ul class="pagination-list">
            <li>
                <a href="{{ first_url }}" class="pagination-link"
                    aria-label="Goto page 1">
                    1
                </a>
            </li>

            <li>
                <span class="pagination-ellipsis">&hellip;</span>
            </li>

            <li>
                <a href="{{ prev_url }}" class="pagination-link"
                    aria-label="Goto page {{ index | minus: '1' }}">
                    {{ index | minus: '1' }}
                </a>
            </li>

            <li>
                <a class="pagination-link is-current"
                    aria-label="Current page {{ index }}">
                    {{ index }}
                </a>
            </li>

            <li>
                <a href="{{ next_url }}" class="pagination-link"
                    aria-label="Goto page {{ index | plus: '1' }}">
                    {{ index | plus: '1' }}
                </a>
            </li>

            <li>
                <span class="pagination-ellipsis">&hellip;</span>
            </li>

            <li>
                <a href="{{ last_url }}" class="pagination-link"
                    aria-label="Goto page {{ count }}">
                    {{ count }}
                </a>
            </li>

        </ul>
    </nav>
    <div class="level">
        <div class="level-left">
            <p>
                <span class="is-hidden-tablet is-italic">Previous: </span>
                {{ prev_title }}
            </p>
        </div>
        <div class="level-right">
            <p>
                <span class="is-hidden-tablet is-italic">Next: </span>
                {{ next_title }}
            </p>
        </div>
    </div>
</section>

This code may seem overwhelming at first, so let’s break it down. I define a section to contain all of the series navigation, which contains three sub elements. The first item contains the code for the link to the series page. The second item is Bulma’s pagination component that displays all of the buttons for navigating throughout the series. The final component is another level that displays the title of the previous and next post beneath the corresponding navigational buttons.

The first element, which links to the series page, uses the same url scheme as the series-header component. This time however, I center the text and include an archive icon to indicate that this footer contains links to the series.

The second element contains the markup for the Bulma Pagination component. It features the previous and next buttons, as well as links to the first, previous, next, and last posts in the series. The two liquid variables index and count contain numbers indicating the post’s number in the series and the total number of posts in the series, respectively. I’ll show the logic how to calculate those values below.

The third element contains Bulma markup which has been used throughout the site before. The variables prev_title and next_title contain the titles of the previous and next post. They are calculated in the logic below as well.

Before I show the rest of the liquid logic, it is important to understand all of the markup that we are trying to show. I will make substantial modifications to portions of that code to introduce new logic based upon which post in the series is currently being viewed. For instance, it doesn’t make sense to show a previous post if the first post in the series is being viewed.

In order to calculate which posts belong to a series, it is necessary to loop over all of the posts that Jekyll knows about. Liquid can help us out here:

{% assign count = '0' %}
{% assign index = '0' %}
{% assign capture_prev = true %}
{% assign capture_next = false %}

{% for post in site.posts reversed %}
    {% if post.series == page.series %}
        {% capture count %}{{ count | plus: '1' }}{% endcapture %}
        {% assign last_url = post.url %}

        {% if capture_next %}
            {% assign next_title = post.title %}
            {% assign next_url = post.url %}
            {% assign capture_next = false %}
        {% endif %}

        {% if post.url == page.url %}
            {% capture index %}{{ count }}{% endcapture %}
            {% assign capture_prev = false %}
            {% assign capture_next = true %}
        {% endif %}

        {% if capture_prev %}
            {% assign prev_title = post.title %}
            {% assign prev_url = post.url %}
        {% endif %}

        {% if count == '1' %}
            {% assign first_url = post.url %}
        {% endif %}
    {% endif %}
{% endfor %}
{% assign after = count | minus: index %}

I’ve presented all of the code up front. You can see at the beginning I assign the variables count and index, as well as two helper variables, capture_prev and capture_next. I use these two variables to help record information about the previous and next post in the series. Then I loop over each post. By default, Jekyll loops over posts starting with the most recent; however, for numbering the posts in the series, I want to keep track of them in chronological order. Therefore, I loop over them with the reversed keyword.

If the post belongs to the same series as the page (in this instance, page is the current page being rendered while post is the collection of all posts on this site), then I increment the count of pages. Every step after that in this loop records information based upon which post is encountered. Interestingly, for the correct behavior to emerge, I collect information in the opposite order as the posts are presented.

To get the last post url, I always overwrite the variable last_url. This way, by the end of the for loop, last_url is guaranteed to contain the url of the last post in the series.

To get the next post url, I wait until I reach the current post and set the capture_next variable to true. Then on the next iteration of the for loop, I store the post title and url and reset the capture_next variable to false. This helper variable, which goes from off to on and back to off again allows me to capture the post immediately after the current post.

When I encounter the current post, I record the current count as the index. I also set capture_next to true and capture_prev to false. This affects the capture of the next and previous post information.

To get the previous post url, I capture every post while capture_prev is true. Once I reach the current post, I set capture_prev to false in order to stop recording the previous information.

To get the first post url, I record the information when the count is 1.

By the time the for loop exits, I have the urls of the first, previous, next, and last post in the series. I also have the total count of posts and the index of the current post. I also create the variable after, which records the number of posts after the current post in the series. Now I need to use this information to control which buttons should be available for the series navigation. We’ll revisit each of the sections in the navigational buttons and use these variables to control what to show.

<hr>
<section class="series-footer">
    ...

    <nav class="pagination is-centered" role="navigation"
        aria-label="pagination">
        {% if index > '1' %}
            <a href="{{ prev_url }}" class="pagination-previous">Previous</a>
        {% else %}
            <a href="{{ prev_url }}" class="pagination-previous" disabled>
                Previous
            </a>
        {% endif %}

        {% if after > 0 %}
            <a href="{{ next_url }}" class="pagination-next">Next</a>
        {% else %}
            <a href="{{ next_url }}" class="pagination-next" disabled>
                Next
            </a>
        {% endif %}

        <ul class="pagination-list">
            {% if index > '2' %}
            <li>
                <a href="{{ first_url }}" class="pagination-link"
                    aria-label="Goto page 1">
                    1
                </a>
            </li>
            {% endif %}

            {% if index > '3' %}
            <li>
                <span class="pagination-ellipsis">&hellip;</span>
            </li>
            {% endif %}

            {% if index > '1' %}
            <li>
                <a href="{{ prev_url }}" class="pagination-link"
                    aria-label="Goto page {{ index | minus: '1' }}">
                    {{ index | minus: '1' }}
                </a>
            </li>
            {% endif %}

            <li>
                <a class="pagination-link is-current"
                    aria-label="Current page {{ index }}">
                    {{ index }}
                </a>
            </li>

            {% if after > 0 %}
            <li>
                <a href="{{ next_url }}" class="pagination-link"
                    aria-label="Goto page {{ index | plus: '1' }}">
                    {{ index | plus: '1' }}
                </a>
            </li>
            {% endif %}

            {% if after > 2 %}
            <li>
                <span class="pagination-ellipsis">&hellip;</span>
            </li>
            {% endif %}

            {% if after > 1 %}
            <li>
                <a href="{{ last_url }}" class="pagination-link"
                    aria-label="Goto page {{ count }}">
                    {{ count }}
                </a>
            </li>
            {% endif %}

        </ul>
    </nav>
    <div class="level">
        <div class="level-left">
            {% if index > '1' %}
            <p>
                <span class="is-hidden-tablet is-italic">Previous: </span>
                {{ prev_title }}
            </p>
            {% endif %}
        </div>
        <div class="level-right">
            {% if after > 0 %}
            <p>
                <span class="is-hidden-tablet is-italic">Next: </span>
                {{ next_title }}
            </p>
            {% endif %}
        </div>
    </div>
</section>

The code above represents the same code as above, but with conditional logic for showing the controls. The first thing to notice is the previous and next buttons. If there is not a previous or next post, then those buttons are disabled. I chose to make them disabled rather than hidden so that the flow of the page is not affected by the post index. This creates a more consistent interface, which I prefer.

Each of the buttons are shown dependent on the index of the post and the total number of posts. It turns out that each button is dependent on the following values:

First post: index > 2. In order to show the first post, there must be more than one previous post.
Previous ellipsis: index > 3. I show ellipses to indicate the existence of a post between the first and previous. Therefore, there must be a third post before the current post.
Previous post: index > 1. There must be a previous post to show it.
Next post: after > 0. There must be a next post to show it.
Next ellipsis: after > 2. As with the previous ellipsis, I need to show it if there are three or more posts after the current post.
Last post: after > 1. There must be more than one next post in order to show the last post.

The previous and next titles follow the same logic as the previous and next post.

This logic leads to the desired behavior shown on each post. It can be a lot to take in, so it may be more helpful to see the source of the components discussed.

Managing this Site with Rake

2018-03-08T03:40:25+00:00

In order to remember how to correctly build this site, I decided to use Rake. Rake is Ruby’s version of Make: by specifying targets to build and how to build them, I can easily perform a complex series of commands to manage this site. Because Rake is so versatile in declaring targets, I use it to create new posts, run continuous integration, and even generate SSL Certificates for my local development environment.

Beginning with Rake

After installing Rake, all I had to do was create a Rakefile in the root of my site. I’ve never programmed in Ruby before, but it was pretty easy to get started. All that is needed is the name of a task and a useful description, and then we can run a command. Prior to using the rakefile, I had to run a long command every time I wanted to build my site.

bundle exec jekyll build

That’s hard to remember! I would much rather run build in order to build my site. So I can make a target to build my site and insert it in the Rakefile.

desc 'Build the Site'
task :build do
  sh 'bundle exec jekyll build'
end

In this code, desc sets the description of the task, task describes the task named build, and sh executes code in a shell script. This is neat! Now, instead of having to remember the entire command, I can just run rake build.

In order to clean the site and rebuild it, I have to run jekyll clean followed by rake build. It would be nice to have one tool run everything for me, so that I don’t get accidentally confused. Let’s make a target to clean the site too.

desc 'Clean the Site'
task :clean do
  sh 'jekyll clean'
end

This is great! Now I run rake clean; rake build in order to rebuild my entire site. That’s a lot of typing though. I could make it even shorter by running rake rebuild. Let’s make that target.

desc 'Rebuild the Site'
task :rebuild => [:clean, :build]

Unlike the other tasks, this one declares a dependency. The rebuild task must complete the clean task, then complete the build task, in that order. Also notice that it doesn’t have a body to execute. We don’t need one because rebuilding the site is already fully described by the clean and build tasks.

I am a forgetful person sometimes, and with all of these tasks, it is hard for me to remember what I can run. Thankfully, Rake has the option -T to list all tasks that it finds in the Rakefile. But sometimes I even forget that. So in order to make my life easier, I made a task to list all of the tasks.

task :list_tasks do
  sh 'rake -T'
end

This task doesn’t have a description. Rake doesn’t show tasks in the output of rake -T if they don’t have a description. That’s good, so I won’t see this reminder task for me. But how do I remember to run rake list_tasks? Sometimes I may even forget that. The solution is to set a default task. The default task is a task that is run by Rake when no other task is specified. It uses the special :default task name.

task :default => [:list_tasks]

Voila! Now I can run rake whenever I forget what I can do, and Rake will tell me!

Taking Rake to the Next Level

Now that I’ve gotten setup with Rake, I can expand upon it to perform more complicated tasks. Jekyll recommends using HTMLProofer to verify that all the links in your site work. We can make a command called test that tests all the links in the site.

To do this, we need to include html-proofer and use it directly from Rake. Since HTMLProofer is ruby code and Rake executes Ruby code, this makes perfect sense to do.

require 'html-proofer'

desc 'Test the Site'
task :test do
  options = {
    :check_sri => true,
    :check_html => true,
    :check_img_http => true,
    :enforce_https => true
  }
  begin
    HTMLProofer.check_directory('_site/', options).run
  rescue => msg
    puts "#{msg}"
  end
end

I had no idea how to setup and run HTMLProofer, but I got sensible options from the website. I don’t like that I had to hardcode _site/ though. What if I ever change the directory to build to? Jekyll supports the -d option to specify where to run the site from; all that I really care about is that the output from the :build task matches the directory that gets tested. Let’s make a variable.

$SITE_DIR = "_site/"

desc 'Build the Site'
task :build do
  sh 'bundle exec jekyll build -d' + $SITE_DIR
end

desc 'Test the Site'
task :test do
  options = {
    :check_sri => true,
    :check_html => true,
    :check_img_http => true,
    :enforce_https => true
  }
  begin
    HTMLProofer.check_directory($SITE_DIR, options).run
  rescue => msg
    puts "#{msg}"
  end
end

Now we’re getting somewhere. All I have to do is edit the $SITE_DIR variable and then my site gets build and tested in that location!

There’s a lot more that can be done with Rake, and I’m just scrating the surface with the Rakefile for this project. You can see the current Rakefile here. If I do anything more advanced, I’ll write another post about it.

Customizing the Design of this Site

2018-01-22T03:56:26+00:00

The default Jekyll Site uses the minima theme. This theme is great for getting started with the basic content of the site, but I prefer to know what’s going on behind the curtain. What exactly does Jekyll use to convert my markdown files into a complete static site? To learn about this, I made a custom theme for this site. The theme’s source code is posted on GitHub.

How do Jekyll Themes Work?

Jekyll uses Ruby Gems to store themes. A theme is a collection of named HTML files with Liquid markup to insert the site content. The behavior of each HTML/Liquid template can be controlled using front matter in each site file. This front matter is also the way that Jekyll knows which template file to use - the layout keyword indicates which HTML file to render. Overall, the process looks like this:

The site file specifies a layout in its front matter.
Jekyll parses the site file and stores the file in named variables.
Jekyll loads the appropriate HTML template from the theme. The template file gets loaded with the variables parsed in step 2.
The fully rendered HTML file is saved in a build directory, which defaults to _site.

This is the main process that Jekyll runs through to generate a static website from a series of HTML files. All of the plugins available for Jekyll will alter how an individual step in the process is completed; however, the overall process is the same.

As an example, let’s go through step-by-step how this page is rendered. You can view the source of this page here. Notice the layout’s front matter specifies the post layout; therefore, Jekyll will look for the file post.html to convert the source to HTML. You can view post.html for this site’s theme here.

The first thing to notice is that post.html specifies the default layout in its own front matter. Just like markdown files can include front matter, theme files can also contain front matter. The rendering engine is the same as well; Jekyll will take the contents of post.html and will place it in the content variable of default.html. With nested templates, it is possible to break down complex page layouts into easy-to-read layout files.

The custom theme for this site uses several layout components to compose all of the pages. Every page is based off of the default layout, which includes a header, body, and footer. There are also optional layouts that can be included on a per-page basis by setting variables in a page or post’s front matter. The hero banner on the front page and the category menu are examples of optional layouts. These optional layouts are included with the liquid tag {% include %}.

This site currently has three different layouts: post, page, and front. This post is rendered using the post layout, as specified previously. The homepage uses the front layout. The About page is an example of the page layout. As I discover the need for more types of layouts, I will add them to this site and detail how they work.

A final note about the site’s theme: the design of this site uses Bulma to manage layout and styling. While its not the most flexible CSS framework available, it does provide plenty of customization and allows me to focus on the content. The documentation is extensive and provides detailed examples of how to structure the site’s HTML. Take a look at Bulma’s documentation if you would like to understand the specifics of each layout.

The Layouts of this Theme

In order to fully explain how this theme was developed, I will explain how I built the layouts included in this theme. Currently, my goal for this theme is to obtain feature parity with the minima theme. In future posts in this series, I will explain how these basic themes changed to fit my needs.

default.html

Every theme starts with a base layout. This layout will contain the core identity that all other layouts will tweak. In this theme, the base layout is default.html. Like all HTML documents, it starts with the base document layout:

<!DOCTYPE html>
<html>
{% include head.html %}
<body>
</body>
</html>

I’ve separated the <head> content into a separate template, head.html. This is to keep all of the information belonging to the head of the document in its own place.

It’s also good to describe the language of the document. This is done via the lang attribute on the <html> tag.

<html lang="{{ page.lang | default: site.lang | default: 'en' }}">

Use the page language first, falling back to the site language if the page doesn’t specify a language, and using English if neither are specified.

Many websites have a header and a footer. This site is no exception. However, we’ll separate the header and the footer into separate templates like with the header above. Also, we’ll use a <section> tag for the main content.

<body>
    {% include header.html %}
    <section>
        {{ content }}
    </section>
    {% include footer.html %}
</body>

Now it’s time to format the layout. I decided with this theme to use a single column layout to focus on the content with an optional sidebar menu. To make the menu optional, the template must specify menu: true in its YAML Front Matter to include the menu. The front layout does this below. Anyways, here is what the main content looks like, expanded upon the section tags in the previous excerpt.

<section class="section">
    <div class="container">
        {% if layout.menu %}
        <div class="columns">
            <div class="column is-narrow">
                {% include components/menu.html %}
            </div>
            <div class="column">
        {% endif %}
                <main class="page-content" aria-label="Content">
                    <div class="wrapper">
                        {{ content }}
                    </div>
                </main>
        {% if layout.menu %}
            </div>
        </div>
        {% endif %}
    </div>
</section>

All of the classes here except for the main tag are part of Bulma. Look through the documentation there to see how each class contributes to the overall layout.

One more snippet makes the default layout complete: an optional hero banner. This banner adds a splash of color and can be seen on the front page of the website. Like the menu, it too must be specified with hero: true in order to be activated. Since it should appear at the top of the page, it appears between the header and the <section> tag. This snippet sets up the hero banner:

{% if layout.hero %}
    {% include components/hero.html %}
{% endif %}

Altogether, this code makes for a customizable default template that suits the needs of this site. The full code for this template is available here.

post.html

The post template defines the main content for posts (including this one). As specified in the introduction, this template inherits the default template via the front matter.

---
layout: default
---

<article class="post">
</article>

This will cause all of the contents of the post layout to be inserted into the {{ content }} tag of the default layout. We can inherit the head, header, and footer from the default template. Since the post content is the primary focus, this template will not include the optional hero or menu template.

There are two parts to the post layout: the header and the content. The header is the most complex. It contains the post title, date, and tags. There’s a bit of Bulma styling here to make it render nicely as well.

<section class="post-header">
    <div class="level">
        <div class="level-left">
            <header class="post-title">
                <p class="title is-3 has-text-primary">
                    {{ page.title | escape }}
                </p>
                <p class="subtitle is-5">
                    {{ page.date | date: "%B %-d, %Y" }}
                </p>
            </header>
        </div>
        <div class="level-right">
            <div class="tags">
                {% for tag in page.tags %}
                <span class="tag is-light">{{ tag }}</span>
                {% endfor %}
            </div>
        </div>
    </div>
</section>

<hr>

The header is a combination of Bulma layout and Jekyll specific Liquid tags, and so is the content.

<section class="post-content">
    <div class="content">
        {{ content }}
    </div>
</section>

The post layout is heavily focused on text. In a future iteration I hope to add better support for images and other media types as well. You can see the full code of the post template here.

page.html

The page template is identical to the post layout, except it can specify a long-title to use instead of the normal title. This is due to the fact that any page with a title by default gets added to the navigation bar in the header of the site. Below is the content of the page template:

<article class="page">
    <div class="level">
        <div class="level-left">
            <header class="page-header">
                <p class="title is-3 has-text-primary">
                    {{ page.long-title | default: page.title | escape }}
                </p>
                <p class="subtitle is-5">
                    {{ page.date | date: "%B %-d, %Y" }}
                </p>
            </header>
        </div>
        <div class="level-right">
            <div class="tags">
                {% for tag in page.tags %}
                <span class="tag is-light">{{ tag }}</span>
                {% endfor %}
            </div>
        </div>
    </div>
    <hr>
    <div class="content">
        {{ content }}
    </div>
</article>

You can see the full code of the page template here.

front.html

The front layout is designed to be the homepage of this website. It’s intent is to provide a helpful summary of the site’s content and serve as an entry point to explore the rest of the site. It’s layout is quite different from the page and post templates. To start, its front matter does include the optional hero and menu components.

---
layout: default
hero: true
menu: true
---

Other than that, the front layout is very simple. It defines a <section> to contain the main content, and then kicks off to include a series of the most recent posts.

<section class="front">
    {{ content }}
</section>

{% include components/recent-posts.html %}

The recent-posts component lists the most recent posts in the site. In fact, its layout is very similar to the header of the post template. The noticeable difference is the additional liquid logic: it performs additional checks to add a horizontal line between posts, and it limits the tags displayed to three.

<section class="recent-posts">
    {% for post in site.posts %}
        <article class="media">
            <div class="media-content">
                <div class="content">
                    <div class="level">
                        <div class="level-left">
                            <div class="wrapper">
                                <p class="title is-4">
                                    <a href="{{ post.url | relative_url }}">
                                        {{ post.title | escape }}
                                    </a>
                                </p>
                                <p class="subtitle is-6">
                                    {{ post.date | date: "%b %-d, %Y" }}
                                </p>
                            </div>
                        </div>
                        <div class="level-right">
                            <div class="tags">
                                {% for category in post.categories %}
                                <span class="tag is-info">
                                    {{ category | escape }}
                                </span>
                                {% endfor %}
                                {% for tag in post.tags %}
                                <span class="tag is-light">
                                    {{ tag | escape }}
                                </span>
                                {% if forloop.index > 3 %}
                                    {% break %}
                                {% endif %}
                                {% endfor %}
                            </div>
                        </div>
                    </div>
                    <div class="post-excerpt">
                        {{ post.excerpt }}
                    </div>
                </div>
            </div>
        </article>
        {% if forloop.last == false %}
            <hr>
        {% endif %}
    {% endfor %}
</section>

You can see the full code of the front template here.

Summary

These code snippets make up a complete Jekyll theme. I did not show the head, header, and footer includes that the default template uses. It is worthwhile to have a look at those as well to gain a complete understanding of how the site fully works. You can view the theme’s source on GitHub.

Over the course of these series of posts, I will introduce additional features to customize the theme further. All of the code in this theme is under the MIT License and can be customized to suit your needs.

The Creation of this Site

2017-12-31T00:00:00+00:00

So I just setup a new blog for myself, and after looking at the numerous options for publishing content on the web, I decided a static site would suit my needs best. I don’t imagine this site will grow to large numbers, and I don’t plan on hosting huge amounts of media (big pictures and large video files). Plus I’ve dealt with WordPress enough to know that I don’t want to stray anywhere near that beast of a CMS. But mostly, being the programmer that I am, I find managing a simple repository with files containing all of the necessary information for this site much easier than throwing everything into a database and tweaking the inner workings of that. Operating Systems are better suited to handle files and folders rather than databases.

So after searching around on the Internet to find the static site generator that was simple enough that I could comprehend how everything works behind the scenes (I like exploring how things work), I settled on Jekyll. Hugo was a close second but I decided I wanted to get some exposure to Ruby over Go. That and GitHub has first class support of Jekyll sites and will publish them for you.

I did however, want a snazzy domain name for my site, and since most people in tech need a web presence, I decided to purchase my own. I didn’t need any hosting package (thanks GitHub), so I purchased a domain name from NameCheap. About $50 for 5 years. Not too bad.

With a domain name and hosting through GitHub, I was ready to go. All I had to do was install Ruby and Jekyll, and publish my repository to GitHub. With the help of several guides, I able to set up this site exactly how I wanted to. I followed these guides in roughly the steps outlined:

Setup Jekyll to create a site on my local PC.
Publish the repository to GitHub (I don’t have a guide for this step, since I’ve published several repositories to GitHub before). By default, GitHub uses the master branch. I also published an identical gh-pages branch which I chose to host from.
Enable GitHub Pages to host the gh-pages branch of the repo.
Create a CNAME Record with NameCheap to point to the static site. I only needed to create the CNAME record; I didn’t create any other records in this tutorial.

After I got the generic site to show up, I wanted to integrate some continuous integration steps into my site. Travis CI has first class support for continuous integration of GitHub repositories, so it naturally made sense to include that. Thankfully, Jekyll includes a great tutorial to setup continuous integration with Travis CI.

Windows Note: the htmlproofer gem needs libcurl.dll to run successfully. It does not come prepackaged with the gem. To solve this, I downloaded curl for Windows and moved the file libcurl.dll to C:/Ruby24-x64/bin. This will allow the local execution of the CI script.

With that, I had a properly functioning static site configured, with a custom domain and continuous integration set up.

Website Source: GitHub
Domain Name: NameCheap
Hosting: GitHub Pages
Continuous Integrations: Travis CI

Some Time Later

I discovered Netlify, which provides free hosting of static sites (similar to GitHub) and it contains its own continuous integration system. Although I already have a functional static site, I decided to switch over to Netlify hosting and continuous integration. I am a fan of using fewer services when possible so that I don’t forget about all the places that I need to visit to maintain my site.

To transition the previous site over to Netlify, I needed to first disable hosting via GitHub Pages. This was as simple as removing the CNAME file and deleting entries from the settings tab of the repository. Once I did that, I signed up with Netlify (via GitHub), and created a site for my repository. Finally, I updated the CNAME record at NameCheap to point to the Netlify URL rather than the GitHub pages URL.

I also needed to update the Continuous integration from using Travis CI to using Netlify’s built in CI. Also, while the short tutorial to set up CI is nice, it lacks a few resources that are important to modern build systems: separate environments, dependency-based builds, and better automated testing. However, since it is easier to develop locally than test via pushing to the remote, I want to be able to run the complete set of tests both locally and when I push. Therefore, I want to introduce Rake as a better build system.

Rather than use a bash script to kick off the continuous integration, I now use rake deploy as my deployment. After updating the build command with Netlify, I have a full site up and running.

Website Source: GitHub
Domain Name: NameCheap
Hosting: Netlify
Continuous Integration: Netlify