From 056cf30f8195b10f5e69ad64563bab642b8ec952 Mon Sep 17 00:00:00 2001 From: Mark Baggett Date: Wed, 28 Jan 2026 08:45:04 -0600 Subject: [PATCH 1/2] Refine navPlace guide. (#229) --- .../enable-a-map-with-navPlace.mdx | 70 ++++++++++++++----- 1 file changed, 54 insertions(+), 16 deletions(-) diff --git a/content/docs/user-guides/enable-a-map-with-navPlace.mdx b/content/docs/user-guides/enable-a-map-with-navPlace.mdx index 4f86f1ba..1985590d 100644 --- a/content/docs/user-guides/enable-a-map-with-navPlace.mdx +++ b/content/docs/user-guides/enable-a-map-with-navPlace.mdx @@ -1,12 +1,21 @@ # Enable a map with navPlace -Use the `` component to plot every Manifest that exposes IIIF Presentation 3 navPlace `Point` features. This guide walks through the prerequisites and shows how to embed a map on any MDX page. +When working with IIIF Presentation 3 content, digital scholars may want to visualize where items in their collection +are located geographically. + +The `` component plots Manifests that expose navPlace Point features, allowing spatial relationships to be explored +interactively. + +This guide walks through the prerequisites and shows how to embed a map on any MDX page. > navPlace is an IIIF extension for geographic context. Make sure your manifests contain `navPlace.features` entries before running the build so Canopy can extract coordinates. ## 1. Add navPlace data to your manifests -Each manifest must include `navPlace` with GeoJSON-like `Feature` objects. Only features with `geometry.type === "Point"` are plotted. +To display items on a map, each IIIF Manifest must include geographic information describing where it is located or relevant. + +Canopy reads this information from the Manifest’s `navPlace` property, which contains GeoJSON-like `Feature` objects. +Only features with a `geometry.type` of `"Point"` are plotted on the map. ```json { @@ -36,7 +45,12 @@ Canopy collects these features, normalizes titles + thumbnails, and writes them ## 2. Embed a Map in MDX -Place `` on any MDX page (`content/**/*.mdx`) or in `content/works/_layout.mdx`. The component is SSR-safe: it renders a placeholder on the server and hydrates on the client with Leaflet + MarkerCluster. +Once your Manifests expose `navPlace` data, you can embed a map anywhere in your site to provide a geographic overview +of your collection. + +Place a `` component on any MDX page (`content/**/*.mdx`) or in `content/works/_layout.mdx`. The component is +server-side–rendering safe and renders a lightweight placeholder on the server and hydrates on the client using +Leaflet and MarkerCluster. ```mdx copy filename="content/about/maps.mdx" --- @@ -49,33 +63,52 @@ Our manifests encode navPlace metadata, so we can show a geographic overview: ``` -- `iiifContent` accepts a Manifest or Collection URL and determines which navPlace markers render. -- `height` controls the rendered canvas (string or number). Default: `600px`. +The `` component accepts the following props: + +* `iiifContent`: A IIIF Manifest or Collection URL. Canopy resolves the resource and renders markers for all available `navPlace` points. +* `height`: Controls the height of the rendered map canvas (string or number). Defaults to `600px`. + +> Note: The `iiifContent` resource must be a part of your Canopy site in order to be used with `Map`. External resources cannot be loaded. + ## 3. Add custom points with MapPoint -You can mix in arbitrary coordinates for items that lack navPlace or for non-IIIF references. When `iiifContent` is omitted, the map only displays your custom points. +In addition to rendering points from navPlace, you can add custom locations directly to a `` using ``. +This is useful for places that lack navPlace data or for locations that are not tied to IIIF resources. + +When `iiifContent` is omitted, the map renders only the custom points you provide. ```mdx copy filename="content/about/maps.mdx" - - - + + + + ``` -Each `MapPoint` supports: +Each `` represents a single geographic location and supports the following props: - `lat` / `lng` (required) — decimal degrees. - `title`, `summary`, `href`, `thumbnail`. - Child MDX content for longer descriptions (`…`). -Custom points leave their titles unlinked by default so the popup stays informational. Add `href` when you want the heading to navigate elsewhere. If you omit the `thumbnail` prop, the map reuses the first referenced manifest thumbnail so you still get a visual teaser. +By default, custom points render as informational markers with unlinked titles. Add an `href` when the point should +navigate the reader to another page or resource. If `thumbnail` is omitted, the map reuses the first available +referenced manifest thumbnail so the popup still includes a visual cue. + +### Linking custom points to works -When a point should drive the reader to one or more works, pass `referencedManifests` (or `manifest` / `manifests`) with the manifest IDs/URLs. Pair those values with the page’s `referencedManifests` front matter so Canopy already knows the local `/works/*.html` hrefs. +When a location should direct readers to one or more items in your collection, associate the point with IIIF Manifests +using `referencedManifests` (or the shorthand `manifest` / `manifests`). + +Pair these values with the page’s `referencedManifests` front matter so Canopy can resolve local `/works/*.html` links +automatically. ```mdx @@ -89,9 +122,9 @@ When a point should drive the reader to one or more works, pass `referencedManif ``` -## 4. Build or restart the dev server +## 4. Build and preview your map -Run your usual workflow so the navPlace dataset stays in sync: +Once your `navPlace` data and map markup are in place, run your normal development workflow to generate and preview the map: ```bash npm run dev # watches navPlace changes and rebuilds the dataset @@ -99,4 +132,9 @@ npm run dev # watches navPlace changes and rebuilds the dataset npm run build ``` -The viewer loads Leaflet + MarkerCluster automatically via `site/scripts/canopy-map.js`. Thumbnails, labels, and links in the popup come from each manifest’s cached metadata, so no extra authoring is required. +> If editing your Github files directly, simply edit and save. + +During the build, Canopy collects and normalizes all `navPlace` features and makes them available to the `` +component. The map viewer automatically loads Leaflet and MarkerCluster via `site/scripts/canopy-map.js`. + +Popups are populated from each Manifest’s cached metadata—including thumbnails, labels, and links. From 51cf549b8228e622814b83e1b37065968d115355 Mon Sep 17 00:00:00 2001 From: Mark Baggett Date: Wed, 28 Jan 2026 08:48:44 -0600 Subject: [PATCH 2/2] Add Creating a New Section Guide. --- .../user-guides/creating-a-new-section.mdx | 106 ++++++++++++++++++ content/docs/user-guides/index.mdx | 1 + 2 files changed, 107 insertions(+) create mode 100644 content/docs/user-guides/creating-a-new-section.mdx diff --git a/content/docs/user-guides/creating-a-new-section.mdx b/content/docs/user-guides/creating-a-new-section.mdx new file mode 100644 index 00000000..ec693aaf --- /dev/null +++ b/content/docs/user-guides/creating-a-new-section.mdx @@ -0,0 +1,106 @@ +--- +title: Create a New Section +description: Add a new top-level section to your Canopy site with its own pages and navigation. +--- + +# Create a New Section + +As your project grows, you may want to organize content into distinct sections beyond about. + +Canopy generates pages from the folder structure inside `content/`. Creating a new section is as simple as adding a +folder, populating it with MDX files, and registering it in your site navigation. + +This guide walks through creating a new "Essays" section from scratch. + +## 1. Create the section folder + +Inside the `content/` directory, create a new folder for your section. The folder name becomes the URL path: + +``` +content/ +├── essays/ ← new section +├── docs/ +├── about/ +└── index.mdx +``` + +A folder named `essays` will be accessible at `/essays` on your site. + +## 2. Add an index page + +Every section needs an `index.mdx` file. This becomes the landing page when visitors navigate to `/essays`: + +```mdx filename="content/essays/index.mdx" +--- +title: Essays +description: Long-form writing and analysis. +--- + +# Essays + +Explore our collection of essays on history, culture, and the archives. +``` + +At this point, visiting `/essays` displays your new landing page. + +## 3. Add a section layout + +Create a `_layout.mdx` file in your section folder. This wraps all pages in the section with consistent layout and +enables sidebar navigation: + +```mdx filename="content/essays/_layout.mdx" + + {props.children} + +``` + +## 4. Add pages to the section + +Create additional MDX files in the folder. Each file becomes a page within the section: + +``` +content/ +└── essays/ + ├── _layout.mdx + ├── index.mdx + ├── introduction.mdx + └── methodology.mdx +``` + +```mdx filename="content/essays/introduction.mdx" +--- +title: Introduction +description: An overview of our research approach. +--- + +# Introduction + +This essay introduces the themes and questions that guide our work... +``` + +These pages are now accessible at `/essays/introduction` and `/essays/methodology`. + +## 5. Add the section to navigation + +Open `content/navigation.yml` and add an entry for your new section. The `href` should match your folder name: + +```yaml filename="content/navigation.yml" +navigation: + - href: /search + label: Works + - href: /essays + label: Essays + - href: /docs + label: Docs + - href: /about + label: About +``` + +After rebuilding, "Essays" appears in your site header alongside the other navigation links. + +## Learn More + +See the [Layout documentation](/docs/content/layout) for all available layout props including sidebar customization +and table of contents options. + +The [Primary navigation](/docs/content/layout#primary-navigation) section explains how `navigation.yml` works in detail. diff --git a/content/docs/user-guides/index.mdx b/content/docs/user-guides/index.mdx index 39e0be3c..965781d0 100644 --- a/content/docs/user-guides/index.mdx +++ b/content/docs/user-guides/index.mdx @@ -10,3 +10,4 @@ Step-by-step guides for the most common Canopy tasks: - [Share and reuse content](./share-content) - [Use metadata collections](./use-metadata-collections) - [Creatie a Timeline](./create-a-timeline) +- [Create a New Section](./creating-a-new-section)