Introducing Jekyll

This site is published with Jekyll, a static site generator. For more info on Jekyll, go to the post right before this one.

First encounter

I had been drawn to Jekyll after hearing about it on

Before firing up this site on Github Pages, I had briefly experimented with Jekyll in 2017 after learning of it while reviewing Tom Johnson’s I’d Rather Be Writing resources. I set up Jekyll 3.6.2 on a Mac and experimented a bit. Now that I have become interested in writing about technology more, I resumed working with Jekyll again this August in hopes of using it on a regular basis.

Getting Jekyll working again with the latest version of Ruby

While there is now a graphical user interface (GUI) for Jekyll known as Jekyll admin, I have been using Jekyll exclusively through the command-line. And as with other command-line tools, the setup process had a little trickiness with versions and tool chains. After getting things up and running, I have to say that I love the easy deployment process.

My experience getting (re)oriented

The first challenge was making sure I had the latest version of Jekyll running, as I had installed Jekyll 3.6.2 two years ago to just try it out. My initial version still worked great — but when I decided to to update to 3.8.6 with my Mac’s installed version of Ruby, I ran into permissions issues. So downloaded a version of Ruby that was independent of my Mac version and switched to this version with my ruby version manager (rvm). This proved to be the breakthrough I needed, and I was able to download and run Jekyll 3.8.6.

Running the local server

One thing that I found myself adjusting to was the necessity of Jekyll’s server process when running pages. It is easy enough to start — after running jekyll create [directoryname], you can then run jekyll serve or bundle exec jekyll serve from within your new directory. This starts a server process on your machine, running a local dev site that shows up in your browser. The browser renders your pages by parsing the files from a _sites directory that Jekyll generates containing your output files. One thing to note, though, is that the _sites directory does not load in the CSS if you open it without having jekyll serve running. You need that server process for the html page’s filepaths to work properly.

Adding CSS

One thing that initially perplexed me was where to put custom styles. Jekyll uses sass and when you run jekyll serve the sass automaticallly compiles - but it was not obvious how to add other styles initially.

I had seen a _sass directory initially in Jekyll 3.6.2 but did not use it during my brief trial run with Jekyll in 2017. When I updated to Jekyll 3.8.6, the _sass directory was no longer there, nor were other key directories. After reviewing the latest documentation on the Jekyll site, I read that these directories were now included in the gem theme, which resided outside my project directory. Typing bundle show minima from within the project directory allowd me to find its location on my machine. I then copied _sass, _layouts, _includes, and assets over from the theme and overrode parts of the templates and styles that I wanted to change.

After exploring the directory, I decided on two approaches for styles:

  • a custom.scss file that is imported so the css shows up in main.css
  • a separate custom.css file

Adding Code Views

I knew that I would want to use styles to show HTML, CSS, and JS in my posts. Jekyll has natural styles for marking up code, but I wanted something that had more color out-of-the-box. Fellow developer Becca Williams had recommended the Prism Library, so I went ahead and added it.

Tabs

I also knew I wanted to create some tabs a la CodePen, and I didn’t want to write a codepen for every step of my project. So I wrote up a quick script and styles for adding tabs so that viewing HTML would be easy. The script is available here and the styles are on this sheet.

Pagination

After getting my basic site up and running, I started thinking about how to keep my work expandable. I wanted to find a way to paginate my posts, and started looking around for ways to do it. While the original paginate gem was deprecated, I found the new Paginate v2 module, which I am now using. I found their examples directory to be instrumental in setting up my pagination logic.

Mistakes

  • Running Jekyll serve from location other than your root directory. This creates a _site folder in the wrong location and can start a slew of unwanted issues.
  • Inadvertently creating a template, such as a default.html or index.html file, in the wrong directory

The banner

As I was really into SVGs and I’ve been on a dragon illustration kick for the past year, I wanted to create an SVG banner with a dragon. The trickiest thing was figuring out CSS to get it to look responsive. Right now it’s coming along but not finished yet.

Sorting for creating a course page

I wanted my default paginated sorting to be most recent date first, but I wanted the opposite for pages that were meant to house instructional posts on a specific topic. After looking at a bunch of template code, I learned how to assign variables in the jekyll template.

{% assign sorted = site.tags[page.category] | sort:"date" %}

The command assign takes care of the variable assignment. I am reaching into site.tags, filtering by the specific category of the current page, and then sorting by ascending date. This allows me to sort the posts for one category in ascending order.

Wiring my Jekyll site to Github Pages

I was originally storing my github-pages publishable stuff in a completely different repo and actually copying all the stuff from the _sites directory over to that repo every time I wanted to publish and push. Needless to say, I wanted omsething more efficient.

After reading about other approaches, my approach was to wire the _sites directory to Github pages. Because my overall jekyll directory was under site version control, I was worried about having a repo within a repo. Fortunately, .gitignore in my jekyll repo had my back, because it automatically ignores the _sites folder. So I moved the .git directory from github-pages into my _sites folder and voila — the _sites folder was under version control and wired to Git, and I now have all my jekyll assets in one place.

One thing I found, though, is that running jekyll clean will blow away the git repo, so it’s not something I want to do on a regular basis. Because I seldom run that command and push my changes on a regular basis, the workflow works well.

There is a gem specifically designed for Github pages, though I have not looked into it yet.

Liquid Syntax

I would be remiss if I did not mention how helpful it has been to learn some Liquid, the programming language used for Jekyll templates.

Closing remarks

It has been a very interesting week getting started with Jekyll. I look forward to posting additional thoughts as I get to know the tool more.