Configuration files

Configure Flower’s settings and output options using a configuration file.

Flower can be configured via the command line interface (CLI), the Python interface, or a configuration file. This guide covers configuration files—for the CLI, see the CLI guide. We don’t have a guide for the Python interface, as Flower is primarily designed to be used as a CLI tool. If you’re interested in the Python interface, check out the Python design document.

Configuration files

A configuration file lets you set your preferences once, so you don’t have to repeat them every time you run flower build. Flower supports two configuration files: .flower.toml and pyproject.toml. These files should be placed in the root of your project—Flower will find them automatically.

Use .flower.toml if you prefer a file dedicated to Flower settings, or pyproject.toml if your Data Package is a Python project that already uses pyproject.toml and you prefer to keep all config settings in one place.

Note

Settings provided via the CLI or Python interface always take priority over the configuration file. Some settings—like specifying a remote source or configuring the view command—can only be set via the CLI or Python interface, not from the configuration file.

Configurable settings

Before diving into editing your configuration, let’s see which settings can be configured via the configuration file:

  • style: How metadata is structured in the output files. Defaults to quarto-one-page.

  • output-dir: The directory where Flower will save the output files. Defaults to docs/.

  • template-dir: The directory that contains the template files for a custom style. If template-dir is set, style is ignored. Not set by default. For more information on how to create custom styles, see the custom styles guide.

For examples of Flower’s built-in styles, see the examples page.

Configuration file syntax

Both configuration files use the same TOML syntax. First, we’ll use .flower.toml in the examples below, then show the minor difference for pyproject.toml.

In the root of your project, create a .flower.toml file and open it in your favorite text editor. To change the output directory to my-docs, you can add the following line to the file:

.flower.toml
output-dir = "my-docs/"

Now, when you run flower build in your terminal, the output directory will be changed to my-docs.

If you would like to use a custom style with your own templates in a my-templates directory, add the following line to .flower.toml:

.flower.toml
template-dir = "my-templates/"

With both these settings, the .flower.toml file would look like this:

.flower.toml
output-dir = "my-docs/"
template-dir = "my-templates/"

If you prefer to configure Flower via pyproject.toml, the syntax is almost the same as above; the only difference is that you need to include a heading to indicate where in the file Flower can find the settings. Open up your pyproject.toml (or create one in the root of your project) and add a new table header [tool.seedcase-flower]. Then put the same configuration settings as you used above in .flower.toml below this table header.

pyproject.toml
[tool.seedcase-flower]
template-dir = "my-templates/"
output-dir = "my-docs/"

Once your configuration file is in place, you can run flower build and Flower will pick up your settings automatically.