Get Started

Stand up a Canopy project in just a few minutes: use the template, drop in your IIIF Collection, and let GitHub Pages do the heavy lifting. This walkthrough keeps everything inside the browser so you can focus on getting to work building your narratives and leaving advanced customization for later.

Build a new project from the template
canopy-iiif/templateDocumentation

1. Create a new repository

  1. Visit the canopy-iiif/template repository.
  2. Be sure to login to GitHub if you haven’t already.
  3. Click Use this template → Create a new repository.
  4. In the General section choose your GitHub account or organization and give the repository a name (for example my-canopy-site)
  5. Under the Configuration, choose the visibility as Public so Pages can publish.
  6. Click Create repository. GitHub then copies the template and wires up the workflows for you.

2. Publish with GitHub Pages

The template ships with a GitHub Pages workflow (.github/workflows/pages.yml) that will host your project without requirement of a server. After each commit to main it will build and deploy your site automatically. To enable Pages for the first time:

  1. Go to Settings → Pages in your new repository.
  2. In the Build an deployment section, ensure GitHub Actions is selected as the source (this may be already set).
  3. Navigate back to the Code tab of your repository and select the gear icon ⚙️ next to the About section in the aside of the page.
  4. Select the Use your GitHub Pages website option and your unique site URL will appear.
  5. Click Save changes and you will see link to your site populate in the About section.

That URL is will be your public and published Canopy deployment hosted entirely by GitHub Pages. We now need to configure it to point to your IIIF Collection and initialize rebuild of Canopy.

3. Configure canopy.yml

canopy.yml
collection:  - https://digitalcollections.lib.washington.edu/iiif/2/korean/manifest.jsonfeatured:  - https://cdm16786.contentdm.oclc.org/iiif/korean:138/manifest.jsonmetadata:  - Author  - Place of Publication

Every template includes canopy.yml at the repository root. This single file drives the build of your Canopy site. Open it and replace the demo collection and featured manifests with your own. There are many other configuration options available (see documentation); but to get the most out of Canopy, you will want to set the following:

SyntaxPurpose
collectionA list of IIIF Collection URI(s) that Canopy will ingest.Required
featuredA list of IIIF Manifest URI(s) to highlight on the homepage. These should be part of the Collection(s) above.Optional
metadataA list of Metadata label names you want to turn into search facets and UI components in your project.Optional
  1. From the Code tab, click the canopy.yml file to open it in the file viewer. Then click the pencil icon ✏️ in the upper right to edit the file directly in GitHub’s web editor.
  2. Replace the demo URIs under collection and featured with your own Collection(s), Manifest(s), and desired metadata facets.
  3. Click the Commit changes button above the file viewer, and confirm then confirm the commit again to save your changes and trigger a rebuild.

4. Visit your new site

After a few moments, your GitHub Actions workflow will complete building and deploying your site. You can monitor the progress by clicking the Actions tab in your repository. Once the workflow completes successfully, visit your GitHub Pages URL (found in Settings → Pages or the About section of your repository) to see your new Canopy site live!

What’s next?

  • Configure your theme in canopy.yml to customize the look and feel and explore customizing further with TailwindCSS in /app/styles.
  • Create your own contextual pages under content/ and link to manifests via referencedManifests frontmatter.
  • Add components referencing items in your collections using <Viewer />, <Image />, and <ReferencedItems /> to enrich the storytelling .