buildr-users mailing list archives

Site index · List index
Message view « Date » · « Thread »
Top « Date » · « Thread »
From Assaf Arkin <>
Subject Update to site and documentation
Date Mon, 16 Mar 2009 22:57:30 GMT
Last week I switched our documentation system to use Jekyll[1]. Before the
switch we used Docter to generate the Web site from Textile documents and
HAML templates. Jekyll replaces that with Textile documents and Liquid

The main reason for the switch: I have a strong preference to maintain as
little code as possible, and since I was the one maintaining Docter, I was
also always on the lookup to replace it with other people's code. Jekyll was
built for Github page[2], so it's bound to get more care and attention. It's
also, for those of you using Github pages, one less tool to learn.

The only change to the Textile files was the title/layout header that Jekyll
requires and using different tags to markup code snippets. Syntax
highlighting is now done by the more powerful Pygments, a Python app. PDF
generation still done by PrinceXML.

If you like the idea of using Textile to generate HTML and PDF, there are a
few more tips on my blog[3].

Another change, we're not using the Hanna template for the API documentation
(RDocs). If you look at the left-side navigation pane[4], you'll notice a
search bar that does as-you-type method search across all classes/modules.

While on the subject of documentation, the Web site (and PDF) have two
sections called Recipes and Troubleshooting. The Wiki has two sections
called "Buildr How Tos" and "Common Problems and Solutions". I'd like to
consolidate both.

The Wiki is much easier to edit than the Web site, so my preference right
now is to consolidate these duplicates and move them over to the Wiki, with
a link from the Web site navigation. Where it says Recipes right now it will
say HowTo and link to the Wiki instead of another page on the site.

The downside is that these two pages will no longer be part of the PDF.



  • Unnamed multipart/alternative (inline, None, 0 bytes)
View raw message