1# Docs Layout
2 
3Build documentation sites with sidebar navigation, table of contents, and surround links.
4 
5## When to use
6 
7- Technical documentation sites
8- Knowledge bases, help centers
9- Any content-heavy site with hierarchical navigation
10 
11> Requires `@nuxt/content` — see [conventions](../guidelines/conventions.md#content-module-integration) for setup (module order + `@source`).
12 
13## Component tree
14 
15```
16UApp
17├── UHeader
18├── UMain
19│   └── NuxtLayout (docs)
20│       └── UPage
21│           ├── #left → UPageAside → UContentNavigation
22│           └── NuxtPage
23│               ├── UPageHeader
24│               ├── UPageBody → ContentRenderer + UContentSurround
25│               └── #right → UContentToc
26└── UFooter
27```
28 
29## App shell
30 
31```vue [app.vue]
32<script setup lang="ts">
33import type { NavigationMenuItem } from '@nuxt/ui'
34 
35const route = useRoute()
36 
37const { data: navigation } = await useAsyncData('navigation', () => queryCollectionNavigation('docs'))
38 
39provide('navigation', navigation)
40 
41const items = computed<NavigationMenuItem[]>(() => [{
42  label: 'Docs',
43  to: '/docs/getting-started',
44  active: route.path.startsWith('/docs')
45}])
46</script>
47 
48<template>
49  <UApp>
50    <UHeader>
51      <template #title>
52        <Logo class="h-6 w-auto" />
53      </template>
54 
55      <UNavigationMenu :items="items" />
56 
57      <template #right>
58        <UContentSearchButton />
59        <UColorModeButton />
60      </template>
61    </UHeader>
62 
63    <UMain>
64      <NuxtLayout>
65        <NuxtPage />
66      </NuxtLayout>
67    </UMain>
68 
69    <UFooter />
70 
71    <UContentSearch :navigation="navigation" />
72  </UApp>
73</template>
74```
75 
76## Layout
77 
78```vue [layouts/docs.vue]
79<script setup lang="ts">
80import type { ContentNavigationItem } from '@nuxt/content'
81 
82const navigation = inject<Ref<ContentNavigationItem[]>>('navigation')
83</script>
84 
85<template>
86  <UPage>
87    <template #left>
88      <UPageAside>
89        <UContentNavigation :navigation="navigation" />
90      </UPageAside>
91    </template>
92 
93    <slot />
94  </UPage>
95</template>
96```
97 
98## Page
99 
100```vue [pages/docs/[...slug].vue]
101<script setup lang="ts">
102const route = useRoute()
103 
104definePageMeta({ layout: 'docs' })
105 
106const { data: page } = await useAsyncData(route.path, () => {
107  return queryCollection('docs').path(route.path).first()
108})
109 
110const { data: surround } = await useAsyncData(`${route.path}-surround`, () => {
111  return queryCollectionItemSurroundings('docs', route.path)
112})
113</script>
114 
115<template>
116  <UPage>
117    <UPageHeader :title="page.title" :description="page.description" />
118 
119    <UPageBody>
120      <ContentRenderer :value="page" />
121 
122      <USeparator />
123 
124      <UContentSurround :surround="surround" />
125    </UPageBody>
126 
127    <template #right>
128      <UContentToc :links="page.body.toc.links" />
129    </template>
130  </UPage>
131</template>
132```
133 
134### How nesting works
135 
136The outer `UPage` in the layout handles the **left sidebar**. The inner `UPage` in the page handles the **right sidebar**. They nest correctly — this is intentional.
137 
138### Common mistakes
139 
140- Not providing navigation via `provide`/`inject` — the layout needs it from the app shell.
141- Forgetting `UContentSearch` in app.vue — search won't work without it.
142- Using `UContentSearchButton` without `UContentSearch` — the button opens search, but the search component must exist.
143 
144## Key components
145 
146- `UPage` — multi-column grid with `#left`, `#default`, `#right` slots
147- `UPageAside` — sticky sidebar wrapper (visible from `lg` breakpoint)
148- `UContentNavigation` — sidebar navigation tree from Nuxt Content
149- `UContentToc` — table of contents from page headings
150- `UContentSurround` — prev/next links
151- `UContentSearch` / `UContentSearchButton` — search command palette
152- `UPageAnchors` — simpler alternative to full TOC
153