Using Canopy IIIF

Canopy renders static sites directly from IIIF Collections and Manifests. 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.

Collections and Manifests

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"]},      },    ],}

A IIIF Manifest provides detailed information about a single digital object, including its metadata (like title, creator, date), the images or media associated with it, and how those images are structured (for example, pages in a book or views of an artwork). Each Manifest is also a JSON document that adheres to the IIIF Presentation API specifications.

{  "@context": "http://iiif.io/api/presentation/3/context.json",  "id": "https://iiif.io/api/cookbook/recipe/0032-collection/manifest-01.json",  "type": "Manifest",  "label": {"en": ["The Gulf Stream"]},  "metadata":    [      {        "label": {"en": ["Artist"]},        "value": {"en": ["Winslow Homer (1836–1910)"]},      },      {"label": {"en": ["Date"]}, "value": {"en": ["1899"]}},    ],  "items": [...],}

Configuration

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:

title: Works by Winslow Homercollection:  - 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

In certain cases, Manifests may not be present in a Collection. You can still include these by manually adding their URIs directly to the manifest list in canopy.yml:

title: Works by Winslow Homermanifest:  - https://iiif.io/api/cookbook/recipe/0032-collection/manifest-01.json  - https://iiif.io/api/cookbook/recipe/0032-collection/manifest-02.json

In both cases, 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.

Content Authoring

To extend IIIF material, Canopy supports the authoring of markdown files with a special component syntax (MDX). These additional content pages can include IIIF assets from your manifests. See the Content section for details on how to author MDX files with IIIF resources. Below is a simple example of an MDX file that references the Gulf Stream Manifest from above and includes a viewer component to render it:

---title: Warm and Deadly Seasdescription: A look at Winslow Homer's 1899 painting The Gulf Stream.referencedManifests:  - https://iiif.io/api/cookbook/recipe/0032-collection/manifest-01.json--- ### Example: Warm and Deadly Seas In 1899, Winslow Homer painted _The Gulf Stream_, a powerful depiction of a lone manadrift in a small boat amidst turbulent seas. The painting captures the raw force ofnature and the vulnerability of humanity against its vastness. In this late 19th-centurywork, Homer illustrates not only the physical dangers of the sea but also the existentialthreats faced by individuals in an indifferent universe. <Viewer iiifContent="https://iiif.io/api/cookbook/recipe/0032-collection/manifest-01.json" />

This page would be accessible at /about/warm-deadly-seas.html and include the viewer rendering the Manifest specified. The referencedManifests frontmatter key ensures that any metadata from the Manifest is indexed for search on this page as well.

Example: Warm and Deadly Seas

In 1899, Winslow Homer painted The Gulf Stream, a powerful depiction of a lone man adrift in a small boat amidst turbulent seas. The painting captures the raw force of nature and the vulnerability of humanity against its vastness. In this late 19th-century work, Homer illustrates not only the physical dangers of the sea but also the existential threats faced by individuals in an indifferent universe.