🎉 See live examples of Canopy IIIF →

Create Navigation Routes

Implementers of Canopy IIIF may want to create routes in their content/ directory to fit their contextual content. This guide will walk you through the process of creating a new directory and adding its pages to navigation menus.

💡

This guide assumes you have a Canopy IIIF project. See the Create a Project guide to get started.

Use Case

As a digital scholarship librarian, you have compiled a series of essays analyzing manuscripts in a IIIF Collection provided by your institution and want to create the new directory essays to deliver this scholarly content.

Implementation

Create a New Content Route

  • Create a new directory in the content/ called essays.
  • Add a new file index.mdx within it. This will act as the landing page for the new directory and be delivered at the route /essays/.
  • Add a new file three-pillars-of-islam.mdx within it. This will be a page within the new directory at the route /essays/three-pillars-of-islam/.
      • index.mdx
      • three-pillars-of-islam.mdx
    • 💡

    The content in this directory is NOT yet accessible. We also need to add the route in /src/pages/essays to make it viewable. The routes will resolve after completion of steps 1-3.

    Reflect the Route in src/pages/

    • Copy the src/pages/about directory recursively and rename it to src/pages/essays. The essays directory will now contain the files index.tsx and [slug].tsx.
    cp -r src/pages/about src/pages/essays

    The src/pages/essays directory will now contain the files index.tsx and [slug].tsx.

        • [slug].tsx
        • index.tsx

    • Reference the /content Directory

    • Open /src/pages/essays/[slug].tsx and change the CONTENT_DIRECTORY variable to essays.
    • Save the file.

    This file will render content at routes content/essays/*, for example /essays/the-three-pillars-of-islam.

    The [slug].tsx file follows a Next.js dynamic route (opens in a new tab) convention.

    /src/pages/essays/[slug].tsx
    - const CONTENT_DIRECTORY = "about";
+ const CONTENT_DIRECTORY = "essays";
    • Open /src/pages/essays/index.tsx and change the CONTENT_DIRECTORY variable to essays.
    • Save the file.

    This file will render the single page content at the route content/essays.

    /src/pages/essays/index.tsx
    - const CONTENT_DIRECTORY = "about";
+ const CONTENT_DIRECTORY = "essays";

    Edit the Primary Navigation

    To add the new route to the primary navigation in the header, we need to add the route to the _meta.json file in the content/ directory.

    • Open content/_meta.json and add the Essays route code to the array.
    • Save the file.
    {
  "path": "/essays",
  "title": "Essays"
}

    Your content/_meta.json file should look like this:

    content/_meta.json
    [
  {
    "path": "/works",
    "title": "Works"
  },
  {
    "path": "/metadata",
    "title": "Metadata"
  },
  {
    "path": "/essays",
    "title": "Essays"
  },
  {
    "path": "/about",
    "title": "About"
  }
]

    Create the Secondary Navigation

    Finally, we want to add the secondary navigation for the Essays directory. This will render in the sidebar of our Essays content.

    • Create the new file _meta.json in the content/essays/ directory that was created earlier.
    • Add the Essays
    • Save the file.
    content/essays/_meta.json
    [
  {
    "path": "/essays",
    "title": "Essays"
  },
  {
    "path": "/essays/three-pillars-of-islam",
    "title": "Three Pillars"
  }
]

    Your file structure should have _meta.json at both content/_meta.json and content/essays/_meta.json.

    • _meta.json
      • _meta.json
      • index.mdx
      • three-pillars-of-islam.mdx

    • Edit Content and Reference Navigation

    In each of the files we created, we need to add an essays value to navigation key and in our frontmatter. This will instruct the page to render the secondary navigation in the sidebar.

    • Open content/essays/index.mdx and add the content below. This will be the landing page for the Essays directory.
    • Save the file.
    content/essays/index.mdx
    ---
title: Essays
navigation: "essays"
---
 
# Essays
 
This is the landing page for the Essays directory.
 
## Introduction
 
This is the introduction to the Essays section.
    • Open content/essays/three-pillars-of-islam.mdx and add the content below. This will be the page for the essay Three Pillars of Islam.
    • Save the file.
    content/essays/three-pillars-of-islam.mdx
    ---
title: Three Pillars of Islam
navigation: "essays"
---
 
# Three Pillars of Islam
 
This is the essay `Three Pillars of Islam`.

    Validate the New Routes

    Once completed, you will be able to navigate to the new routes.

    • From the home page, note the Essays navigation item in the primary navigation of the header.
    • Follow the Essays navigation item to the landing page /essays/ for the Essays directory.
    • Note the secondary navigation in the sidebar with the items: Essays and the Three Pillars of Islam.
    • Follow the Three Pillars of Islam link to your content page /essays/three-pillars-of-islam/.
    Create Markdown ContentCustomize the Search Index