Customize the search index

Search is powered by FlexSearch and configured entirely through canopy.yml plus optional front matter on MDX pages. This guide walks through indexing additional metadata, enabling summaries, adding annotation text, and splitting results into custom tabs.

Prereq: Start with a working Canopy project and at least one IIIF collection configured.

1. Extend canopy.yml

Add a search block (or edit the existing one) to enable metadata and summary indexing, plus custom layouts for each record type.

search:  results:    work:      layout: grid      result: figure    page:      layout: list      result: article    docs:      layout: list      result: article  tabs:    order:      - work      - docs      - page  index:    metadata:      enabled: true      all: false    summary:      enabled: true    annotations:      enabled: true      motivation:        - commenting        - tagging

Key ideas:

• results.<type> controls layout/markup per record type. Add entries for new types you introduce via front matter (for example, docs).
• tabs.order establishes the tab order in the runtime. Types not listed fall back to the order in results.
• index.metadata.all controls whether every metadata entry from each manifest is indexed. When it is false, Canopy only indexes the labels listed in the top-level metadata array of canopy.yml.
• index.summary.enabled toggles whether manifest/page summaries become searchable text.
• index.annotations.enabled writes a third artifact (search-index-annotations.json) that stores annotation bodies. Set motivation to the list you care about.

2. Tag MDX pages for search

Front matter controls which MDX pages enter the search index and how they appear in results.

---title: Publishing workflowsearchType: docssearchSummary: Step-by-step deployment guide.referencedManifests:  - https://api.dc.library.northwestern.edu/api/v2/works/a5d3b7f3-d0fc-4d6d-9417-ef9184fa9273?as=iiif--- # Publishing workflow ...

Fields:

• search: false — opt out entirely.
• searchType — overrides the default page type. Match this with an entry under search.results to give the type its own tab/layout.
• searchSummary / searchSummaryMarkdown — concise teaser shown in list layouts.

3. Verify the generated artifacts

Run npm run build (or restart npm run dev) and inspect the files under site/api/:

• search-index.json — compact payload used to populate FlexSearch. Inspect it to confirm metadata labels and summaries are present.
• search-records.json — rich records referenced when rendering the UI.
• search-index-annotations.json — only written when annotations.enabled is true.

If annotation indexing is enabled, the browser runtime fetches the annotations file on demand and merges it into the FlexSearch source before running queries.

4. Custom result templates

Set result: figure or result: article per type (see search.results above). Then override the corresponding MDX partial under content/search/ to adjust the markup:

• _result-figure.mdx
• _result-article.mdx

Both receive record, query, and runtime helpers so you can render badges, metadata, or excerpts. If these files are missing, Canopy falls back to its defaults.

5. Troubleshooting

• Missing metadata values in the index — ensure the exact label appears in canopy.yml → metadata (for facet generation and selective metadata indexing). Set search.index.metadata.all: true to include every metadata entry regardless of the list.
• Tabs in the wrong order — confirm every type is listed in tabs.order. Anything omitted falls back to the declaration order under results.
• MDX page not indexed — remove search: false (if present) and make sure the file is not in a content/search/ directory (that folder is reserved for templates).