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.
$ 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: firstname.lastname@example.org 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 email@example.com 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.