Home / Blog / Jekyll, YUI and Github: a great combination

History always repeats itself and sometimes that's good. Here's a second chance to be part of it: tmdtc.com

Jekyll, YUI and Github: a great combination

I was looking for a way to easily publish documentation for Dedomenon , the information storage engine behind MyOwnDB.com which I'm again developing heavily. And as I'm developing, I want to write complete and up to date documenation. I was looking for a hosted solution, which I wouldn't have to maintain myself, but I still wanted to have full control of the content, so I could easily move to another solution in the future if needed.

I thought of a wiki, but didn't go for it as I'm not sure of the export functionalities of hosted solution and the ease of integrating the content in a new solution. Each wiki seems to have its own markup, and I'm afraid that an export functionality is not enough to ensure long term availability of the content.

I then looked at Jekyll , a tool to maintains web sites (and more specifically blogs) developed by Github . It has some very compelling functionalities:

  • can be hosted as Github pages, which responds to my hosting requirement
  • content is written in markdown or textile. As I had some content in textile format already, it's a plus!
  • I can write content with my prefered editor (vim)
  • Hosting on github means I can (I must!) handle the content's history with git
  • categorizes content based on the directories hierarchy

The only problem I had it that it didn't seem a ready-made solution to handle non-blog oriented website. But after some work, I got a working solution which is worth sharing: Jekyll Base .

Jekyll Base is simply the basic directory hierarchy expected by jekkyl, with a ready-to-use template offering:

  • Cross-browser layout thanks to YUI Grids
  • FreshPick based CSS
  • Use of Yahoo’s CDN for delivery of YUI Grids files
  • Google Analytics activated by putting site id in config file
  • Google Ajax Search activated by putting your API key in the config file
  • Listing of documents in current section
  • List of subsections
  • Breadcrumbs to help in navigation

It includes 2 helpers script to add sections and pages. You can of course see it in action at http://dedomenon.github.com/documentation .

Thanks to the use of YUI Grids, the template is very simple, though will render in all browser as expected. Combined with the FreshPick CSS, it gives an acceptable solution. This is particularly important as I'm really not a designer.

Jekyll Base source is available on github and its documentation is of course self-managed and hosted as Github pages at http://raphinou.github.com/jekyll-base/


Log in or create a user account to comment.

I'm available for hire 

If you're looking for someone to temporarily join your IT team, or if you need help to put IT to work in your company, I'm ready to help. Contact me now !

Mon Tue Wed Thu Fri Sat Sun
    1 2 3 4 5
6 7 8 9 10 11 12
13 14 15 16 17 18 19
20 21 22 23 24 25 26
27 28 29 30 31