Output Directory

The dir key specifies the directory where the generated site files are published. It provides a simpler way to use the default fs provider without having to set the more formal destinations and provider keys.

Default output directory

The default output directory is ./build/site. If dir isn’t set, the site files are written to this directory (unless destinations are specified, which can alter this behavior).

dir key

The dir key is configured under the output key in a playbook. The dir key specifies the directory where the generated site files are published. It accepts a relative or absolute filesystem path. A relative path is expanded to an absolute path using the following rules:

  • If the first path segment is a tilde (~), the remaining path is resolved relative to the user’s home directory.

  • If the first path segment is a dot (.), the remaining path is resolved relative to the location of the playbook file.

  • If the first path segment is a tilde directly followed by a plus sign (~+), or does not begin with an aforementioned prefix, the remaining path is resolved relative to the current working directory.

The dir key can be used in combination with the destinations key. If the first destination is an fs provider and the path is not specified, it inherits the value of dir key. Otherwise, the dir key acts as an additional fs destination. When the output directory is specified from the CLI using the --to-dir option, the behavior is the same as if the dir key is set in the playbook.

Specify a relative path

In Example 1, the site will be published to a folder named launch relative to the playbook file.

Example 1. Assign a relative path to the dir key
output:
  dir: ./launch

Specify an absolute path

In Example 2, the site will be published to home/dev/docs-site/beta, regardless of where the playbook is located.

Example 2. Assign an absolute path to the dir key
output:
  dir: /home/dev/docs-site/beta

Clean the output directory

The clean key is optional and is deactivated (assigned the value false) by default. When it’s assigned the value true in a playbook, it removes the path assigned to dir recursively before generating the site.

Example 3. Activate the clean key
output:
  clean: true (1)
1 clean is activated with the value true and deactivated with false.

This key is only relevant for the filesystem (fs) provider. The key can be overridden per destination when using the destinations key.

Use this key with great care. For example, if you set dir to your home directory and clean to true, you’ll delete ALL of the folders and files in home.

The clean key can also be activated via the CLI using the --clean option.