Markdown

Every page in content/ is an .mdx file: Markdown plus JSX components. The quickest way to see everything in action is to open content/about/markdown.mdx, which contains headings, quotes, lists, tables, images, and footnotes. This guide recreates those patterns in smaller chunks.

File layout

• Nested folders map to URL paths (content/guides/index.mdx → /guides/).
• index.mdx inside any directory becomes that directory’s landing page.
• Run npm run dev to preview changes with live reload.

Supported front matter

Add YAML at the top of each file to set metadata and opt into search or reference features. These are the keys Canopy reads today—older fields like image are ignored and can be deleted.

Example:

---title: January 1955 Correspondencedescription: Seven letters between Amanda Ira Aldridge and Mihailo KovačevićreferencedManifests:  - https://api.dc.library.northwestern.edu/api/v2/works/46de2c91-3a29-4525-939e-ee17073f3a7e?as=iiif  - https://api.dc.library.northwestern.edu/api/v2/works/bb968afb-7857-46bd-9392-d8617a93cc9f?as=iiifsearchSummary: Letters exchanged during January 1955.---

Home page flags

content/index.mdx recognizes two more keys:

• showHero: show the featured-manifest hero (true/false).
• showHighlighted: render metadata sliders beneath the hero.

---title: Amanda Ira Aldridge CorrespondencesshowHero: trueshowHighlighted: true---

Core Markdown patterns

Text, emphasis, headings

# Heading level 1 ## Heading level 2 Paragraphs can mix _italics_, **bold**, and `inline code` for props like `iiifContent`.

Lists and blockquotes

1. Gather manifests.2. Draft copy.3. Link to supporting resources.[^1] - Highlight takeaways.- Pair prose with citations. > Blockquotes surface letters, diary entries, or reviewer notes.

Images

![Stacked archival boxes](https://picsum.photos/seed/canopy-stacks/800/360) <Image  src="https://ids.lib.harvard.edu/ids/iiif/9013118"  isTiledImage  height="400px"  alt="Detail from The Summons"  caption="Use the Image component for pan-zoom or annotated figures."/>

Tables and definition lists

| Feature | Syntax | Notes || ------- | ------ | ----- || Tables  | `| col | col |` | Align columns with pipes and separators. || Code    | ```` ```js const id = 1; ``` ```` | Add a language hint for syntax highlighting. | Term: Definition lists keep glossaries tidy.

Code blocks and checklists

```txt filename="snippet.mdx"<Viewer iiifContent="https://…" />``` - [x] Document the build inputs.- [ ] Leave one unchecked item as a reminder.

Footnotes

Refer to prior research when needed.[^source] [^source]: Footnotes collect citations at the end of the page.

Components inside Markdown

Embed Canopy components inline to tie Markdown narratives back to IIIF assets:

• <Viewer /> for a full manifest experience.
• <Image /> for single-canvas figures.
• <Slider /> for curated carousels.
• <ReferencedItems /> / <References /> to connect essays and works.

Because MDX is just React, you can pass props directly in the markup. Keep component usage minimal when possible so the prose stays readable in raw form.

Home page content

content/index.mdx controls the landing page. Front matter toggles the hero interstitial sourced from featured manifests and the highlighted metadata sliders that render below it.

---title: Amanda Ira Aldridge CorrespondenceshowHero: trueshowHighlighted: true--- <Container>  <p>Introduce the collection, cite your institution, or drop inline media.</p>  <ButtonWrapper>    <Button href="/works" label="Browse works" />    <Button href="https://example.org" label="About the project" variant="secondary" />  </ButtonWrapper></Container>

Hero interstitial

When showHero is true, <Interstitials.Hero /> renders at the top of the page and rotates through the featured manifests listed in canopy.yml.

collection:  - https://collections.example.org/iiif/harpsichordsfeatured:  - https://collections.example.org/iiif/manifest/alpha  - https://collections.example.org/iiif/manifest/bravo  - https://collections.example.org/iiif/manifest/charliemetadata:  - Subject  - Creator

Behavior notes:

• Featured manifests are normalized during the IIIF build so duplicates collapse to a single entry.
• If you omit featured, Canopy falls back to a random manifest from the cached collection.
• The hero supports props like headline, description, links, variant, background, homeLabel, and height. Pass them via content/index.mdx (e.g., <Interstitials.Hero headline="Explore" />).
• Set variant="breadcrumb" to render a centered, copy-driven hero with a breadcrumb that mirrors the current docs path; override the leading crumb with homeLabel when needed.

<Interstitials.Hero  variant="breadcrumb"  headline="Plan your visit"  description="Preview your favorites, bookmark upcoming tours, and read the latest from the archives."  links={[{ title: 'Browse works', href: '/works' }]}/>

Custom content region

Everything beneath the hero comes from the Markdown body. Compose <Container /> wrappers, prose, or IIIF components (Viewer, Slider, ReferencedItems) to introduce the project. The docs layout wrapper provides typography defaults so you can focus on the content itself.

Highlighted metadata sliders

When showHighlighted is true, <RelatedItems /> rows render one slider per metadata label defined in canopy.yml. Each slider fetches a generated /api/facet/<label>/<value>.json collection and links cards back to the related work page.

Tips:

• Limit the metadata list to fields with a reasonable number of distinct values; each unique value generates its own IIIF Collection file.
• Use the top prop on <RelatedItems /> to restrict the number of sliders (top={2} renders two label buckets).
• Override slider spacing with the sliderOptions prop or by editing packages/app/ui/src/iiif/sliderOptions.js.

Checklist when editing the home page

• Add descriptive title and description front matter for accurate SEO and social cards.
• Keep hero copy short; the manifest label and summary already surface detailed provenance.
• Use <Button /> for primary actions and <Button variant="secondary" /> for tertiary links to maintain consistent styling.
• Wrap embedded sliders or viewers in <section> and heading pairs so the table of contents and skip links stay meaningful.

Layout components

Use layout primitives from @canopy-iiif/app/ui/server to keep spacing and call-to-action styling consistent across MDX pages.

Container

Wrap sections in a centered, padded shell that respects the project’s max width. Add utility classes via className to tweak backgrounds or spacing.

<Container> Textual content goes here. </Container>

Button

Render calls to action with the Canopy button styles. label provides the text while variant toggles between primary and secondary treatments.

<Button href="/about" label="Read more" target="_blank" variant="primary" />

ButtonWrapper

Arrange multiple buttons with a consistent gap. Useful for callouts with several actions.

<ButtonWrapper>  <Button href="/search" label="Browse" />  <Button href="/about" label="About" variant="secondary" /></ButtonWrapper>