Creating a simple blog with jekyll

I document how I managed to get jekyll running on FreeBSD. Jekyll is a static site generator written in ruby. That makes self-hosted blogging on static hosting very easy.

Previously I’ve tried hugo but it’s much more cumbersome and seems to be perpetually broken. I also have more experience with ruby so it’s easier for me to fix myself. I won’t be covering custom theming quite yet but even that is very easy.

These instruction are Written for FreeBSD specifically but the majority of this page is UNIX agnostic. Substitute commands and variables accordingly. See The jekyll website if you need more help. System stability not guaranteed.

Installing jekyll

$ sudo pkg install ruby26 rubygem-jekyll rubygem-bundler

Creating a new site

This will create a new directory with a ready-to-go website. There are other options that will create scaffolding for a new theme or a blank website. I don’t care for those fancy things though so we’ll continue with minima, the default theme.

$ jekyll new $SiteName && cd $SiteName

Editing the Gemfile and installing gems

Next we’ll want to edit the Gemfile. A Gemfile is a list of rubygems you need for the current project. Below I show only the changes I have made.

# find the line for minima and comment it out 
#gem "minima", "~> 2.5"

# add this line to upgrade minima to a newer version  
gem "minima", git: "https://github.com/jekyll/minima"

# gives jekyll support for org-mode files
gem "jekyll-org"

# does the hard part for you when creating new posts 
gem "jekyll-compose"

Now we use bundler to install everything from the gemfile. This might take a while.

WARNING: DO NOT RUN THE FOLLOWING COMMAND AS ROOT – Installing gems as root might overwrite any gems your system’s package manager has installed or place a gem earlier in your $PATH than a gem the system’s package manager installed. This has potential to create dependency hell or completely break your ruby installation.

$ bundle install

Testing the installation

run the following then open up a web browser and type localhost:4000 in the address bar.

$ jekyll serve

Editing jekyll’s configuration file

I hate yaml. But, luckily, we don’t have to touch this file very often. Below is something similar to my own _config.yml at the time of writing.

% Blog
author: 
  name: Your Name 
  email: example@example.com 
description: >-
  your description 
  I guess this has something to do with SEO?
  This multi-line also goes in <head>
# the path to your site from apache's documentroot 
# ex: /content/blog. Leave blank if it's at the documentroot
baseurl: "/" 
#This is important for permalinks 
url: "https://blog.your.website"

# Build settings
theme: minima
plugins:
  - jekyll-feed
  - jekyll-org

minima:
# minima 3.0 supports skins. Try classic, dark, solarized, and solarized-dark
  skin: classic
# These put little buttons at the bottom of the page
  social_links:
    gitlab:
      - username: you
	instance: gitlab.instance
    mastodon: 
      - username: you
	instance: mastodon.instance
# this sets the items in the navbar. Note that you cannot just place a url 
# here and expect it to work. Each file must exist in the project directory
header_pages: 
  - index.markdown
  - contact.markdown
  - externalsite.html

# shows the first paragraph of the post on the feed page
show_excerpts: true
# this tells jekyll to stop overriding your custom configs. 
ignore_theme_config: true

Testing the server config

Run the following then open up a web browser and type localhost:4000 in the address bar. Note that jekyll will not automatically reaload when you update _config.yml. You might need to kill and restart it or pass an extra flag.

$ jekyll serve

Writing a post

Jekyll uses markdown. This is the easiest way since all the metadata jekyll wants is automatically placed into the “frontmatter” for you. I typically leave jekyll serve running in another shell and frequently check the generated site as I go.

$ jekyll compose $PostTitle
$ vim _posts/whatever-jekyll-told-you-the-post-is-called.md

Alternatively you can use org mode files. See jekyll-org

Generating the website

Jekyll dumps the static files (ie html, css, js, etc) into _site. This is generated every time you run

$ jekyll serve

$ jekyll clean && jekyll build

Make sure to triple check that everything works before uploading.

Uploading to a webserver

I typically use sftp to move files around. If you don’t know what this means than I suggest you take an hour or two to become familiar with ssh and ftp over ssh. Otherwise you can just use cpannel or whatever antiquated software your hosting provider has cursed you with.

$ sftp -rC remoteuser@blog.your.website
sftp> lcd _posts
sftp> cd /var/www/html/blog-or-wherever-your-blogdir-is
sftp> put -r ./* 
# this might take a long time, go get a cup of coffee 
sftp> bye

Now we check to see if we broke anything during the upload process. Open a web browser and navigate to https://blog.your.website/blog-or-wherever-your-blogdir-is. Did it work? Good job. If not you are beyond my help – Godspeed.