[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 Part 1 of this 3-part tutorial, I made the case for building a static website, and I showed you how to install Jekyll. With this post, I’m going to explain how to configure your site once you’ve installed it, and I’m going to help you understand the components that make up Jekyll.
Configuring your Jekyll site
The first thing we probably want to do once we got a site is to change the title and some basic information. To do so, you need to edit the _config.yml
file on your text editor. The file is located on the top level of your myresearch
folder. Fire up your TextWrangler, or whatever you’re using, and open the file as you normally would from inside your text editor. This file is written in the YAML language. This language is an important part of the way Jekyll handles data, and will become very important when you want to handle data other than pages or posts in Jekyll. At the most basic level, you can understand right away what is happening in this file. YAML is written in “dictionary” style, which means you will always have keys and values. The key precedes the colon, the value follows it.
To change the title of the site, replace “Your awesome title” with whatever value you please. While you’re at it, go ahead and add your email to the email key and change the description (remember to keep the quotation marks for long passages). You can leave everything else as-is for now. Save the file.
At this point if you want to see the results of your work, you need to re-generate the site. Yes, every time we make changes we need to re-generate the site. They don’t call it static site generation for nothing. To do so you must go back to the terminal. Unless you quit the terminal earlier, it should be running the server. We need to cancel this process by using control + c. You should now see your prompt again. Go ahead and clear out the working space by hitting command + k.
Now to regenerate the site type (always after the $):
~/myresearch $ jekyll build -w
The -w
in the above command is an example of a “flag.” In this case, this flag is telling Jekyll to watch for any changes we make to our project files and regenerate the site each time we make one. Nice, huh!
Once our site is re-generated, we need to re-start the server again to see the results. We’ll do that in another tab of the terminal, so that we don’t interrupt the -w
process. To open a new tab hit command + t. In the new prompt type:
~/myresearch $ jekyll serve
Go back to your browser and refresh. Your new site should now reflect your new title and the short description you wrote.
Understanding the Jekyll components
I’ve seen some beginners confuse the generator with the actual site that is built. To be clear, we never make changes inside the _site
folder, ever. Instead we work with the templates in the top level folder, labelled myresearch
in our case. Before we begin, we should take a look at the different parts of the Jekyll project folder structure.
If yours is anything like mine, you should have the following files and folders at this moment.
.
├── _config.yml
├── _includes
| ├── footer.html
| ├── head.html
| └── header.html
├── _layouts
| ├── default.html
| ├── page.html
| └── post.html
├── _posts
| ├── 2015-08-26-welcome-to-jekyll.markdown
├── _site
| ├── [DO NOT TOUCH. GO AWAY]
├── about.md
├── css
| ├── main.css
└── index.html
Let’s go one by one. You’ve already seen the _config.yml
file. The _includes
folder has some of the components we will need in all of our pages. For the standard theme, these are a footer, a header and the head of the HTML file, with links to the CSS and some metadata. Feel free to edit any of them at this point, but be careful. You will notice that this .html files have some strange syntax in them which looks something like this:
{% if page.title %}{{ page.title }}{% else %}{{ site.title }}{% endif %}
This is the liquid templating language, which allows some basic programming functionality and handling of data. If the previous sentence gave you a headache, that’s a good sign that you should stay away from the liquid for now. Once you feel more comfortable with the basic functionality, then I do encourage you to start learning how liquid works in the context of Jekyll. If time allows, I will write a follow-up tutorial on handling data in Jekyll in the future.
The _layouts
folder contains templates for different types of content. In our case the most important thing to notice is that Jekyll handles pages and posts differently. Again, you will notice these files also use liquid.
The _posts
folder is where your posts go. Pages go on the top level folder. The about.md
page for example is a page, the only one so far. If you’re familiar with Wordpress, you will notice that the concept of pages and posts is pretty much the same here. A post is part of a continuous feed, where the latest one usually takes precedence over previous ones; a page on the other hand is imagined to stand alone. In a second we will edit our first page and our first post.
The css
folder is where our stylesheets live. In the standard theme we only use one css file. Feel free to tweak the look and feel of the site if you know what you’re doing. Since we’re regenerating the site automatically, thanks to our -w
flag, your changes should be reflected upon refresh on your browser.
Finally, the index.html
page is our homepage. This is the page we would change to modify the content outside of the header and footer on the homepage.
Next time...
In part 3 of this tutorial, I’ll show you how to edit posts and pages, and I’ll explain how to publish your site.
Are you a Jekyll user? If so, what has your experience been like? Please share in the comments