The Documentation Theme for Jekyll is a Jekyll-based website theme built for technical documentation and help systems, delivering static HTML sites with product-specific sidebars, PDF output, and multiple special layouts. It is created by Tom Johnson, author of the technical writing blog "I'd Rather Be Writing," and maintained on GitHub at tomjoht/documentation-theme-jekyll.
What is the Documentation Theme for Jekyll?
This theme takes Markdown pages with YAML frontmatter and builds them into a static documentation website using Jekyll. Output includes a collapsible sidebar, top navigation, search support, and optional PDF files per product. It runs on Jekyll 3.x with kramdown as the Markdown processor, and the primary language in the repository is HTML. The theme is distributed free on GitHub under the gh-pages branch and includes sample content for three products (mydoc, product1, product2) that you can delete.
Key Features
- Multi-sidebar navigation — Each product documentation set can have its own sidebar defined in a YAML file under
_data/sidebars/, with support for two levels of nesting. - PDF generation via Prince XML — Build a PDF for each product individually using a licensed Prince XML tool, with configuration files in the
pdfconfigsfolder and build scripts likepdf-product1.sh. - Commento.io integration — Add comments below pages and posts through Commento.io (requires a paid plan at $5/month); can be disabled globally in
_config.yml. - Relative links everywhere — The site uses relative URLs so you can view it offline or move it between internal and external servers without rewriting links.
- Multiple special layouts — Includes knowledge-base, glossary, FAQ, and shuffle layouts for different documentation patterns.
- Frontmatter-driven metadata — Pages can define
title,tags,keywords,summary,sidebar, andpermalink, with keywords populated into HTML metadata for SEO. - Docker support — Build and run the site locally with
docker-compose build --no-cache && docker-compose upwithout installing Ruby gems locally. - Kramdown Markdown — Supports kramdown syntax with specific list-spacing rules, and includes syntax highlighting for code samples.
Who is it for?
The theme is designed for technical writers who need to produce documentation for multiple products or versions, with each product getting its own sidebar. It also suits documentation teams that want a lightweight static site approach rather than a full CMS. Developers who need quick documentation hosting on GitHub Pages can use the included github-pages gem option. API documentation writers following Tom Johnson's tutorials will find the theme aligned with his recommended workflows.
What can you do with it?
- Product documentation teams: Create separate sidebars for each product and set default sidebars by folder path in
_config.yml, so each page automatically gets the right navigation. - Open source maintainers: Publish documentation to GitHub Pages using
bundle exec jekyll serveand the Gemfile, with relative links that work in any subdirectory. - Training and knowledge bases: Use the knowledge-base layout and tag archive pages to organize articles by topic and provide a searchable reference.
How does it work?
After downloading or cloning the theme, you install Jekyll and Bundler, then either delete the Gemfile to run plain jekyll serve or keep it to use bundle exec jekyll serve with the github-pages gem. You configure sidebars and top navigation by editing YAML files, and each page's frontmatter references the sidebar it should use. To generate a PDF, you install Prince XML, add a product configuration file, and run the matching shell script.
Pros and cons
- Pros: Multiple product sidebars, PDF per product, offline viewing via relative links, Docker setup for testing, and a Commento.io integration for user comments.
- Cons: The sidebar is limited to two levels, and using the GitHub Pages gem requires Bundler due to dependency conflicts with the latest Jekyll. Prince XML is free to try but imprints a small watermark on the first page unless you buy a license.
Pricing
The theme itself is free and open source on GitHub. The only related paid service is Commento.io for comments, which starts at $5/month, and Prince XML for PDF generation requires a commercial license for watermark-free output.
Alternatives
Just the Docs is another Jekyll documentation theme with a simpler, single-sidebar layout and automatic navigation.
FAQ
Is the Documentation Theme for Jekyll free?
Yes, the theme is open source and free to download from GitHub. You do not need to pay anything to use the theme itself or to publish a site with it on GitHub Pages.
How do I build the theme locally?
Download the ZIP from the GitHub repo, install Jekyll and Bundler, then run jekyll serve from the project directory. If you keep the Gemfile for GitHub Pages, use bundle exec jekyll serve instead.
Can I use Docker to run the site?
Yes, the repository includes a docker-compose.yml. Clone the repo and run docker-compose build --no-cache && docker-compose up, then open http://localhost:4000/.
How do I generate a PDF of a product?
You need a license for Prince XML, install it, then customize the css/printstyles.css email address and create a PDF config file in pdfconfigs. Follow the pattern of the existing pdf-product1.sh script and run it.
How many levels can the sidebar have?
The sidebar supports two levels of nesting (folders and subfolders). You cannot create deeper hierarchies. Each level must have at least one topic before the next level starts.
