Site UI Configuration

Configure ArdoRoot, header, footer, edit links, last-updated metadata, and context sidebars from root.tsx.

Build-time options belong in ardo() config. Site chrome belongs in React. Configure the header, sidebar, footer, edit links, last-updated metadata, and multi-section sidebars in your app's root.tsx with <ArdoRoot>.

Minimal Root

Every Ardo app needs the generated config and sidebar data. Import them from virtual modules and pass them to ArdoRoot.

import { ArdoRoot, ArdoRootLayout } from "ardo/ui"
import config from "virtual:ardo/config"
import sidebar from "virtual:ardo/sidebar"
import "ardo/ui/styles.css"

export function Layout({ children }: { children: React.ReactNode }) {
  return <ArdoRootLayout>{children}</ArdoRootLayout>
}

export default function Root() {
  return <ArdoRoot config={config} sidebar={sidebar} />
}

ArdoRootLayout owns the document-level theme bootstrap and global shell setup. ArdoRoot owns the React Router outlet, Ardo providers, default header, sidebar, and footer.

ArdoRoot Props

Prop	Type	Purpose
`config`	`ArdoConfig`	Generated site config from `virtual:ardo/config`.
`sidebar`	`SidebarItem[] \| Record<string, SidebarItem[]>`	Generated sidebar data from `virtual:ardo/sidebar` or `virtual:ardo/sidebars`.
`contexts`	`ArdoContextItem[]`	Optional rail items for switching between multiple sidebar contexts.
`header`	`ReactNode`	Replace the entire default header.
`sidebarContent`	`ReactNode`	Replace the generated sidebar content.
`footer`	`ReactNode`	Replace the default footer element.
`headerProps`	`ArdoHeaderProps`	Configure the default header. Ignored when `header` is provided.
`sidebarProps`	`ArdoSidebarProps`	Configure the default sidebar. Ignored when `sidebarContent` is provided.
`footerProps`	`ArdoFooterProps`	Configure the default footer. Ignored when `footer` is provided.
`editLink`	`{ pattern: string; text?: string }`	Site-wide edit-link pattern for Markdown pages.
`lastUpdated`	`{ enabled?: boolean; text?: string; formatOptions?: Intl.DateTimeFormatOptions }`	Site-wide last-updated display settings.
`tocLabel`	`string`	Label for the generated table-of-contents panel.
`className`	`string`	Replace the default layout class.
`children`	`ReactNode`	Replace the default React Router `<Outlet />` content.

Use headerProps when you want the default responsive header but need to configure the logo, navigation, search, theme toggle, or action area.

import { ArdoNav, ArdoNavLink, ArdoSocialLink } from "ardo/ui"
import logo from "./assets/logo.svg"

export default function Root() {
  return (
    <ArdoRoot
      config={config}
      sidebar={sidebar}
      headerProps={{
        logo,
        title: "My Docs",
        searchPlaceholder: "Search documentation...",
        nav: (
          <ArdoNav>
            <ArdoNavLink to="/guide/getting-started">Guide</ArdoNavLink>
            <ArdoNavLink to="/api-reference">API</ArdoNavLink>
          </ArdoNav>
        ),
        actions: <ArdoSocialLink href="https://github.com/example/project" icon="github" />,
      }}
    />
  )
}

Header prop	Purpose
`logo`	String URL or `{ light, dark }` logo variants.
`title`	Header title. Defaults to `config.title`.
`nav`	Desktop navigation content, usually `ArdoNav` and `ArdoNavLink`.
`actions`	Right-side actions such as `ArdoSocialLink` or custom buttons.
`search`	Set to `false` to hide search. Defaults to `true`.
`searchPlaceholder`	Placeholder for the search input.
`themeToggle`	Set to `false` to hide the theme toggle. Defaults to `true`.
`mobileMenuContent`	Additional content for the mobile menu. `ArdoRoot` supplies the sidebar.
`className`	Replace the default header class.

Pass header instead of headerProps when your design needs a fully custom header element.

For light customization, pass footerProps. For the common "default footer with sponsor and copyright" case, pass an explicit footer element.

import { ArdoFooter } from "ardo/ui"

export default function Root() {
  return (
    <ArdoRoot
      config={config}
      sidebar={sidebar}
      footer={
        <ArdoFooter
          sponsor={{ text: "Example Co", link: "https://example.com" }}
          message="Released under the MIT License."
          copyright="Copyright 2026 Example Co"
        />
      }
    />
  )
}

Footer prop	Purpose
`message`	React content rendered as footer message text.
`copyright`	React content rendered as copyright text.
`trustedMessageHtml`	Trusted HTML for the message line. Do not pass user-provided content.
`trustedCopyrightHtml`	Trusted HTML for the copyright line. Do not pass user-provided content.
`project`	Project metadata override for the linked package/version line.
`sponsor`	Sponsor link rendered as "Sponsored by ...".
`buildTime`	Build timestamp override. Defaults to generated config metadata.
`buildHash`	Git hash override. Defaults to generated config metadata.
`ardoLink`	Set to `false` to hide the "Built with Ardo" link.
`children`	Full custom footer content. Skips automatic footer rendering.
`className`	Replace the default footer class.

Edit Links and Last Updated

editLink and lastUpdated are site-wide content settings. Ardo applies them to Markdown and MDX document pages, and page frontmatter can opt out with editLink: false or lastUpdated: false.

<ArdoRoot
  config={config}
  sidebar={sidebar}
  editLink={{
    pattern: "https://github.com/example/project/edit/main/docs/app/routes/:path",
    text: "Edit this page on GitHub",
  }}
  lastUpdated={{
    enabled: true,
    text: "Last updated",
    formatOptions: { dateStyle: "medium" },
  }}
  tocLabel="On this page"
/>

The :path placeholder receives the route file path relative to the generated Markdown route root.

Context Sidebars

Use virtual:ardo/sidebars and contexts when your docs have distinct areas, such as guide pages and generated API reference pages. The sidebar rail becomes a context switcher, and ArdoRoot selects the active sidebar map entry by context id.

import { ArdoRoot } from "ardo/ui"
import config from "virtual:ardo/config"
import sidebars from "virtual:ardo/sidebars"

export default function Root() {
  return (
    <ArdoRoot
      config={config}
      sidebar={sidebars}
      contexts={[
        { id: "guide", label: "Guide", href: "/guide/getting-started" },
        { id: "api-reference", label: "API", href: "/api-reference" },
      ]}
    />
  )
}

Each context item has:

Field	Purpose
`id`	Sidebar map key. Conventionally the top-level route folder, such as `guide` or `api`.
`label`	Text shown in the sidebar rail tooltip.
`href`	Landing link for the context. Also used to infer the default active route prefix.
`match`	Optional string prefix or `RegExp` when `href` is not enough to match the context's routes.

Use virtual:ardo/sidebar for a single global sidebar. Use virtual:ardo/sidebars only when you want context-aware navigation.

Minimal Root

ArdoRoot Props

Header

Footer

Edit Links and Last Updated

Context Sidebars