---
title: "Outputs"
---

Flower outputs the Data Package metadata (i.e., the content of
`datapackage.json`) in a human-readable format. Flower can output this
reformatted metadata in two ways:

1. As text to be displayed directly, e.g. in a terminal.
2. As file(s) that can be used to build documentation for a Data package
   (by default, files are in a CommonMark-compliant Markdown format with
   [Quarto](https://quarto.org) features).

Both output formats can be customised to suit different needs.

## Terminal output

When outputting to the terminal, Flower generates a plain text
representation of the Data Package metadata for a quick overview. As
with file outputs, the terminal output can be customised using different
styles.

<!-- TODO: Add examples of terminal output here or under Examples? -->

## File output: Built-in styles {#built-in-styles}

Flower is designed to be extensible to make it easier for us to develop
built-in styles and to expand them in the future. This extensibility
also accommodates users using custom
[configurations](/docs/guide/config.qmd) and creating their own
[custom styles](/docs/guide/custom-styles.qmd).

See our [Examples](/docs/examples/index.qmd) page for a list of our
built-in styles.

### `quarto-one-page` (default) {#quarto-one-page-default}

The `quarto-one-page` style generates a single Quarto Markdown file,
`index.qmd`, suitable for simpler Data Packages with a small number of
resources and/or resources with a small number of variables. This is the
default style, since it keeps the metadata together. It can be used to
create a single-page website or PDF (rendered by Quarto).

For an example, see the
[Quarto one page style](/docs/examples/quarto-one-page/index.qmd)
example.

### `quarto-resource-listing` {#quarto-resource-listing}

The `quarto-resource-listing` style generates a file structure where
each resource is documented in its own separate Markdown file, which is
useful for more complex Data Packages with many resources and/or
resources with many variables. The style includes an overview of the
resources in a
[Quarto listing style](https://quarto.org/docs/websites/website-listings.html)
in the `index.qmd` file.

With the flower study example, this style generates three files:
`index.qmd`, `resources/species-catalog.qmd`, and
`resources/growth-records.qmd`, as shown below.

:::: panel-tabset
#### Rendered output

![The rendered output of `index.qmd` with the `quarto-resource-listing` style.](/docs/design/example-output/images/example-quarto-resource-listing.png){.border
fig-alt="The rendered output for the `index.qmd` file with Flower's
quarto-resource-listing style using the flower study example. An
overview of the resources are provided in a listing."}

![The rendered output of a resource, here `resources/species-catalog.qmd`, with the `quarto-resource-listing` style. This would be the same with the `quarto-resource-tables` style.](/docs/design/example-output/images/example-quarto-resource-species-catalog.png){.border
fig-alt="The rendered output for the species-catalog resource from the
flower study example with Flower's quarto-resource-listing style. With
the `quarto-resource-tables` style, the output of the resource files is
the same."}

![The rendered output of a resource, here `resources/growth-records.qmd`, with the `quarto-resource-listing` style. This would be the same with the `quarto-resource-tables` style.](/docs/design/example-output/images/example-quarto-resource-growth-records.png){.border
fig-alt="The rendered output for the growth-records resource from the
flower study example with Flower's quarto-resource-listing style. With
the `quarto-resource-tables` style, the output of the resource files is
the same."}

#### Raw output

``` {.md filename="index.qmd"}
---
listing:
    type: table
    contents: resources
    fields: [title, subtitle, description]
    field-display-names:
        subtitle: "Name"
---

# flora: Observations of flora species and seasonal development

License: [CCO 1.0 UNIVERSAL](https://creativecommons.org/publicdomain/zero/1.0/legalcode) | Version: 1.2.3 | ID: 29b1b5e4-3f4c-4d2a-9f8e-123456789abc

A dataset containing flora species records and their observed growth stages across different environments.

## Contributors

- Jane Doe, creator, jane-doe@example.com
- John Smith, author, john-smith@example.com

## Resources
```

::: callout-note
The `index.qmd` file uses Quarto's
[listing feature](https://quarto.org/docs/websites/website-listings.html)
to generate a table listing of the resources in the Data Package, with
their titles and descriptions.

The table is interactive, allowing users to search for specific
resources based on their titles. Clicking on the title takes the user to
the corresponding resource documentation file.
:::

``` {.md filename="resources/species_catalog.qmd"}
---
title: "Flora Species"
subtitle: "species_catalog"
description: "This resource contains a catalog of flora species."
---

- Path: resources/species_catalog/data.parquet
- Primary key: `species_id`

| Title | Name | Type | Description |
| ---- | ---- | ---- | ---- |
| Species ID | `species_id` | integer | The unique identifier for each species. |
| Scientific name | `scientific_name` | string | The Latin name of the species. |
| Common name | `common_name` | string | The common name of the species. |
| Family | `family` | string | The Latin family to which the species belongs. |
```

``` {.md filename="resources/growth_records.qmd"}
---
title: "Growth Stage Records"
subtitle: "growth_records"
description: "This resource contains records of observed growth stages for various flora species."
---

- Path: resources/growth_records/data.parquet
- Primary key: `record_id`
- Foreign keys:
    - Field: `species_id`, resource: `species_catalog`

| Title | Name | Type | Description |
| ---- | ---- | ---- | ---- |
| Record ID | `record_id` | integer | The unique identifier for each growth record. |
| Species ID | `species_id` | integer | The unique identifier for each species. |
| Observation date | `observation_date` | date | The date when the observation was made. |
| Growth Stage | `growth_stage` | string | The observed growth stage of the species. |
| Location | `location` | string | The location where the observation was made. |
```
::::

### `quarto-resource-tables` {#quarto-resource-tables}

As the `quarto-resource-listing` style, the `quarto-resource-tables`
style generates a Quarto documentation structure where each resource is
documented in its own separate Markdown file. The difference lies in the
`index.qmd` file, where resources are summarized in a table format
instead of a listing. With this style, the tables are filterable and
columns can be sorted, making it easier to find specific resources and
variables within a Data Package.

::: callout-note
Since the resource documentation files are the same as those generated
by the `quarto-resource-listing` style, they are not repeated here.
Please refer to the previous section for the rendered and raw output of
the resource files.
:::

::: panel-tabset
#### Rendered output

![The rendered output of `index.qmd` with the `quarto-resource-tables` style.](/docs/design/example-output/images/example-quarto-resource-tables.png){.border
fig-alt="An example of the rendered output for the `index.qmd` file with
Flower's quarto-resource-tables style. The top is a header with the data
package name and title, with the license, version, ID, and description
shown below. Below is a contributors section and a resources section
with the resource title, name, and description shown in a table."}

#### Raw output

``` {.md filename="index.qmd"}
---
listing:
    type: table
    contents: resources
    fields: [title, subtitle, description]
    field-display-names:
        subtitle: "Name"
---

# flora: Observations of flora species and seasonal development

License: [CCO 1.0 UNIVERSAL](https://creativecommons.org/publicdomain/zero/1.0/legalcode) | Version: 1.2.3 | ID: 29b1b5e4-3f4c-4d2a-9f8e-123456789abc

A dataset containing flora species records and their observed growth stages across different environments.

## Contributors

- Jane Doe, creator, jane-doe@example.com
- John Smith, author, john-smith@example.com

## Resources
```
:::
