Reworked documentation for GitHub pages website.

[reload-deploy]

• Use couscous (https://github.com/mnapoli/Couscous) to mirror repository documentation on the website.
• Added a bit of design based on Bootstrap and the Bootswatch Superhero theme (http://bootswatch.com/superhero/).
• Updated documentation with content from current GitHub pages site.

Updating documentation should now be a matter of installing couscous and running “couscous deploy”.

The result should look something like this:

[danquah]

w00t!!111

[luckow]

wow, holy moly!

[xendk]

I'm still not convinced that couscous is the bees knees. A site and a readme is two very different things, and using the same for both is gonna shaft one of them. Either you'll have a site that's a readme with a logo in the corner, in which case you might as well just use the github repository page, or you'll have a readme sprinkled with HTML and image URLs which is rather annoying when you open the readme from the command line.

Also, they serve different purposes. A site is marketing, it's what's trying to make people install it, the readme is documentation, it's where people look for help. For instance, how to set up sudo to restart Apache don't need to be on the site frontpage, but it either needs to be documented in the readme, or the readme has to have a pointer to it.

Like the theme though.

[kasperg]

The main problem I see with GitHub sites is that they are not keep up to date because the workflow of updating them is separated from the normal development workflow. Couscous makes that easier.

Either site or README might suffer but I do not think the damage is that bad compared to the upside of easy maintenance.

• The current screenshot is a README with a logo. I think it adds something to the project compared to the GitHub repository. You could add more imagery with CSS or in the template if needed.
• Markdown supports images, the current README already contains images, it will not look pretty in the command line. With a bit more effort I expect that named links and break-tags I introduced could be removed again.
• I would think having a Getting started section in a README is quite useful and enough markering for my taste.
• Setting up sudo might not be front page material but I do not think it is a problem having it at the bottom of the site.

Anyway: If you like the theme it should be possible to extract the basic HTML template and CSS and use it with separate content.