Custom layouts

<Layout /> gives you a full doc shell, but some sections deserve custom framing. When you need to steer the markup yourself, import the primitives below inside _layout.mdx and arrange them however you like.

Navigation components

Import these helpers directly in the layout (or wire them globally through app/components/mdx.tsx):

• <SubNavigation /> reads the current directory, page context, and content/navigation.yml to build a sidebar tree. Override the defaults with navigation, heading, or ariaLabel when you need a custom label or data source.
• <ContentNavigation /> prints an on-page table of contents. With no props it derives headings from the current page. Pass items, heading, or headingId to take over the outline, and add collapsible if you want the built-in expand/collapse control. Leave it off for a static list.
• <ContentNavigationScript /> handles sticky positioning, collapse state, and active-heading tracking. Include it once per layout (usually right after the nav markup). The script tags parent wrappers and injects any helper nodes it needs, so the HTML stays lean.

ContentNavigationScript runs once and keeps the navigation sticky, so the markup above is all you need. <ContentNavigation /> hydrates from the heading metadata captured during the MDX build; if the page has ## headings (or deeper) it will mirror the default <Layout />. When a page is short—or you need to curate the outline—pass your own items array.

Remember to render <ContentNavigationScript /> anywhere the TOC appears so the floating behavior works without hydrating React.

Example _layout.mdx

import {  SubNavigation,  ContentNavigation,  ContentNavigationScript,} from "@canopy-iiif/app/ui/server"; <style>  {`    .custom-layout-example {        display: grid;        grid-template-columns: minmax(16rem, 20rem) minmax(0, 1fr);        gap: 2rem;        align-items: flex-start;        padding: 2rem;    }     .custom-layout-example__sidebar {        display: flex;        flex-direction: column;        gap: 1.25rem;    }     .custom-layout-example__sidebar nav {      padding: 1rem;      background: var(--color-accent-100);      border: 1px solid var(--color-accent-200);    }     .custom-layout-example__content {        min-width: 0;    }`}</style> <div className="custom-layout-example">  <aside className="custom-layout-example__sidebar">    <SubNavigation />    <ContentNavigation />  </aside>  <div className="custom-layout-example__content">{props.children}</div></div> <ContentNavigationScript />