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

Sponsored content

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
Buy me a coffeeBuy me a coffee