Layout Overrides

@pagesmith/docs ships with four built-in layouts: home, page, listing, and notFound. You can replace any of them with your own TSX components, or register entirely new layouts and assign them to specific sections through meta.json5.

The default docs chrome itself now lives behind @pagesmith/docs/components and @pagesmith/docs/layouts, so custom overrides can extend the built-in Pagesmith shell instead of copy-pasting the docs package internals.

Layout Resolution at a Glance

This diagram shows the two-step resolution process: the current route determines a layout name, then theme.layouts either maps that name to a custom TSX component or falls back to a built-in layout. Notice that section meta.json5 selects the layout name for section landing and item pages, while built-in names such as listing still follow the same resolution and fallback rules.

Built-in Layouts

When no overrides are configured, these layouts are used automatically. The page layout is still the default for ordinary section landing pages and individual pages.

Overriding via theme.layouts

To replace a built-in layout, add a theme.layouts mapping in pagesmith.config.json5. Each key is a layout name and each value is a file path (relative to the config file) pointing to a TSX component:

1{2  name: "My Docs",3  title: "My Docs",4  theme: {5    layouts: {6      // Replace the home page layout7      home: "./theme/layouts/MyHome.tsx",89      // Replace the standard page layout10      page: "./theme/layouts/MyPage.tsx",1112      // Replace the 404 layout13      notFound: "./theme/layouts/My404.tsx",14    },15  },16}

The override file is resolved relative to the directory containing pagesmith.config.json5. At build time, the file is bundled with Rolldown (supporting TypeScript and JSX) and its default export is used as the layout component.

Export Resolution

The docs system looks for the layout component in this order:

1. The default export
2. A named export matching a known alias:
   • home -> DocHome or Home
   • page -> DocPage or Page
   • listing -> DocListing or Listing
   • notFound -> DocNotFound or NotFound

For custom layout names (beyond the four built-in ones), the system looks for default or an export matching the layout name.

Layout Component Props

Every layout component receives the same base set of props, with the page layout receiving additional navigation-related props.

Base Props (all layouts)

Site Object

The site prop is built by getSitePayload(config, model) and contains:

Page Layout Additional Props

Layouts used for non-home pages (page, listing, and any custom item layouts) receive these additional props on top of the base set:

The home layout receives the base props plus listingCards / listingGroups / listingTotal when relevant; sidebar/prev/next/breadcrumb props are omitted because the home page has no surrounding section.

A SidebarSection has:

1type SidebarSection = {2  title: string;3  slug: string;4  collapsed?: boolean;5  items: SidebarItem[];6};78type SidebarItem = {9  title: string;10  path: string;11  children?: SidebarItem[];12};

Creating a Custom Layout

Custom layouts are TSX files that use @pagesmith/docs/jsx-runtime for server-side JSX rendering. Here is a minimal custom page layout that reuses the shared Pagesmith docs shell:

1import { h } from "@pagesmith/docs/jsx-runtime";2import { SiteDocument } from "@pagesmith/docs/components";3import { PageShell } from "@pagesmith/docs/layouts";45type Props = {6  content: string;7  frontmatter: Record<string, any>;8  headings: Array<{ depth: number; text: string; slug: string }>;9  slug: string;10  site: any;11  sidebarSections?: any[];12  prev?: { title: string; path: string };13  next?: { title: string; path: string };14};1516export default function MyPage(props: Props) {17  const { content, frontmatter, headings, slug, site, sidebarSections } = props;18  const title = frontmatter.title ? `${frontmatter.title} - ${site.title}` : site.title;1920  return (21    <SiteDocument title={title} site={site}>22      <PageShell23        site={site}24        currentPath={slug}25        headings={headings}26        sidebarSections={sidebarSections}27      >28        <div class="prose" innerHTML={content} />29      </PageShell>30    </SiteDocument>31  );32}

Key points:

• Import h from @pagesmith/docs/jsx-runtime for JSX support.
• Prefer @pagesmith/docs/components and @pagesmith/docs/layouts when you want the stock Pagesmith shell without copying the docs package internals.
• Use innerHTML={content} to render the processed markdown HTML. This is a special prop that sets the element’s inner HTML without escaping.
• Include data-pagefind-body="" on the content-only wrapper so Pagefind indexes the page body without header, sidebar, breadcrumb, or footer chrome. For article layouts, prefer the <article> element instead of a larger shell wrapper.
• Reference theme assets at ${site.basePath}/assets/style.css for the bundled theme CSS and ${site.basePath}/assets/main.js for the theme runtime, or import @pagesmith/site/css/chrome / @pagesmith/site/runtime/chrome directly in custom Vite entries when you are building around the shared site components.
• If search is enabled, include the Pagefind CSS and JS assets from ${site.basePath}/pagefind/.

Using meta.json5 for Per-Section Layouts

You can assign different layouts to different sections using the layout and itemLayout fields in a section’s meta.json5.

Section Landing Page Layout

The layout field controls which layout is used for the section’s README.md:

1// content/blog/meta.json52{3  displayName: "Blog",4  layout: "blogHome",5  itemLayout: "blogPost",6}

Item Layout

The itemLayout field controls which layout is used for all non-landing pages in the section.

In the example above, content/blog/README.md uses the blogHome layout, while all other pages like content/blog/my-post/README.md use the blogPost layout.

Both layout and itemLayout default to "page" when not specified.

Registering Additional Layouts

When you reference a layout name in meta.json5 that is not one of the built-in names, you must register it in theme.layouts:

1// pagesmith.config.json52{3  theme: {4    layouts: {5      blogHome: "./theme/layouts/BlogHome.tsx",6      blogPost: "./theme/layouts/BlogPost.tsx",7      changelog: "./theme/layouts/Changelog.tsx",8    },9  },10}

1// content/blog/meta.json52{3  displayName: "Blog",4  layout: "blogHome",5  itemLayout: "blogPost",6}

1// content/changelog/meta.json52{3  displayName: "Changelog",4  layout: "changelog",5  itemLayout: "changelog",6}

The docs system collects all unique layout names from section metas and resolves them at build time. If a layout name is referenced in a meta.json5 but not registered in theme.layouts, the build will fail with an error.

You do not need to register the built-in layout names (home, page, listing, notFound) unless you want to override them. They always have default implementations.

Layout Resolution Order

When rendering a page, the layout is chosen as follows:

1. Home page (content/README.md): always uses the home layout.
2. Section landing page (e.g. content/guide/README.md): uses layout from the section meta.json5, falling back to "page".
3. Item page (e.g. content/guide/getting-started/README.md): uses itemLayout from the section meta.json5, falling back to "page".

For each layout name, the system looks for:

1. A registered override in theme.layouts
2. The built-in default (only for home, page, listing, and notFound)

If a section meta or page frontmatter references a layout name that is neither built in nor registered in theme.layouts, the build throws.

Example: Custom Home Page

Replace the default landing page with a minimal custom design:

1// pagesmith.config.json52{3  theme: {4    layouts: {5      home: "./theme/MyHome.tsx",6    },7  },8}

1// theme/MyHome.tsx2import { h } from "@pagesmith/docs/jsx-runtime";34export default function MyHome({ content, frontmatter, site }: any) {5  return (6    <html lang={site.language || "en"}>7      <head>8        <meta charset="utf-8" />9        <meta name="viewport" content="width=device-width, initial-scale=1" />10        <title>{site.title}</title>11        <link rel="stylesheet" href={`${site.basePath}/assets/style.css`} />12      </head>13      <body>14        <main data-pagefind-body="">15          <h1>{frontmatter.title || site.name}</h1>16          <p>{frontmatter.description || site.description}</p>17          {frontmatter.actions?.map((action: any) => (18            <a href={action.link}>{action.text}</a>19          ))}20          {content ? <div class="prose" innerHTML={content} /> : null}21        </main>22      </body>23    </html>24  );25}

Example: Custom Article Layout

Create a specialized layout for blog-style content in a specific section:

1// pagesmith.config.json52{3  theme: {4    layouts: {5      article: "./theme/Article.tsx",6    },7  },8}

1// content/blog/meta.json52{3  displayName: "Blog",4  itemLayout: "article",5  orderBy: "publishedDate",6}

1// theme/Article.tsx2import { h } from "@pagesmith/docs/jsx-runtime";34export default function Article({ content, frontmatter, site, prev, next }: any) {5  const title = frontmatter.title ? `${frontmatter.title} - ${site.title}` : site.title;67  return (8    <html lang={site.language || "en"}>9      <head>10        <meta charset="utf-8" />11        <meta name="viewport" content="width=device-width, initial-scale=1" />12        <title>{title}</title>13        <link rel="stylesheet" href={`${site.basePath}/assets/style.css`} />14      </head>15      <body>16        <header>17          <a href={`${site.basePath}/`}>{site.name}</a>18        </header>19        <article data-pagefind-body="">20          <h1>{frontmatter.title}</h1>21          {frontmatter.publishedDate ? <time>{frontmatter.publishedDate}</time> : null}22          {frontmatter.description ? <p class="lead">{frontmatter.description}</p> : null}23          <div class="prose" innerHTML={content} />24        </article>25        <nav>26          {prev ? <a href={prev.path}>Previous: {prev.title}</a> : null}27          {next ? <a href={next.path}>Next: {next.title}</a> : null}28        </nav>29      </body>30    </html>31  );32}

This layout renders blog-style pages with a published date, description lead, and prev/next navigation, while the section landing page continues to use the default page layout.