Couscous, Generate Beautiful Github pages from Markdown

Couscous is a PHP tool that generates beautiful GitHub pages website from your markdown documentation. Everything you need to do is to write your documentation in Markdown inside your repository, versioned with your code, then it will turn those Markdown files to HTML. As simple as that !

It’s available as a Phar file, that you can install with Composer or download it directly, then you can run it on your current project directory. All your .md files will be scanned and converted to html, then you can customize the website generated, or simply deploy to your github pages !

Getting started with Couscous

To install it with composer you can run

$ composer global require couscous/couscous

Or simply download the Phar file and copy it to your local bin. So whether you have it locally or globally, you can immediately generate your first html from the README.md file by running :

$ couscous preview

You can then browse http://localhost:8000 to preview the generated file. Of course you can specify a specific IP address and port in the preview argument, if the port 8000 is already used locally.

If you are happy with the generated page you can deploy it to github pages, and this time it will be published in the gh-pages branch of your git repository. This will remove everything that exists in the gh-pages branch, commit in your name, and push to GitHub. So to deploy simply run :

$ couscous deploy

Templates and customization

You probably won’t need to customize, as the solution already provides nine simple and beautiful ready to use templates. But if you are still interested you can create or customize your own template. The documentation is available and will guide you, however you can simply get started by cloning the default basic template and customize it.

Templates could be remote or embedded with the website, so you will have to choose between using the directive url or directory in the configuration :

template:
    # Name of the directory containing the website template (default is "website")
    directory: website
    # Or if you are using a remote template, you can set the Git URL
    url: https://github.com/CouscousPHP/Template-Light.git
    # Name of the index file (default is "README.md")
    index: index.md

There are lots of other options for example if you wish to generate and deploy pages to a branch other than gh-pages, use the --branch option. Or you can update with the self-update directive.

Overall, Couscous is really good if you know how to cook it, but the website generator from Markdown is really simple and useful, but best of all it will help automate your github website generation from Markdown without efforts ! Released under an MIT license.

More information at https://couscous.io/