> Skip to content
FEATURED:
  • The Evolution of Race in Admissions
Sign In
  • News
  • Advice
  • The Review
  • Data
  • Current Issue
  • Virtual Events
  • Store
    • Featured Products
    • Reports
    • Data
    • Collections
    • Back Issues
    • Featured Products
    • Reports
    • Data
    • Collections
    • Back Issues
  • Jobs
    • Find a Job
    • Post a Job
    • Career Resources
    • Find a Job
    • Post a Job
    • Career Resources
Sign In
  • News
  • Advice
  • The Review
  • Data
  • Current Issue
  • Virtual Events
  • Store
    • Featured Products
    • Reports
    • Data
    • Collections
    • Back Issues
    • Featured Products
    • Reports
    • Data
    • Collections
    • Back Issues
  • Jobs
    • Find a Job
    • Post a Job
    • Career Resources
    • Find a Job
    • Post a Job
    • Career Resources
  • News
  • Advice
  • The Review
  • Data
  • Current Issue
  • Virtual Events
  • Store
    • Featured Products
    • Reports
    • Data
    • Collections
    • Back Issues
    • Featured Products
    • Reports
    • Data
    • Collections
    • Back Issues
  • Jobs
    • Find a Job
    • Post a Job
    • Career Resources
    • Find a Job
    • Post a Job
    • Career Resources
Sign In
ADVERTISEMENT
Profhacker Logo

ProfHacker: How (and Why) to Generate a Static Website Using Jekyll, Part 1

Teaching, tech, and productivity.

  • Twitter
  • LinkedIn
  • Show more sharing options
Share
  • Twitter
  • LinkedIn
  • Facebook
  • Email
  • Copy Link URLCopied!
  • Print

How (and Why) to Generate a Static Website Using Jekyll, Part 1

By  Prof. Hacker
August 31, 2015
jekyll-logo-2x.png

[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.

We’re sorry. Something went wrong.

We are unable to fully display the content of this page.

The most likely cause of this is a content blocker on your computer or network. Please make sure your computer, VPN, or network allows javascript and allows content to be delivered from c950.chronicle.com and chronicle.blueconic.net.

Once javascript and access to those URLs are allowed, please refresh this page. You may then be asked to log in, create an account if you don't already have one, or subscribe.

If you continue to experience issues, contact us at 202-466-1032 or help@chronicle.com

jekyll-logo-2x.png

[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.

ADVERTISEMENT

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?

ADVERTISEMENT

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.

ADVERTISEMENT

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.

ADVERTISEMENT

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

ADVERTISEMENT

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:

ADVERTISEMENT

~/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.

New Jekyll site

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.

ADVERTISEMENT

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

ADVERTISEMENT

ADVERTISEMENT
ADVERTISEMENT
  • Explore
    • Get Newsletters
    • Letters
    • Free Reports and Guides
    • Blogs
    • Virtual Events
    • Chronicle Store
    • Find a Job
    Explore
    • Get Newsletters
    • Letters
    • Free Reports and Guides
    • Blogs
    • Virtual Events
    • Chronicle Store
    • Find a Job
  • The Chronicle
    • About Us
    • DEI Commitment Statement
    • Write for Us
    • Talk to Us
    • Work at The Chronicle
    • User Agreement
    • Privacy Policy
    • California Privacy Policy
    • Site Map
    • Accessibility Statement
    The Chronicle
    • About Us
    • DEI Commitment Statement
    • Write for Us
    • Talk to Us
    • Work at The Chronicle
    • User Agreement
    • Privacy Policy
    • California Privacy Policy
    • Site Map
    • Accessibility Statement
  • Customer Assistance
    • Contact Us
    • Advertise With Us
    • Post a Job
    • Advertising Terms and Conditions
    • Reprints & Permissions
    • Do Not Sell My Personal Information
    Customer Assistance
    • Contact Us
    • Advertise With Us
    • Post a Job
    • Advertising Terms and Conditions
    • Reprints & Permissions
    • Do Not Sell My Personal Information
  • Subscribe
    • Individual Subscriptions
    • Institutional Subscriptions
    • Subscription & Account FAQ
    • Manage Newsletters
    • Manage Your Account
    Subscribe
    • Individual Subscriptions
    • Institutional Subscriptions
    • Subscription & Account FAQ
    • Manage Newsletters
    • Manage Your Account
1255 23rd Street, N.W. Washington, D.C. 20037
© 2023 The Chronicle of Higher Education
  • twitter
  • instagram
  • youtube
  • facebook
  • linkedin