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.
• Visit Internationalization when configuring multiple locales, language toggles, and translated navigation.
• 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.

The British India art demo includes Northwestern University Libraries' Donald K. Adams and Lawrence D. Stewart Collection of Prints. This excerpt shows two of its Manifests. Other entries and fields are omitted.

{  "@context": ["http://iiif.io/api/presentation/3/context.json"],  "id": "https://api.dc.library.northwestern.edu/api/v2/collections/94536627-cfdf-413c-852b-0cb16d986da3?as=iiif",  "type": "Collection",  "label": {"none": ["Donald K. Adams and Lawrence D. Stewart Collection of Prints"]},  "items": [    {      "id": "https://api.dc.library.northwestern.edu/api/v2/works/c26591b2-994b-4ba3-a87e-9124419fa91b?as=iiif",      "type": "Manifest",      "label": {"none": ["View of the city and fortress of Tonk in Rajpootana"]}    },    {      "id": "https://api.dc.library.northwestern.edu/api/v2/works/4bdb5a22-6c7f-498d-8e6e-e49ea9bc4778?as=iiif",      "type": "Manifest",      "label": {"none": ["The town & pass of Boondi, in Rajpootana"]}    }  ]}

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.

The Manifest for The town & pass of Boondi, in Rajpootana supplies its title and date. This excerpt omits the Canvas data and other fields; follow the link for the complete Manifest.

{  "@context": "http://iiif.io/api/presentation/3/context.json",  "id": "https://api.dc.library.northwestern.edu/api/v2/works/4bdb5a22-6c7f-498d-8e6e-e49ea9bc4778?as=iiif",  "type": "Manifest",  "label": {"none": ["The town & pass of Boondi, in Rajpootana"]},  "metadata": [    {      "label": {"none": ["Date"]},      "value": {"none": ["1826 to 1830"]}    }  ]}

Configuration

Canopy works with IIIF Presentation 3.0 and 2.x. To use this Collection, add its id to canopy.yml. The ID is also the URL of the Collection document:

title: Art in British Indiacollection:  - https://api.dc.library.northwestern.edu/api/v2/collections/94536627-cfdf-413c-852b-0cb16d986da3?as=iiif

Each Manifest gets a work page. The two shown above appear at:

• /works/view-of-the-city-and-fortress-of-tonk-in-rajpootan.html
• /works/the-town-and-pass-of-boondi-in-rajpootana.html

You can also build from individual Manifests. To include only these two works, use a manifest list instead of the Collection:

title: Art in British Indiamanifest:  - https://api.dc.library.northwestern.edu/api/v2/works/c26591b2-994b-4ba3-a87e-9124419fa91b?as=iiif  - https://api.dc.library.northwestern.edu/api/v2/works/4bdb5a22-6c7f-498d-8e6e-e49ea9bc4778?as=iiif

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

Use MDX to add context to IIIF materials and embed components in Markdown. This page references the Boondi Manifest and displays it in a viewer. See Content for more examples.

---title: A View of Boondidescription: Explore a print of Boondi from Northwestern University Libraries.referencedManifests:  - https://api.dc.library.northwestern.edu/api/v2/works/4bdb5a22-6c7f-498d-8e6e-e49ea9bc4778?as=iiif--- ### Example: A View of Boondi Northwestern University Libraries dates _The town & pass of Boondi, in Rajpootana_to 1826 to 1830. Its catalog describes the town on a hillside, with the Raja's palacepartway up and fortifications extending toward the summit. <Viewer iiifContent="https://api.dc.library.northwestern.edu/api/v2/works/4bdb5a22-6c7f-498d-8e6e-e49ea9bc4778?as=iiif" />

This page appears at /about/boondi.html. The referencedManifests frontmatter key links it to the work and supplies the Manifest metadata selected for search.

Example: A View of Boondi

Northwestern University Libraries dates The town & pass of Boondi, in Rajpootana to 1826 to 1830. Its catalog describes the town on a hillside, with the Raja's palace partway up and fortifications extending toward the summit.