YOU WILL FIND this post in your _posts directory, if you’re managing a Jekyll site. Jekyll is a static site generator, written in Ruby. Here’s how it works: you install Jekyll locally:

~ $ gem install jekyll bundler

and you generate the scaffolding for a new site with a brief incantation like this:

~ $ jekyll new my-new-site-name

Then you simply move to the site directory you just created

~ $ cd my-new-site-name

and then from inside that directory, you run the Jekyll server

~/my-new-site-name $ bundle exec jekyll serve --watch

Now that the server is ‘watching’ your site for changes, as you add code and content, Jekyll automatically re-generates the entire site. In my case, with just a few pages, the process takes .22 seconds.

Then you push the site to a git repository like Github, and publish it via Github Pages.

Below is a more detailed look at the steps I go through to make changes to the site.

CREATE A NEW BRANCH

Create a new branch with git

git branch <new-branch-name> 

or checkout an existing branch

git checkout -b <new-branch-name> 

START WATCHING FOR CHANGES

You can rebuild the site locally in many different ways, but using the –watch flag is simple.

bundle exec jekyll serve --watch

Now, as you make edits, the site will regenerate, and you can preview the changes in a new browser tab that is pointing at the right ports (in a Github Codespace which uses VS Code, just go to the Ports tab and click on the globe icon to open a preview of the site).

ADD POSTS, COMMIT, MERGE

To add new posts to your blog, simply add a file in the _posts directory that follows the convention YYYY-MM-DD-name-of-post.markdownand includes the necessary front matter. Then make edits to files in the _posts directory, or to other files. Each time you edit, the site will regenerate, and you can preview the changes in your browser. When you are done, quit the jekyll server with ctrl-c, and then add all the changes to git’s staging area:

git add .

Now you are ready to commit the changes with a message describing what changed

git commit -m "Your commit message" 

Then push your branch to the remote repo

git push origin <new-branch-name> 

Finally, checkout master and git pull master to make sure the master branch is up to date, and then merge and push:

git checkout master
git pull origin master  # Ensure master is up-to-date
git merge <new-branch-name> # Merge the new-branch-name into master

PUBLISH AND CLEANUP

To make the changes go live on your site use:

git push -u origin master   

Your site will be updated in a minute or so. If you want to delete the branch you were using you can

git branch -d <new-branch-name>

WHY JEKYLL?

What can you do with Jekyll? Well, pretty much anything that you can do with Ruby. If you’re like me, and eager to learn more Ruby, then Jekyll is a great way to ease into things. Take a look at the list of blog posts in /blog (or the footer of the home page), under the hood there’s a bit of embedded Ruby in the HTML and this Ruby says: make a list of all the blog articles, discard all but the most recent four posts, then create a 23-word excerpt for each, and output the hed, dek, small image, and excerpt into these HTML tags here. The hed, dek, etc. are all defined in the front matter of the markdown file you use to create the post. ‘Front matter’ sound confusing? Just open the sample posts that are baked into the default new site. It’ll make instant sense. They’re just variables that you can refer to elsewhere.

I found Jekyll’s includes and layouts easy to navigate. You put reusable code for the head, header, and footers in the includes directory, then include them into layouts you create, for example a page layout. When you create a new instance of a page, it knows that a page is just a slight variation on the default layout.

Because there’s no database in the backend, there’s reduced complexity, increased security, and each page is much snappier to load.

When I first heard about static site generators, I was a bit confused. If this were possible, why aren’t more bloggy sites using static site generators? Turns out the answer is: because we just needed a little time to figure out how simple it is. At least that’s how I feel.

CREDITS

This site is hosted using Github Pages, which makes hosting HTTPS sites relatively painless and easy, not to mention very cost-effective (gratis). I used the Bootstrap Agency theme for its animated fixed nav bar and nice timeline CSS. All icons are by FontAwesome, and from time to time I use the following icons from the Noun Project

• Recursive triangles, Created by Bohdan Burmich
• Donut chart, created by HLD
• Lightbulb, created by ImageCatalog

The full-bleed image at the top of the site is a photogram of pine needles. I chose this image because it reveals the rhythm, inner structure of something simple, something we take for granted. It is “Dennenaalden, anonymous, 1840 - 1845” and is part of the Rijskmuseum collection in Amsterdam.

Jekyll also offers support for code snippets:

def print_hi(name)
  puts "Hi, #{name}"
end
print_hi('Tom')
#=> prints 'Hi, Tom' to STDOUT.

Check out the Jekyll docs for more info on how to get the most out of Jekyll. File all bugs/feature requests at Jekyll’s GitHub repo. If you have questions, you can ask them on Jekyll Talk.