Using Canopy IIIF

Canopy renders static sites directly from IIIF Collections! These docs will walk you through the configuration options, content examples, and features available when building with Canopy. Canopy sites can be built in minutes and hosted anywhere static files can be served. The builder fetches manifests and generates layouts from Markdown files leaving you with a bundle of HTML, CSS, and basic javascript that can be deployed anywhere. All examples in this section are plain MDX so they can be copied directly into your own content/ directory to get started.

How to use these docs

• Start with Configuration to understand the canopy.yml settings in detail.
• Use Guides for task-driven walkthroughs of common use cases.
• Refer to Content to understand how to author MDX files with IIIF assets.
• Track what shipped in each semantic version on the Releases page.

What is a IIIF Collection?

A IIIF Collection is a JSON document that lists other IIIF resources, typically Manifests or other Collections. Collections can represent any grouping of IIIF Manifests, such as an archive, library, or museum's digital holdings. Each Manifest within a Collection describes a single object (like a book, artwork, or video) and includes metadata, images, and structure. Canopy ingests one or more Collection URIs to build a project. Each Manifest listed in the Collection then becomes a page in the site with normalized metadata, thumbnails, and links.

Below is a simple example of a IIIF Collection containing two Manifests including paintings by the American artist Winslow Homer:

{  "@context": "http://iiif.io/api/presentation/3/context.json",  "id": "https://iiif.io/api/cookbook/recipe/0032-collection/collection.json",  "type": "Collection",  "label": {"en": ["Simple Collection Example"]},  "items":    [      {        "id": "https://iiif.io/api/cookbook/recipe/0032-collection/manifest-01.json",        "type": "Manifest",        "label": {"en": ["The Gulf Stream"]},      },      {        "id": "https://iiif.io/api/cookbook/recipe/0032-collection/manifest-02.json",        "type": "Manifest",        "label": {"en": ["Northeaster"]},      },    ],}

Working with Canopy

Canopy works with both Presentation 3.0 API and the older Presentation 2.x. If the collection noted above were provided to Canopy, the canopy.yml file would reference Collection URI id which is also the URL where the collection document is hosted:

collection:  - https://iiif.io/api/cookbook/recipe/0032-collection/collection.json

As this collection references two manifests, each would have its own relative page on the site:

• /works/the-gulf-stream.html
• /works/northeaster.html

Each page would include normalized metadata from the Manifest, thumbnails, and links to view the object in a IIIF viewer. Manifest metadata is indexed for search along with any other MDX files under content/. Theming offers some baseline options with the ability to supply optional CSS overrides. With a site built, you can deploy it anywhere static files can be served, such as GitHub Pages or your own web server. And best of all, Canopy handles all the heavy lifting of fetching, normalizing, and rendering IIIF resources so you can focus on building great experiences.