Version 3.0 of my Documentation theme for Jekyll released
- Version 3.0 released
- Prominent theme features
- Getting started
- Comparing this Jekyll theme to HATs and DITA
- Theme roadmap
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: https://idratherbewriting.com/documentation-theme-jekyll/.
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.
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.
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
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.