Skip to content

Theme, layouts, and navigation

The default theme is a responsive documentation shell rather than a closed template. It supplies navigation, sidebars, page outlines, local search, appearance controls, code copying, pagination, home heroes, and a complete 404 page. Start with configuration; extend React only when a product requirement cannot be expressed there.

Layouts

Choose a content layout in frontmatter:

md
---
layout: doc
---
  • doc is the default. It applies reading typography, the heading outline, and previous/next links derived from the sidebar.
  • home renders the locale-resolved configured hero and optional feature row before page MDX in a full-width shell.
  • page keeps navigation and a neutral article container without documentation paging.

Home hero artwork can provide separate light and dark assets while keeping one accessible description:

ts
themeConfig: {
  home: {
    hero: {
      image: {
        src: '/workflow-light.jpg',
        darkSrc: '/workflow-dark.jpg',
        alt: 'Documentation workflow',
      },
    },
  },
}
ts
themeConfig: {
  logo: { src: '/logo.svg', alt: 'Product docs' },
  nav: [
    { text: 'Guide', link: '/guide/' },
    { text: 'GitHub', link: 'https://github.com/example/project' },
  ],
  sidebar: [
    {
      text: 'Getting started',
      items: [{ text: 'Quick start', link: '/guide/' }],
    },
  ],
}

Internal theme links are resolved under base. HTTP(S) nav links use ordinary browser navigation in the current context. Nav items pass only href; they do not automatically add a new context or relationship attributes. MDX-authored links can explicitly set target="_blank" and rel="noopener noreferrer" when a new context is genuinely useful. Below 960px the persistent sidebar becomes a labelled modal sheet with collapsible groups. At desktop widths, every group remains visible as a semantic section beside the document, and the current page uses the primary theme treatment.

Local search is enabled unless themeConfig.search is false. It loads on demand, opens from the search button or Control+K / Command+K, supports keyboard selection, and restores focus when dismissed. Search v2 records page language so results from the active locale are ranked and grouped correctly.

Locales

Locale entries define a BCP 47 lang, label, and route root; they may override nav, sidebar, home, and UI messages. Mirrored routes let the language switch preserve the current page. The longest matching configured locale root controls document and search language. Frontmatter lang does not override the resolved route locale; content requiring another language should live under the corresponding locale root.

Customize visual values with theme tokens or compose React behavior through theme extensions.