Features

What’s the Use Case for Jekyll?

By Tom Johnson | STC Senior Member

I recently gave a presentation titled “Writing tech docs like a hacker with Jekyll” at an STC Silicon Valley Chapter meeting, held in a backroom at IHOP around some long tables, with a slide projector positioned up front. “What’s the use case for Jekyll?” an attendee asked, repeatedly. No matter how much I tried to explain Jekyll’s usefulness, I never quite found an answer she liked.

“Yeah, but I can already do all this in our publishing system,” she said. She worked for one of the big tech companies and had an extensive DITA implementation set up using something like IXIASOFT or Trisoft. Everything Jekyll could offer, her publishing system already provided. So what was really the reason why she or anyone else should be interested in Jekyll?

It’s true that if you compare help authoring tools feature by feature, a heavy DITA publishing system or even a popular HAT like Madcap Flare would likely beat Jekyll.

I explained that nearly everything you can do with DITA you can do with Jekyll, but ultimately the question returned, and she said, “I just don’t see what the use case for Jekyll is.”

Having been in the field for a while, I’ve used a range of help authoring tools—RoboHelp, Flare, Microsoft Word, Mediawiki, Author-it, Drupal, Google Docs, Confluence, DITA with OxygenXML, and more. With each tool, I’ve always come up against shortcomings or annoyances with the tools that bothered me. When I had autonomy with tools, I often abandoned one and moved on to the next, only to move again along that familiar hype cycle from the peak of expectation into the trough of disillusionment.

What Is Jekyll?

I should probably back up a bit and introduce Jekyll (http://jekyllrb.com), since few technical writers are familiar with it. Jekyll was originally created in 2008 by Thomas Preston-Werner, co-founder of GitHub, as an alternative to CMS-based blogging tools.

Preston-Werner wanted to approach blogging like a developer, using developer tools and workflows. Preston-Werner writes, “On Sunday, October 19th, I sat down in my San Francisco apartment with a glass of apple cider and a clear mind. After a period of reflection, I had an idea. While I’m not specifically trained as an author of prose, I am trained as an author of code. What would happen if I approached blogging from a software development perspective? What would that look like?”

This seminal post helped launch a whole breed of tools known as “static site generators.” There are now hundreds of static site generators (see staticgen.com), but based on user activity, Jekyll is by far the most popular and has the most community support.

Figure 1. Jekyll has more than twice as many stars and four times as many forks as the next competing static site generator, GitBook.
Figure 1. Jekyll has more than twice as many stars and four times as many forks as the next competing static site generator, GitBook.

As a static site generator, Jekyll takes all your Markdown files and generates them into a complete HTML website. That’s where the name Jekyll comes from—the ability to transform something that’s plain into something awesome. There’s a bit more going on here besides rendering Markdown, though.

Jekyll Project Setup

With Jekyll, you store all your files in a project folder. Basic settings are defined in a configuration file. Using a terminal emulator (I prefer iTerm), you change to your Jekyll project folder and then run “jekyll serve” to create a preview of your content on a Web server.

Figure 2. My text editor is open on the left; the browser on the right is open to the preview URL (http://127.0.0:4005). The terminal window shows how the site regenerates each time I save a change.
Figure 2. My text editor is open on the left; the browser on the right is open to the preview URL (http://127.0.0:4005). The terminal window shows how the site regenerates each time I save a change.

I usually keep this preview window open in one browser and my editor (I like WebStorm) open next to it. As I work on content and save changes, Jekyll rebuilds the site and shows me the update. This way I can work in a text editor while also seeing what the output will look like.

Advanced Scripting Logic

Beyond just converting Markdown, Jekyll also uses Liquid (https://help.shopify.com/themes/liquid), a scripting language created by Shopify, to implement more advanced logic with your content. Liquid includes scripts that can run “for” loops through your content, process “if” and “elsif” statements, apply filters to strings, and more. For example, you might define a property in your configuration file called audience. In one output, you could set audience equal to administrators. In another, you could set it equal to analysts. Then you could incorporate logic on a page like this:


	{% if site.audience == “administrators” %}
	show this to administrators
	{% elsif site.audience == “analysts” %}
	show this to analysts
	{% endif %}

The outputs would conditionalize the content to show the correct content to the right audience. You can also store content in an “includes” folder. To embed any file from your includes folder into another file, you use an include tag like this:


	{% include myfile.md %}

The content from myfile.md gets inserted where you placed the tag. I use includes not only for content re-use, but also to create templates for alerts (notes, tips, cautions) as well as for images. You can pass parameters into the template and populate it in easy ways.

This is only the tip of the iceberg when it comes to Liquid and Jekyll. When you see what you can do using Liquid, it usually removes fears people have about Markdown being too primitive and limiting to handle robust use cases common with tech docs. In addition to Markdown and Liquid, you can also use any HTML or JavaScript directly in your pages.

No Database Backend

Static site generators contrast sharply with Web-based content management systems like WordPress or Drupal. With Web-based content management systems, when users go to your page, PHP tags make calls to the database for the page’s content. The content gets served up from the database and dynamically inserted into the page for the user to view. This rendering takes time.

With Jekyll and other static site generators, however, content is already populated onto the page. When users go to the page, the page content immediately appears, because there’s no need to make a trip to a database to retrieve the content. As a result, Jekyll pages load noticeably faster (half a second instead of the two-second average with Web CMSs).

Figure 3. Web-based CMSs pull content from a database every time a user visits a page. Static site generators don’t have a backend database; content is already pre-packaged onto the page.
Figure 3. Web-based CMSs pull content from a database every time a user visits a page. Static site generators don’t have a backend database; content is already pre-packaged onto the page.

Additionally, because there isn’t a database or online login screen, Jekyll sites are much more secure. There’s nothing to hack. You won’t run into any software restrictions from your security group.

Integration with Version Control

Usually you use version control (like Git or Mercurial) with your Jekyll project. Additionally, GitHub offers some slick features to support Jekyll. When you commit your Jekyll source files to a GitHub repository, in a branch called “github-pages,” GitHub will automatically build your Jekyll site for you. This feature is called GitHub Pages (https://pages.github.com).

Figure 4. GitHub provides hooks to automatically build a site from your repo commits when the source is a Jekyll project.
Figure 4. GitHub provides hooks to automatically build a site from your repo commits when the source is a Jekyll project.

A couple of years ago, I converted my WordPress blog to Jekyll (building with GitHub Pages) and have been pleased with the workflow. Services similar to GitHub Pages—such as a plugin called “Jekyll-hook”—are available for you to implement on your own server.

Markdown and Text-file Formats

Working with Jekyll for the past two years, I’ve found that I really like working in Markdown and text file formats. I cringe every time I open a help authoring tool and see a WYSIWYG editor. I also like the freedom to implement any layout I want using basic HTML, CSS, and JavaScript.

For example, I recently wanted to embed a linear workflow map at the top of each topic in a series, as seen in Figure 5.

Figure 5. This workflow map appears at the top of a lengthy procedure. Jekyll made it simple to implement this map using basic HTML, CSS, and JavaScript.
Figure 5. This workflow map appears at the top of a lengthy procedure. Jekyll made it simple to implement this map using basic HTML, CSS, and JavaScript.

The workflow squares, which are drawn with CSS, automatically highlight based on a box number stored in the page’s frontmatter. Some JavaScript looks at the box number and assigns an active class to the box to perform the green highlighting.

Jekyll is incredibly flexible and allows me to configure outputs for nearly any documentation scenario.

Here’s another example. To deliver context-sensitive help for a project, I used collections in Jekyll to generate a JSON file that Web engineers integrated into a software application. Code on each application page simply pulled in the tooltip content from the JSON file I supplied. (I could have even hosted the JSON file on a separate help server, making it act like a content API, but it was easier to just include the JSON file with the application.)

Basically, you can do pretty much anything you want in Jekyll—especially if you have some Web savvy. Even if you don’t have Web savvy, Jekyll’s code is surprisingly simple (definitely simpler than WordPress). Building a website to match your corporate brand involves just a few basic steps:

  1. Copy the source of the site.
  2. Make all the JS and CSS links work locally.
  3. Gut the page content and replace it with a {{content}} tag.
  4. Save this code as mylayout.html in the layouts folder of your project.
  5. In your Jekyll page frontmatter, specify layout: mylayout.html for your page.

When Jekyll builds the site, your Markdown page content will be inserted into the {{content}} tag of the layout you just defined. That’s it. You don’t have to sort through a long list of PHP tags, there’s no database to configure, no complicated templates with loops to set up. Jekyll is easy enough for technical writers to extend and customize for their unique authoring and publishing needs.

Ultimately, the use case for Jekyll is that it’s a replacement for help authoring tools. You don’t need to spend thousands or hundreds of thousands of dollars each year paying vendors to build elaborate systems to handle authoring and publishing. If HTML is your main output, you can probably do most everything with an open source, static site generator like Jekyll.

With Jekyll, you can handle robust re-use, conditional filtering, variables, multiple outputs, and even—with a bit of hacking—PDF output using a utility called Prince XML.

So my question to the attendee was the same as the one she posed to me, but in reverse, “What’s the use case for these expensive, complex authoring and publishing systems when I can do all of this with a free, open-source tool like Jekyll?” Additionally, Jekyll gives you some unique advantages:

  • Complete control over the site output
  • The ability to work in Markdown formats
  • Integration with version control
  • Lightning fast loading times
  • No licensing costs
A Few Limitations

Jekyll does have some limitations. Jekyll won’t tell you if any links are broken. You can’t see which topics link to each other. While PDF output is possible with some hacks, Jekyll wasn’t designed to easily generate PDF. Because Jekyll is open, it’s hard to lock down content to a specific set of allowed tags or properties.

If you’re using Jekyll with version control, you’ll need to become familiar with tools like Git or Mercurial, which might require additional learning. Search isn’t provided out of the box (you have to incorporate third-party search such as Google, Algolia, or Swiftype). Nor are comment forms provided (again, you would need third-party services such as Disqus). Users can’t log in and have profiles, which means you can’t restrict access based on user roles.

Despite these limitations, Jekyll seems to have hit the sweet spot with how I like to operate. It’s a tool I don’t seem to grow out of. The more I immerse myself in developer workflows and environments, the more comfortable I become using Jekyll and working in a text editor and terminal.

Jekyll probably makes the most sense in developer documentation environments, especially when developers might be contributing or working with documentation. If developers write or edit any docs, they usually prefer to write in Markdown instead of XML.

Additionally, Jekyll works extremely well with API documentation, as it provides powerful syntax highlighting and lets you easily include code samples (either embedded directly or referenced from another directory).

My Documentation Theme for Jekyll

If you’re interested in exploring Jekyll, check out the “Documentation theme for Jekyll” that I’ve created (http://idratherbewriting.com/documentation-theme-jekyll) document. This theme is more than just a pretty skin for your content. In this theme I try to outline best practices and techniques for all the common scenarios that technical writers face.

From content re-use to alerts, automated links, robust table of contents, conditional filters, context-sensitive help, and even PDF output, I outline my approach and show how I implemented it in the Jekyll theme. It can also be helpful to look at some other documentation sites that use Jekyll:

Sometimes looking at source code of other projects can give you ideas for how to approach similar issues. (Most of these projects have open GitHub repos.) This openness leads to more collaboration and innovation, with multiple communities building on each other instead of competing against each other.

References

Jekyll versus DITA series, http://idratherbewriting.com/2015/03/23/new-series-jekyll-versus-dita/

Preston-Werner, Thomas. 17 Nov. 2008. Blogging like a hacker, http://tom.preston-werner.com/2008/11/17/blogging-like-a-hacker.html

TOM JOHNSON (tom@idratherbewriting.com) is a technical writer at Amazon Lab126 (www.lab126.com) in Sunnyvale, California. He is most well-known in the community for his tech comm blog at http://idratherbewriting.com. You can access the Jekyll documentation theme and other resources from the Jekyll tab on Tom’s site. You can contact Tom through Twitter @tomjohnson.