/ Projects

BlackDoc, A Jekyll Theme

I recently added a new section in my website to publish my code cheatsheets. I added this new section for my own use as a quick reference to easily find the syntax and basic usage of language or software that I use for my projects.

While working on it, I decided that it needs to be a two-column layout with a scrolling sidebar, essentially a master-detail view. The main navigation will be listed in the sidebar and its contents displayed in the right column. One current limitation of Ghost is that it does not support nested static pages, meaning you can't have URLs for static pages in the format -- http://website.com/dir1/dir2/page1. You simply can't add /s into the url slug of a post or page. Hopefully, this feature will be added in future versions of Ghost.

To work around this problem, I published my new cheatsheets section using Jekyll, a Ruby-based static site generator. It's the perfect solution if you just want to create a static website using Markdown text files. Jekyll is also the engine behind GitHub Pages, and is one of the popular static site generators. So now, I just need a theme for Jekyll to complement the colour scheme of my main website.

I did a quick search which led me to find the Hyde Jekyll theme. I found it to be a good starting theme because it already includes sample templates, pages, posts, and styles. However, it still doesn't have the features that I really need, and when I searched, I didn't find any good Jekyll theme with the master-detail layout that I was looking for. And so, I decided to create my own Jekyll theme. And this is how BlackDoc came about. Hopefully, someone will find this theme useful as well in their own projects.

About BlackDoc

BlackDoc is a two-column Jekyll theme that's ideal for websites that require a master-detail layout for viewing of content. It is ideal for sites such documentation, cheatsheets, lyrics, notes, etc. It also looks great in black background and the sidebar can display scrolling content. It's based on Poole, the Jekyll butler, and the Hyde theme.

Demo GitHub Download BlackDoc

Quick Setup

Install BlackDoc using the following commands.

~ gem install jekyll
~ git clone git@github.com:karloespiritu/BlackDoc.git
~ cd BlackDoc
~ jekyll serve
# => Now browse to http://localhost:4000

BlackDoc Features

In addition to the features of Poole and Hyde, BlackDoc theme adds the following:

  • Scrolling sidebar with a thin scrollbar to allow displaying of numerous top-level content.
  • Elements and classes of the Hyde theme were updated to look great in black background.

Browser support

BlackDoc theme supports most modern browsers and only compatible with Internet Explorer 9 and above.


BlackDoc is a free Jekyll theme under MIT License and hosted with GitHub. Head to the GitHub repository to download.