[This is a guest post by Alex Gil, the Digital Scholarship Coordinator at Columbia University Libraries. Among other collaborations, he is also vice-chair of the Global Outlook::Digital Humanities (go::dh) special interest group of the Alliance of Digital Humanities Organizations, where he has been an advocate of (and instructor in) minimal computing. On Twitter, Alex is @elotroalex.]
In this 3-part tutorial I will be covering the basics of my site generator of choice, Jekyll. Alas, Jekyll only really works smoothly for Mac and Linux machines. In this tutorial I will be assuming a Mac machine, but I’m confident that Linux users will find it easy to extrapolate. Windows users, , I hear Hugo runs nicely on your operating system.
Before you get started though, you should be aware that the workflow for working with Jekyll may be strange to you—not necessarily hard, just strange. If you’re not familiar with the command line, HTML/CSS, or markdown, I recommend you take the introductory tutorials in the links before continuing. At the end of the tutorial I will talk about publishing your site on a server you rent or host yourself. You always have the option to publish your Jekyll sites free of charge using GitHub pages, but this is outside the scope of this tutorial.
Besides some basic know-how, we also need a good simple text editor to create our pages. You cannot use a rich text editor or a word processor. These types of software add unnecessary junk to your files, breaking your site. We need, instead, software that will create files that have no other characters than the ones we put in. As a Mac user, I use TextWrangler, and on a pinch, Vim. You will find many other options by searching for ‘simple text editor.’
Why build a static website?
Building a static website may seem like a throwback to the 1990’s, and in many ways it is, but we have very good reasons in 2015 for doing so. Perhaps the most common type of website today is the dynamically generated one. This type of website, often called a “web-app,” usually creates a persistent connection between the user interface and a database on a server, and pages are “dynamically” constructed when you click on a link or enter a URL. Because of this setup, most of the HTML that you experience on the internet did not exist as such right before you called it on a browser. Security patches and updates are constantly required to keep these websites alive.
The commitment to this maintenance continues to be one of the main reasons web projects fall by the wayside, or the reason you may be having a hard time getting your library to “support” you in the creation and maintenance of your digital humanities project. These complex systems also demand more computation, increasing our collective carbon footprint. As if that weren’t enough, the added computing also makes these websites slower to access in areas of the world with low-bandwith.
If we learned to love database-driven websites like Wordpress, one of the main reasons was the ability to modularize content: to do the Header or Footer once, and have it show up on every page, etc. With such an easy way of doing things, why would you go back to static sites, where you had to build every page one by one, or worst, using Dreamweaver. This is where static site generators come in the picture.
A static site generator allows you to have your cake and eat it too. With most of the affordances of database-driven sites, a static site generator allows you to generate your whole site in your computer out of different components before you put it on a server. Once your site is static, it has become faster to access, more secure and easier to preserve. If you’re feeling really open, you can actually make all the data you used to create the site available to the public, as I did for the Around DH in 80 Days project. To learn more about the thinking that underlies advocacy for static sites, and other forms of minimal computing, please visit our GO::DH Minimal Computing site, itself built using the Jekyll generator.
Getting started with Jekyll: Installation
The actual Jekyll documentation is really, really good and clear, and you should run there any time you need a refresher. If you already know your way around a command line and GitHub, or know how to code a bit, I would just stop reading this and go straight there.
To install Jekyll, open your terminal (another word for the command line). You can find the terminal on a Mac by searching for it by clicking on the little magnifying glass on your top-right menu bar and typing “terminal.” Once your terminal is open type the words that follow the $ (always ignore what comes before the $):
~ $ gem install jekyll
Jekyll is a Ruby “gem” (the Ruby version of a plugin). This means that Jekyll needs Ruby to be installed on your machine. Lucky for you, Ruby comes pre-installed on most modern Macs. If Ruby is not installed on your machine, you need to do so. If you did not get an error after gem install jekyll, you are good to go.
The next step is to create a folder for your project with all the files that jekyll needs to generate your site. You must first figure out where in your machine you will like that folder to exist. I personally have a folder called www that I use for such purposes. To create one and navigate to it enter the following two lines, one at a time, on your terminal:
~ $ mkdir www
~ $ cd www
Once we are inside the www folder, we are ready to create our project starting kit. In this tutorial we will be building a site called “myresearch":
~ $ jekyll new myresearch
Feel free to change the name of the folder to whatever pleases you. Once we created our jekyll starter-kit, we need to navigate to it:
~ $ cd myresearch
Once inside the myresearch folder, we can “generate” the first version of our site easily by typing into the terminal:
~/myresearch $ jekyll serve
Your terminal will now start a local server that comes built-in with Jekyll. You will see a message below the line you just entered. Copy the URL after the words Server address:. Now open your Firefox (Chrome could be a bit sensitive with local servers), and paste the link. Voila! You should be looking at your brand new website.
The site you see before you has been generated into a folder called _site inside your myresearch folder. The complete site is there already. Take a look! Do not get ahead of yourself, though. At this point only you are the only one who can see the website, and of course, we still need to add your content.
Next time...
In part 2 of this tutorial, I’ll explain how to configure your Jekyll site.
Are you a Jekyll user? If so, what has your experience been like? Please share in the comments
