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.

Front matter reference

Use YAML blocks to control metadata, canonical links, referenced manifests, and search behavior. The Frontmatter guide lists every supported key plus examples for the home page toggles.

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. Compose Markdown and drop components wherever you need them—most sites lead with <Interstitials.Hero />, then follow up with <Container> sections, sliders, or bespoke CTAs.

---title: Amanda Ira Aldridge Correspondence--- <Interstitials.Hero  headline="Plan your visit"  description="Preview your favorites, bookmark upcoming tours, and read the latest from the archives."  links={[{ title: 'Browse works', href: '/works' }]}/> <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

<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, <RelatedItems />, 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.

<RelatedItems top={3} /> renders 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>