Search results

Version 3.0 of my Documentation theme for Jekyll released

by Tom Johnson on Aug 13, 2015
categories: innovation jekyllweb-design

Version 3.0 of my Documentation theme for Jekyll is now available. This theme has a ton of features, such as tags, series, collections, search, PDF generation, and more. Additionally, I've written up detailed documentation for using the theme. Overall, the theme shows how to do single sourcing (including both web and print output) as well as conditional filtering of content based on different attributes.

Version 3.0 released

Version 3.0 of my Documentation theme for Jekyll is now available. You can download the source code from the theme’s Github repo.

Here’s an example output:

The theme is built for single sourcing, so the default theme has a couple of outputs: Designers and Writers. The Designers output has detailed instructions for working with the theme.

Documentation theme screenshot

The Writers output is a slightly scaled back version of the same content (eliminating some explanations of how the theme works), with another theme applied.

Documentation theme screenshot

The Getting started page in the theme explains how to build the two outputs.

Prominent theme features

Some of the more prominent features of the theme include the following:

  • Bootstrap framework
  • Sidebar with page hierarchy
  • PDF generation (with Prince XML utility)
  • Notes, tips, and warning information notes
  • Tags
  • Single sourced outputs
  • Emphasis on pages, not posts
  • Relative (rather than absolute) link structure
  • Responsive design
  • Help API and UI tooltips
  • Extensive documentation and tutorials

For a more detailed list of supported features, see Supported features.

Getting started

To get started using the theme, see Getting started with this theme.

Then see Setting configuration options and Customizing the theme.

Comparing this Jekyll theme to HATs and DITA

Jeyll is amazingly flexible. You can build pretty much whatever you want, if you’re clever enough and have good web development skills. I’m not a professional web developer, but I was able to leverage some existing frameworks like Bootstrap and some jQuery plugins like Navgoco to build this theme.

I think the theme does most everything that a help authoring tool or a DITA-authoring tool can do, within reason. I’ve been using this theme for some months now on documentation projects at my work.

The thing with Jekyll is that you have to build the functionality you want. It’s not enough to say “Can Jekyll do this or that?” It’s more like, “Is there a Jekyll theme that contains the functionality that does this or that?”

The theme is open source and freely available for you to use. If you have feedback, suggestions, or other comments, please let me know.

Theme roadmap

What’s next for the theme? In the next version, I want to add the following:

  • More robust search, including a search results page that highlights keywords matches from the user’s query.
  • Better link management so that you maintain link names in just one place.
  • Better instructions for Windows users
  • More WebStorm tip and tricks
  • Theme validation to ensure there aren’t any broken links or other issues
  • CSS cleanup with more organized, consolidated styles
  • Sass-based rules with CSS to enable easier theming

About Tom Johnson

Tom Johnson

I'm an API technical writer based in the Seattle area. On this blog, I write about topics related to technical writing and communication — such as software documentation, API documentation, AI, information architecture, content strategy, writing processes, plain language, tech comm careers, and more. Check out my API documentation course if you're looking for more info about documenting APIs. Or see my posts on AI and AI course section for more on the latest in AI and tech comm.

If you're a technical writer and want to keep on top of the latest trends in the tech comm, be sure to subscribe to email updates below. You can also learn more about me or contact me. Finally, note that the opinions I express on my blog are my own points of view, not that of my employer.