In the previous post in this series on innovation, I highlighted some web tools worth exploring for help systems. In this post, I want to dive into one of the latest trends with web tools: static site generators.
For the past 10 years, web publishing platforms with database backends have been the predominant way people publish content online. WordPress and Drupal have dominated the landscape. These web platforms, or web content management systems (CMSs), are so popular, about 22% of all new websites in the U.S. are powered by WordPress (according to TechCrunch).
Drupal tends to be used when you want a more robust (and complex) solution than WordPress. Other tools are also common, such as Joomla, Alfresco, Expression Engine, and more.
However, there's a problem with web CMSs such as WordPress:
Static site generators are applications run on the command line that compile a website. For example, you may have various pages defining a layout, some "include" files, a configuration file, and your content files.
The static site generator reads your configuration file and pushes your content into the layout files, adds whatever includes are referenced (such as a sidebar or footer), and renders everything into HTML. Each page has the sidebar and other navigation included directly into it, as well as all the other layout code you've defined, ready for viewing.
Many static site generators run continuously in a browser preview. Each time you make a change to your site, the static site generator recompiles your site in about 1 second. You can refresh your browser preview page to see the changes as you work.
Because everything is compiled locally, you don't need to worry about security hacks into your database. As a result, it's incredibly easy to work with code samples. You can author your content in Markdown or HTML, add code samples inside code blocks that are processed with a Markdown processor (such as Kramdown or Red Carpet), and more. You can add your own scripts directly on the page. It's simply much easier and more flexible to do what you want.
Jekyll, one of the most popular static site generators, allows you to use a templating language called Liquid (from Shopify) inside your content. You can use if-else statements, run loops, insert variables, and do a lot more sophisticated processing of your content through this templating language directly on your page.
Because you're working with text files, you usually store your site files in a code repository such as Github. You treat your content files with the same workflow as programming code -- committing to the repository, pushing and pulling for updates, and more.
When you're ready to publish your site, you can transfer the whole site using the command line to your host. If you're working with Github Pages and Jekyll, your online repository can build your site on the fly. This means your code repository becomes your publishing host. It eliminates the need to actually build your site and deploy the build; instead, you just deploy the source code, and the repository builds it for you.
There are many different static site generators available, but most of them work in highly similar ways. Think of them as different kinds of apples -- Gala, Fuji, Granny Smith, Red Delicious, Honey Crisp, McIntosh, Cortland, and more.
When you read the instructions on using a static site generator, most have similar components and workflows -- you have a configuration file, some layout files, allowed programming logic, and so on.
Some of the most popular static site generators include the following:
You can see the full list of static site generators broken down by repository numbers at staticgen.com.
When I was trying to choose a static site generator, I chose the most popular one, Jekyll, mainly because I wanted a platform that would have the most community support, momentum, and tutorials available for it.
Jekyll also has the benefit of support from Github, which is the most common code repository on the web. Jekyll and Github are kind of like Mediawiki and Wikipedia -- the software thrives in part from its sponsoring host.
Many of the themes designed for Jekyll involve blogging scenarios, but the sites are used for all kinds of purposes (such as the U.S. government heathcare websites). There are quite a few documentation projects that are using Jekyll. To get a sense of what documentation looks like on a Jekyll site, explore the following sites:
(Note: Special thanks for Erlend Sogge Heggen for pointing me to some of these links.)
You can fork most of the above themes and use them for your own documentation projects. Here are also some Jekyll templates built for docs:
For some articles talking about using Jekyll for documentation, see the following:
I also built a Jekyll theme designed for documentation. You can see the Github repository here: https://github.com/tomjohnson1492/documentation-theme-jekyll. Here's the site: Documentation Theme for Jekyll.
Right now I'm just calling this "Documentation theme for Jekyll." Those are the keywords I kept searching for in looking for documentation-related Jekyll themes, so I decided to use it as the name. If you have a recommendation for something more catchy, please let me know.
Any Jekyll site could be used for documentation. So what makes my theme specific to documentation projects?
Without going into too much detail, I'll just note a few features that I thought were key:
That's about it. I'll get into this theme in more detail in a future post. I tried to add some documentation for Getting Started, but frankly I've done a poor job here with the theme documentation and need to spend a lot more time on it. Still, you can probably follow it enough to get started.
My plan is to provide a more comprehensive tutorial on using Jekyll from a technical writer's perspective, explaining how to do single sourcing, conditional logic, content re-use, and even things like translation, PDF output, and more.
This is an ongoing project that will no doubt evolve with many iterations and improvements, but I've reached a point where the theme is good enough to start using for documentation.
I'm currently using this theme on a documentation project at work. So far it's going well. It's too early to make any conclusions, but so far my impression is that static site generators may prove to be a platform that works extremely well for API documentation.
Get new posts delivered straight to your inbox.
I'm a technical writer based in the California San Francisco Bay area. Topics I write about on this blog include technical writing, authoring and publishing tools, API documentation, tech comm trends, visual communication, technical writing career advice, information architecture and findability, developer documentation, and more. If you're a professional or aspiring technical writer, be sure to subscribe to email updates using the form above. You can learn more about me here.