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 and an fs provider path isn’t specified, the site files are written to this default directory.

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 both an fs provider path and dir are specified, the value assigned to dir overrides the first fs provider path. When the output directory is specified from the CLI using the --to-dir option, it also overrides the dir and first fs provider path in a 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 only applies to the filesystem provider.

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.