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.
- 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.