Configuration with couscous.yml

You can define options in a couscous.yml file at the root of your repository.

That configuration file is optional.


    # 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
    # Name of the index file (default is "")

# List of directories to include in the processing (by default it's empty, so all markdown files are parsed)
# Paths are relative to the optional source path given when generating the website, repository root by default
    - docs

# List of directories to exclude from the processing (default contains "vendor" and "website")
# Paths are relative to the optional include paths given when generating the website, repository root by default
# The ".gitignore" file will also be read if it exists to exclude the directories in it
    - vendor
    - website
    - some/dir

    # Scripts to execute before generating the website
        - cp bin/couscous.phar website/
    # Scripts to execute after generating the website
        - rm website/couscous.phar

# Set this variable to use a Custom Domain
# The content of this variable will be directly inserted into the CNAME file

# Set the target branch in which to deploy the generated website
branch: gh-pages

# Any variable you put in this file is also available in the Twig layouts:
title: Hello!

# Base URL of the published website (no "/" at the end!)
# You are advised to set and use this variable to write your links in the HTML layouts

Note: any variable you put in couscous.yml is called Metadata. You can use these variables in templates for example. Learn more about this in the Metadata documentation.

Using a Domain Name with Github Pages and Couscous

To use a CNAME for your Couscous-generated documentation so that your docs point to or something similar, set the cname variable described above and point your DNS to, as detailed in the Github documentation.

Override configuration from command line

Metadata can also be specified from the command line:

$ couscous generate --config baseUrl= --config "fooBar=Baz Qux"

This command will work exactly as if the following text was included in couscous.yml:

fooBar: Baz Qux

This feature can be used to easily set flags, override metadata, or generate the same content for a variety of baseUrl values, all without the need to update couscous.yml.

Note: any CLI metadata will persist through regenerations caused by the preview command.