Contributing a built-in style

Add your own style as a built-in style in Flower.

Flower comes with a number of built-in styles to use with the build or view commands. This guide explains how to contribute a new built-in style that will be available to all Flower users.

Before you begin, fork the Flower repository on GitHub and clone your fork locally. Make the following changes in your local copy.

Creating a new style

Built-in styles consist of the following files:

  • Jinja2 template files: these define the layout of the generated documentation.
  • A sections.toml configuration file: this defines how many output files will be created and which metadata will be displayed in each file.

First, create the template files and add the sections.toml configuration file for your style by following the guide for creating custom styles. If you are writing a terminal style for use with the view command, do not put an output-path for your sections in sections.toml.

Use the name of your style as the name of the template folder. The name should be short, descriptive, and distinct from existing built-in styles. It should be given in snake case.

Adding the style as built-in

Next, in your local copy of the Flower repo, place the template folder into the src/seedcase_flower/styles/ folder. The file structure should now look like:

src/
└── seedcase_flower/
    └── styles/
        ├── ...
        └── your_new_style/
            ├── sections.toml
            ├── template_1.qmd.jinja
            ├── template_2.qmd.jinja
            ├── ...
            └── template_last.qmd.jinja

Finally, add your style to the appropriate style enum (Style or ViewStyle) in src/seedcase_flower/styles.py. All styles are defined in the Style enum, while styles suitable for terminal output with view are also added to ViewStyle. For example, if the your_new_style is a new style, you would include it like so:

src/seedcase_flower/styles.py
class Style(Enum):
    """Built-in styles for generating documentation."""

    quarto_one_page = "quarto_one_page"
    quarto_resource_listing = "quarto_resource_listing"
    quarto_resource_tables = "quarto_resource_tables"
1    your_new_style = "your_new_style"
1
Add your new style as shown on this line.
Important

For the new style to work properly, the name of the enum member must be exactly the same as the folder name for the new style.

Testing the new style

Once the new style is in place, be sure to test that it works as expected by running the view or build command as appropriate. You can use the example Data Package included in Flower to test:

Terminal
uv run seedcase-flower build --source docs/includes/datapackage.json --style your-new-style

Making a pull request

Before submitting a pull request with your changes, make sure you:

You might find it helpful to read through our contributing guidelines. If you would like a more detailed walkthrough of creating commits and submitting pull requests, have a look at the relevant sections of our Guidebook.

You’re now ready to open a pull request from your fork to the main Flower repository on GitHub.