Use metadata collections

For every label listed under metadata in canopy.yml, Canopy creates derived IIIF Collections: one per label and one per label/value pair. These files power /metadata, related sliders, and the home-page highlights. You can also reference them directly in MDX components like <Viewer /> and <Slider />.

1. Configure metadata labels

Add or update the metadata array so it includes the labels you want to facet on.

collection:  - https://digital.lib.utk.edu/assemble/collection/collections/tdhmetadata:  - Subject  - Place  - Format  - Date

The labels must match the manifest metadata labels (case-insensitive during the build). After editing canopy.yml, restart npm run dev so the IIIF cache refreshes.

2. Verify the generated collections

During the build Canopy logs each generated collection (e.g., /api/facet/subject/war-pensions.json). Open one of the URLs in your browser to confirm it contains the expected manifests:

/api/facet/subject/war-pensions.json

If you run the project at a subpath via CANOPY_BASE_PATH, prepend it when viewing the JSON in your browser (e.g., /canopy/api/facet/subject/war-pensions.json). Delete .cache/iiif and rebuild if you change the metadata list but still see stale output.

3. Embed a collection in MDX

Use the generated collections to power sliders or viewers on custom pages. For example, to add a carousel of manifests whose subject is “War pensions”:

---title: War pensions in Tennessee--- # War pensions During the American Civil War... <Slider iiifContent="/api/facet/subject/war-pensions.json" />

You can swap <Slider /> for <Viewer /> to render a browsable IIIF collection instead of cards. <ReferencedItems /> continues to use the referencedManifests field, so use it when you need a hand-picked bibliography rather than an automatically generated list.

4. Tips

• Keep label names short but descriptive; they appear verbatim in UI headings.
• Removing a label from canopy.yml deletes the associated /api/facet/** files on the next build.
• Use metadata labels consistently across manifests. Sparse or inconsistent values make facets less useful, even though the collections will still be generated.