Contributing a built-in style

Add your own style to Flower’s built-in styles.

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 and clone your fork locally.

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 the style creates and which metadata is displayed in each file.

First, follow the custom style guide to create the templates and add the sections.toml locally.

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 (e.g., my_new_style).

Note

A terminal style for the view command must be a single-page output style, meaning it can only use a single [[one]] section. view ignores output-path since it doesn’t output files and single-page styles can be used by build as well.

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 something like:

src/
└── seedcase_flower/
    └── styles/
        ├── ...
        └── your_new_style/
            ├── sections.toml
            ├── package.qmd.jinja
            └── resource.qmd.jinja

Your style may have fewer or more templates than shown above—and may use different parts of the datapackage.json, e.g., contributors, license, or schema fields. Remember to give your templates descriptive names. The .qmd extension serves as an example; Jinja2 can produce any plain text format (e.g., .html, .md, .yml).

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

src/seedcase_flower/styles.py
class Style(Enum):
    # ...
    your_new_style = "your_new_style"

If your style is also a terminal style for the view command, add it below the existing styles in the ViewStyle enum as well:

src/seedcase_flower/styles.py
class ViewStyle(Enum):
    # ...
    your_new_style = "your_new_style"
Important

For the new style to work properly, the string value of the enum member (e.g., "your_new_style") must exactly match the folder name.

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 for your tests. For example, to test with build, run:

Terminal
uv run seedcase-flower build docs/includes/datapackage.json \
    --style your_new_style --output-dir docs/examples/your-new-style

This will build the documentation using your new style and output it to the docs/examples/your-new-style folder. You can then check the output files to ensure that the style is applied correctly and that the metadata is displayed as expected.

Adding the new style to the examples page

When your new style is working properly, please add it to the Examples page. This will allow users to see what the style looks like and how it can be used. To add your style to the Examples page, add the link to the folder you just created with the test command above (docs/examples/your-new-style) to the list of styles.

Making a pull request

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

  • Run just run-all in the terminal to ensure that all tests and linting checks pass.
  • Put your changes on a new branch with a name that follows our branch naming conventions.
  • Commit your changes following Conventional Commits.
  • Push your branch to GitHub.
Tip

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. We appreciate you taking the time to contribute and will review your pull request as soon as possible.