Couscous requires PHP 5.4 or above on your machine.
If you have already set up a global install of Composer just run:
$ composer global require couscous/couscous
You can also add Couscous as a dependency for a project with
composer require couscous/couscous.
Be aware that in order for Couscous to be awesome it will install a good amount of other dependencies. If you rather have it self-contained, use the Phar method just below.
Alternatively, you can download couscous.phar:
$ curl -OSL https://couscous.io/couscous.phar
Please note that as Github is using a DDOS protection system, if using CURL fails, just manually download the phar file.
If you want to run
couscous instead of
php couscous.phar, move it to
$ chmod +x couscous.phar $ sudo mv couscous.phar /usr/local/bin/couscous
Please note that you need to have the
phar extension installed to use this method. It should be installed by default on most OSes.
Let's not waste time and run:
$ couscous preview
Couscous will take every
*.md file it finds in your current directory and convert it to HTML files, keeping the same directory structure (
README.md files will be renamed to
index.html). You can then visit http://localhost:8000/ to preview the result!
Be assured that this command will not modify your repository.
Liking what you see? The default template comes with a header and an optional left menu (which is hidden if it is not configured). You can configure all that by creating a
couscous.yml and checking out all the options on the template's homepage.
Specify an address
couscous preview will work on most installations, there may be times where you need to specify the IP address the server should listen to (for example if using a VM, Vagrant or Docker). To specify the IP address, in this example
$ couscous preview 0.0.0.0:8000
Happy with the result? Here is how to deploy:
$ couscous deploy
Couscous will generate the website (in a temp directory) and publish it 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.
The website is now online: https://your-username.github.io/your-project/.
deploy command will not change anything in your current branch (e.g. master branch). It will only affect the
Deploying to a custom branch
If you wish to have Couscous generate and deploy pages to a branch other than
gh-pages, use the
--branch option. For example:
$ couscous deploy --branch master
Customizing the template
Couscous provides a default template (and a few others to choose from), but you can of course come up with your own. Writing templates is really simple, and it is all explained in the templates documentation.
If you are using the phar file, you can update Couscous by simply running the
$ couscous self-update