[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.]
This post concludes my introduction to Jekyll.
- In Part 1, I made the case for building a static website, and I showed you how to install Jekyll.
- In Part 2, you learned how to configure your site, and I explained Jekyll’s different components.
Today, I’ll demonstrate how to edit posts & pages and how to publish your site.
Editing posts and pages
At this point let’s edit our first post and our first page. Instead of creating new ones, which we can at any point, we will edit the existing “Welcome to Jekyll!” post and the “About” page.
All Jekyll content pages are written in Markdown (GitHub flavored to be precise). Markdown files have the .md or .markdown file extension. Remember to always save your Markdown files with this extension when creating new ones.
If you open the about.md with your text editor, the first thing you will notice is the header of the file:
This is the information about the file, and we need it to generate some of the links, to tell Jekyll what template in the
_layout folder to use and to provide the title on our menus and pages. Extra points if you noticed it is written in YAML style. Replace the values in each category with your preference. In the permalink, make sure to keep the two forward slashes.
At this point you can start editing the content of the about page using Markdown. Jekyll will take your Markdown and convert it to HTML in the re-generation process. That said, you can actually write direct HTML in these files if you wanted to. This technique comes in handy sometimes—for example, when we want to add an
<iframe>, to embed content from another website.
Editing the post is no different. The one important difference is the filename. Posts in Jekyll most adhere to a strict file naming convention:
[date] + [title] + .markdown. The file that generates the “Welcome to Jekyll!” post, for example, is named
2015-08-26-welcome-to-jekyll.markdown. These are no simple dates, either. The date format used here is known as ISO 8601, or as some people call it, “computer date format":
yyyy-mm-dd. Notice also that the filename has no spaces or capital letters. As a matter of course, never use a space or a capital letter on a filename again when dealing with Jekyll.
Publishing your site
Ok, now we’re ready for the big moment. Once you have added content to your heart’s content, and perhaps changed the design of your website, you may want to share the fruits of your labor with the rest of us.
If you do not have your own server, many host providers or your university’s UNIX account can provide a good home for your website. Many digital humanists are now using Reclaim Hosting or Sly Media Networks to rent server space. Either one of those should do for your purposes. Once your server is setup, and you have leased a domain name for your site, you will need FTP or SSH access to the server to transfer your
_site folder to your server. Depending on the hosting company your folder structure on the server will be slightly different, so I cannot provide generalized help to help you navigate your server. Customer service or the documentation on the host provider will go a long way here.
Once you know where you will park your site, all you need to do is transfer the contents of the
_site folder from your computer to the parking spot on your server. Here are some things to keep in mind when you do so: Don’t copy the
_site folder itself, just the contents inside; try to copy the folder in your ‘root directory’ on the server; if you need to create a sub-folder for your jekyll site, you may run into the infamous relative path problem. If you do so, this handy tutorial should get you out of the jam.
That’s it! If you did everything right, you are now the proud owner of your sustainable, speedy and secure digital press. Share that link widely!
Are you a Jekyll user? If so, what has your experience been like? Please share in the comments