Couscous 20/01/2016
Couscous is a static site generator tool for your Github projects, converting all markdown files into an online documentation hosted by Github Pages.
Installation
The first step is to get the tool:
curl -OS http://couscous.io/couscous.phar
sudo mv ./couscous.phar /usr/loal/bin/couscous
Then we need to create a couscous.yml file at the root of our Github Project:
template:
url: https://github.com/CouscousPHP/Template-Light.git
baseUrl: http://<user-name>.github.io/<project-name>
title: <project-title>
subTitle: <project-short-decription>
github:
user: <user-name>
repo: <project-name>
menu:
items:
home:
text: Home
relativeUrl:
<article-name>:
text: <article-title>
relativeUrl: <article-filename>.html
Of course <user-name>, <project-name>, <project-title>, <project-short-decription>,
<article-name>, article-title and article-filename need to be replaced accordingly.
Generating the Documentation
Couscous is going to automatically use *.md files found in the project (e.g. README.md).
The menu section in couscous.yml will generate a handy menu. Usually home
as well as the rest of the documentation is listed here, for example:
menu:
items:
home:
text: Home
relativeUrl:
installation:
text: Installation
relativeUrl: doc/01-installation.html
compatibility:
text: Compatibility
relativeUrl: doc/02-compatibility.html
benchmark:
text: Benchmark
relativeUrl: doc/03-benchmark.html
To generate the documentation, simply run:
couscous preview
This will launch a local server, allowing us to preview the documentation at http://localhost:8000.
Once satisfied, we can run:
couscous deploy
This will generate the definitive HTML, commit them in a gh-page branch and push
it, making it available online.
Conclusion
Couscous provides the possibility to host nice documentation for Github projects, thanks to its simplicity.