Skip to main content
Layouts are React components that wrap MDX content and provide consistent page structure — navigation, sidebars, footers, and metadata bars. Every content page specifies its layout in frontmatter.

​
How Layouts Work

A content file declares its layout in the YAML frontmatter: 
---
title: My Page
layout: learn
---

# My Page

Content here...
At render time, the build system reads the layout field, looks it up in apps/site/components/withLayout.tsx, and wraps the compiled MDX content in the corresponding layout component. The TypeScript pattern for a layout is: 
import type { FC, PropsWithChildren } from 'react';

const MyLayout: FC<PropsWithChildren> = ({ children }) => (
  <>
    <WithNavBar />
    <main id="main" tabIndex={-1}>
      {children}
    </main>
    <WithFooter />
  </>
);

export default MyLayout;

​
Available Layouts

All layout files live in apps/site/layouts/.
Used for pages in the About section. Provides:
  • Top navigation bar
  • Sidebar with about and getInvolved navigation keys
  • Meta bar (reading time, authors, edit link)
  • Breadcrumbs
  • Footer
// About.tsx
const AboutLayout: FC<PropsWithChildren> = ({ children }) => (
  <>
    <WithNavBar />
    <Article>
      <WithSidebar navKeys={['about', 'getInvolved']} />
      <div>
        <main id="main" tabIndex={-1}>{children}</main>
        <WithMetaBar />
      </div>
      <WithBreadcrumbs navKeys={['about', 'getInvolved']} />
    </Article>
    <WithFooter />
  </>
);
Standalone article pages. Provides:
  • Top navigation bar
  • Empty sidebar (no nav keys — no sidebar links shown)
  • Meta bar
  • Footer
Suitable for one-off content pages that don’t belong to a section’s sidebar.
The foundational layout that wraps all other layouts. Provides:
  • NavigationStateProvider React context
  • A baseLayout CSS class wrapper
This is applied at the app level, not declared in frontmatter.
Blog index and category listing pages. Provides:
  • Top navigation bar
  • Blog header with category label
  • Blog category tabs (All, Announcements, Release, Vulnerability, Migrations, Events)
  • Paginated post listing
  • Footer
This layout does not accept or render {children} from MDX content — the blog listing is fully data-driven.
Generic layout for pages that don’t fit a specific section. Provides:
  • Top navigation bar
  • Empty sidebar
  • Footer
No meta bar, no breadcrumbs.
Download section pages. Provides:
  • Top navigation bar
  • Page title from frontmatter
  • WithDownloadSection component pre-populated with live release data
  • MDX content rendered inside the download section
  • Footer
This is an async Server Component — it fetches release data at build time via provideReleaseData().
Download archive listing. Used for the historical releases archive page.
A visual layout used for landing/feature pages that require the glowing backdrop visual treatment.
Learn section articles. Provides:
  • Top navigation bar
  • Sidebar with the learn navigation key (full Learn section outline)
  • Sidebar cross-links (previous/next article navigation)
  • Meta bar
  • Breadcrumbs
  • Footer
// Learn.tsx
const LearnLayout: FC<PropsWithChildren> = ({ children }) => (
  <>
    <WithNavBar />
    <Article>
      <WithSideBar navKeys={['learn']} />
      <div>
        <main id="main" tabIndex={-1}>
          {children}
          <WithSidebarCrossLinks navKey="learn" />
        </main>
        <WithMetaBar />
      </div>
      <WithBreadcrumbs navKeys={['learn']} />
    </Article>
    <WithFooter />
  </>
);
Individual blog posts. Provides:
  • Top navigation bar
  • Post title (from frontmatter)
  • Author avatar group and names
  • Blog preview card
  • EOL alert (for vulnerability posts)
  • MDX content
  • Blog cross-links (previous/next post)
  • Meta bar
  • Footer

​
Creating a Custom Layout

1

Create the layout component

Add a new .tsx file in apps/site/layouts/. Follow the FC<PropsWithChildren> pattern:
import WithFooter from '#site/components/withFooter';
import WithNavBar from '#site/components/withNavBar';
import type { FC, PropsWithChildren } from 'react';

const MyCustomLayout: FC<PropsWithChildren> = ({ children }) => (
  <>
    <WithNavBar />
    <main id="main" tabIndex={-1}>
      {children}
    </main>
    <WithFooter />
  </>
);

export default MyCustomLayout;
2

Register the layout

Add the layout to the mapping in apps/site/components/withLayout.tsx.
3

Use in frontmatter

Reference the layout name in any content page’s frontmatter:
---
title: My Page
layout: my-custom
---
4

Document the layout

Add a note about the layout’s purpose and usage to the relevant documentation.
If you add a layout component to apps/site/layouts/ but forget to register it in withLayout.tsx, pages that reference it will fail to render.

Build docs developers (and LLMs) love

Get started for freeTalk to us