From c8c2f66c05e2ee3e27b991db87f69818d131b292 Mon Sep 17 00:00:00 2001
From: =?UTF-8?q?S=C3=A9bastien=20Chopin?= <atinux@gmail.com>
Date: Wed, 2 Sep 2026 17:17:59 +0200
Subject: [PATCH 1/2] feat: add support for page layout within navigation

---
 app/app.vue                                   | 24 +++++++-
 app/components/docs/DocsAsideMobileBar.vue    |  5 +-
 .../layouts/LayoutsDocs.vue}                  |  0
 app/components/layouts/LayoutsPage.vue        |  7 +++
 app/pages/[...slug].vue                       |  3 +-
 app/utils/navigation.ts                       | 29 +++++++++
 playground/app/app.config.ts                  |  1 +
 playground/content/2.writing/5.navigation.md  | 11 ++++
 playground/content/page.md                    | 23 ++++++++
 playground/content/pages/.navigation.yml      |  1 +
 playground/content/pages/test.md              | 21 +++++++
 test/navigation.test.ts                       | 59 ++++++++++++++++++-
 12 files changed, 178 insertions(+), 6 deletions(-)
 rename app/{layouts/docs.vue => components/layouts/LayoutsDocs.vue} (100%)
 create mode 100644 app/components/layouts/LayoutsPage.vue
 create mode 100644 playground/content/page.md
 create mode 100644 playground/content/pages/.navigation.yml
 create mode 100644 playground/content/pages/test.md

diff --git a/app/app.vue b/app/app.vue
index 62ef764..a508c15 100644
--- a/app/app.vue
+++ b/app/app.vue
@@ -1,10 +1,12 @@
 <script setup lang="ts">
 import type { NavigationItem } from 'comark-content'
 import type { SearchSection } from './utils/search-sections'
+import { useRoute } from 'vue-router'
 
 const { seo, docs } = useAppConfig()
 
 const content = useDocsContent()
+const route = useRoute()
 
 const { data: navigation } = await useAsyncData('navigation', () => content.value.client.navigation(), {
   watch: [() => content.value.base],
@@ -21,7 +23,14 @@ const {
 
 onNuxtReady(() => loadSearchSections())
 
+const nuxtApp = useNuxtApp()
 const navTree = computed<NavigationItem[]>(() => prefixNavigation(navigation.value ?? [], content.value.base))
+const navigationLayout = ref(findNavigationLayout(navTree.value, route.path))
+onNuxtReady(() => {
+  nuxtApp.hook('page:finish', () => {
+    navigationLayout.value = findNavigationLayout(navTree.value, route.path)
+  })
+})
 const searchFiles = computed<SearchSection[]>(() =>
   (files.value ?? []).map((section) => {
     const [path, hash] = section.id.split('#')
@@ -52,6 +61,7 @@ useSeoMeta({
 })
 
 provide('navigation', navTree)
+provide('layout', navigationLayout)
 
 // const colorMode = useColorMode()
 const historyOpen = useVersionHistory()
@@ -82,9 +92,17 @@ defineShortcuts({
     <AppHeader />
 
     <UMain>
-      <NuxtLayout>
-        <NuxtPage />
-      </NuxtLayout>
+      <Suspense>
+        <LayoutsPage v-if="navigationLayout === 'page'">
+          <NuxtPage />
+        </LayoutsPage>
+        <LayoutsDocs v-else-if="navigationLayout === 'docs'">
+          <NuxtPage />
+        </LayoutsDocs>
+        <UContainer v-else>
+          <NuxtPage />
+        </UContainer>
+      </Suspense>
     </UMain>
 
     <AppFooter />
diff --git a/app/components/docs/DocsAsideMobileBar.vue b/app/components/docs/DocsAsideMobileBar.vue
index b591c2a..b43fb55 100644
--- a/app/components/docs/DocsAsideMobileBar.vue
+++ b/app/components/docs/DocsAsideMobileBar.vue
@@ -14,6 +14,7 @@ const menuDrawerOpen = ref(false)
 const tocDrawerOpen = ref(false)
 const navigationRef = ref<HTMLElement | null>(null)
 let observer: IntersectionObserver | undefined
+const layout = inject('layout')
 
 watch(menuDrawerOpen, (open) => {
   nextTick(() => {
@@ -28,9 +29,11 @@ watch(menuDrawerOpen, (open) => {
 
 <template>
   <div
-    class="lg:hidden sticky top-(--ui-header-height) z-10 bg-default -mx-6 p-2 px-6 border-b border-muted flex justify-between"
+    class="lg:hidden sticky top-(--ui-header-height) z-10 bg-default -mx-6 p-2 px-6 border-b border-muted flex h-13"
+    :class="layout === 'page' ? 'justify-end' : 'justify-between'"
   >
     <UDrawer
+      v-if="layout === 'docs'"
       v-model:open="menuDrawerOpen"
       direction="left"
       :title="title"
diff --git a/app/layouts/docs.vue b/app/components/layouts/LayoutsDocs.vue
similarity index 100%
rename from app/layouts/docs.vue
rename to app/components/layouts/LayoutsDocs.vue
diff --git a/app/components/layouts/LayoutsPage.vue b/app/components/layouts/LayoutsPage.vue
new file mode 100644
index 0000000..caa8415
--- /dev/null
+++ b/app/components/layouts/LayoutsPage.vue
@@ -0,0 +1,7 @@
+<template>
+  <UContainer class="max-w-7xl">
+    <UTheme :ui="{ pageHeader: { container: 'lg:pt-8' }, contentToc: { container: 'lg:pt-16' } }">
+      <slot />
+    </UTheme>
+  </UContainer>
+</template>
diff --git a/app/pages/[...slug].vue b/app/pages/[...slug].vue
index b482a3e..602433c 100644
--- a/app/pages/[...slug].vue
+++ b/app/pages/[...slug].vue
@@ -6,13 +6,13 @@ import CodeExplorer from '../components/CodeExplorer.vue'
 import Browser from '../components/Browser.vue'
 
 definePageMeta({
-  layout: 'docs',
   path: '/:slug(.+)',
 })
 
 const { toc, seo } = useAppConfig()
 const navigation = inject<Ref<NavigationItem[]>>('navigation')
 const content = useDocsContent()
+const layout = inject('layout')
 
 const { data: page } = await useAsyncData(`${content.value.base}:${content.value.path}`, () =>
   content.value.client.get(content.value.path)
@@ -126,6 +126,7 @@ if (content.value.mode === 'prod') {
       />
 
       <UContentSurround
+        v-if="layout === 'docs'"
         :surround="surroundLinks as any"
         :ui="{ root: !surroundLinks[0] ? 'sm:grid-cols-1' : 'sm:grid-cols-2' }"
       />
diff --git a/app/utils/navigation.ts b/app/utils/navigation.ts
index 7cd86d6..46a7589 100644
--- a/app/utils/navigation.ts
+++ b/app/utils/navigation.ts
@@ -64,6 +64,35 @@ export interface BreadcrumbItem {
   path?: string
 }
 
+export type NavigationLayout = 'docs' | 'page'
+
+/** Layout declared by the nearest matching page or directory navigation node. */
+export function findNavigationLayout(
+  navigation: NavigationItem[] | undefined | null,
+  path: string | undefined
+): NavigationLayout | undefined {
+  if (!navigation?.length || !path || path === '/') return undefined
+
+  let layout: NavigationLayout | undefined
+  const visit = (items: NavigationItem[]) => {
+    for (const item of items) {
+      const isPage = item.path === path
+      const isDirectory = Boolean(
+        item.children?.length
+        && item.path !== '/'
+        && path.startsWith(`${item.path}/`)
+      )
+      if (!isPage && !isDirectory) continue
+
+      if (item.layout === 'docs' || item.layout === 'page') layout = item.layout
+      if (item.children?.length) visit(item.children)
+    }
+  }
+
+  visit(navigation)
+  return layout || 'docs'
+}
+
 /** Trail of navigation items leading to `path`, including the page itself. */
 export function findBreadcrumb(
   navigation: NavigationItem[] | undefined | null,
diff --git a/playground/app/app.config.ts b/playground/app/app.config.ts
index d640ae4..e3915be 100644
--- a/playground/app/app.config.ts
+++ b/playground/app/app.config.ts
@@ -12,6 +12,7 @@ export default defineAppConfig({
     ecosystem: [{ mark: 'comark-content', to: 'https://content.comark.dev', label: 'Comark Content' }],
     nav: [
       { label: 'Documentation', sections: ['getting-started', 'writing', 'concepts', 'deployment'] },
+      { label: 'Page', to: '/page' }
     ],
   },
   footer: {
diff --git a/playground/content/2.writing/5.navigation.md b/playground/content/2.writing/5.navigation.md
index fbfe0af..977b15d 100644
--- a/playground/content/2.writing/5.navigation.md
+++ b/playground/content/2.writing/5.navigation.md
@@ -26,6 +26,17 @@ title: Getting Started
 
 Page titles come from frontmatter — `navigation.title` when set, `title` otherwise. Pages with `navigation: false` are excluded from the tree entirely (and therefore from prev/next links, search, and `llms.txt`).
 
+## Section layouts
+
+Pages use the `docs` layout by default, which includes the navigation sidebar. Set `layout: page` in a directory's `.navigation.yml` to render every page in that directory without the sidebar:
+
+```yaml [content/3.examples/.navigation.yml]
+title: Examples
+layout: page
+```
+
+The layout applies to nested directories too. A nested `.navigation.yml` can set `layout: docs` to restore the sidebar. The `page` layout keeps the header, footer and page table of contents.
+
 ## Header tabs
 
 The header renders one tab per group in `header.nav` from `app.config.ts`. Each group maps top-level content sections to a tab:
diff --git a/playground/content/page.md b/playground/content/page.md
new file mode 100644
index 0000000..7db5d18
--- /dev/null
+++ b/playground/content/page.md
@@ -0,0 +1,23 @@
+---
+title: Page
+description: This is an example using the page layout.
+navigation:
+  layout: page
+---
+
+In order to use the `page` layout without the left aside.
+
+## Usage
+
+You only need to set:
+
+```yaml
+---
+navigation:
+  layout: page
+---
+```
+
+## TOC
+
+The Table of Contents stays if you have headings.
diff --git a/playground/content/pages/.navigation.yml b/playground/content/pages/.navigation.yml
new file mode 100644
index 0000000..85fdf6f
--- /dev/null
+++ b/playground/content/pages/.navigation.yml
@@ -0,0 +1 @@
+layout: page
diff --git a/playground/content/pages/test.md b/playground/content/pages/test.md
new file mode 100644
index 0000000..4dee36e
--- /dev/null
+++ b/playground/content/pages/test.md
@@ -0,0 +1,21 @@
+---
+title: Test
+description: This is an example using the page layout.
+---
+
+In order to use the `page` layout without the left aside.
+
+## Usage
+
+You only need to set:
+
+```yaml
+---
+navigation:
+  layout: page
+---
+```
+
+## TOC
+
+The Table of Contents stays if you have headings.
diff --git a/test/navigation.test.ts b/test/navigation.test.ts
index 54904b4..65db153 100644
--- a/test/navigation.test.ts
+++ b/test/navigation.test.ts
@@ -1,5 +1,5 @@
 import { describe, expect, it } from 'vitest'
-import { findBreadcrumb, findPageHeadline, findSurroundLinks } from '../app/utils/navigation'
+import { findBreadcrumb, findNavigationLayout, findPageHeadline, findSurroundLinks } from '../app/utils/navigation'
 import type { NavigationItem } from 'comark-content'
 
 const nav = [
@@ -76,6 +76,63 @@ describe('findBreadcrumb', () => {
   })
 })
 
+describe('findNavigationLayout', () => {
+  const navigation = [
+    {
+      title: 'Examples',
+      path: '/examples',
+      page: false,
+      layout: 'page',
+      children: [
+        { title: 'Overview', path: '/examples/overview' },
+        {
+          title: 'API',
+          path: '/examples/api',
+          page: false,
+          layout: 'docs',
+          children: [{ title: 'Reference', path: '/examples/api/reference' }],
+        },
+      ],
+    },
+    { title: 'Examples extended', path: '/examples-extended', layout: 'docs' },
+  ] as unknown as NavigationItem[]
+
+  it('inherits a directory layout for its pages, including hidden pages', () => {
+    expect(findNavigationLayout(navigation, '/examples/overview')).toBe('page')
+    expect(findNavigationLayout(navigation, '/examples/hidden')).toBe('page')
+  })
+
+  it('lets a nested directory override an inherited layout', () => {
+    expect(findNavigationLayout(navigation, '/examples/api/reference')).toBe('docs')
+  })
+
+  it('matches complete path segments only', () => {
+    expect(findNavigationLayout(navigation, '/examples-extended/page')).toBeUndefined()
+  })
+
+  it('supports navigation paths prefixed for version previews', () => {
+    const previewNavigation = [{
+      title: 'Examples',
+      path: '/tree/feature/examples',
+      page: false,
+      layout: 'page',
+      children: [{ title: 'Overview', path: '/tree/feature/examples/overview' }],
+    }] as unknown as NavigationItem[]
+
+    expect(findNavigationLayout(previewNavigation, '/tree/feature/examples/overview')).toBe('page')
+  })
+
+  it('returns undefined without a matching layout', () => {
+    expect(findNavigationLayout(navigation, '/unknown')).toBeUndefined()
+    expect(findNavigationLayout(
+      [{ title: 'Custom', path: '/custom', layout: 'custom' }] as unknown as NavigationItem[],
+      '/custom'
+    )).toBeUndefined()
+    expect(findNavigationLayout([], '/examples')).toBeUndefined()
+    expect(findNavigationLayout(null, undefined)).toBeUndefined()
+  })
+})
+
 describe('findSurroundLinks', () => {
   it('returns the flattened previous and next pages', () => {
     expect(findSurroundLinks(nav, '/getting-started/installation')).toEqual([

From 95d52340937e1fd8fa12456cf227c347587fb7ec Mon Sep 17 00:00:00 2001
From: =?UTF-8?q?S=C3=A9bastien=20Chopin?= <atinux@gmail.com>
Date: Wed, 2 Sep 2026 17:25:35 +0200
Subject: [PATCH 2/2] fix failing test and improve types

---
 app/pages/[...slug].vue |  2 +-
 test/navigation.test.ts | 14 +++++++++-----
 2 files changed, 10 insertions(+), 6 deletions(-)

diff --git a/app/pages/[...slug].vue b/app/pages/[...slug].vue
index 602433c..81a6770 100644
--- a/app/pages/[...slug].vue
+++ b/app/pages/[...slug].vue
@@ -12,7 +12,7 @@ definePageMeta({
 const { toc, seo } = useAppConfig()
 const navigation = inject<Ref<NavigationItem[]>>('navigation')
 const content = useDocsContent()
-const layout = inject('layout')
+const layout = inject<Ref<NavigationLayout>>('layout')
 
 const { data: page } = await useAsyncData(`${content.value.base}:${content.value.path}`, () =>
   content.value.client.get(content.value.path)
diff --git a/test/navigation.test.ts b/test/navigation.test.ts
index 65db153..da4aa0d 100644
--- a/test/navigation.test.ts
+++ b/test/navigation.test.ts
@@ -106,8 +106,8 @@ describe('findNavigationLayout', () => {
     expect(findNavigationLayout(navigation, '/examples/api/reference')).toBe('docs')
   })
 
-  it('matches complete path segments only', () => {
-    expect(findNavigationLayout(navigation, '/examples-extended/page')).toBeUndefined()
+  it('does not inherit a layout from a partial path segment match', () => {
+    expect(findNavigationLayout(navigation, '/examples-extended/page')).toBe('docs')
   })
 
   it('supports navigation paths prefixed for version previews', () => {
@@ -122,12 +122,16 @@ describe('findNavigationLayout', () => {
     expect(findNavigationLayout(previewNavigation, '/tree/feature/examples/overview')).toBe('page')
   })
 
-  it('returns undefined without a matching layout', () => {
-    expect(findNavigationLayout(navigation, '/unknown')).toBeUndefined()
+  it('falls back to docs without a matching supported layout', () => {
+    expect(findNavigationLayout(navigation, '/unknown')).toBe('docs')
     expect(findNavigationLayout(
       [{ title: 'Custom', path: '/custom', layout: 'custom' }] as unknown as NavigationItem[],
       '/custom'
-    )).toBeUndefined()
+    )).toBe('docs')
+  })
+
+  it('returns undefined for the landing page or without enough navigation context', () => {
+    expect(findNavigationLayout(navigation, '/')).toBeUndefined()
     expect(findNavigationLayout([], '/examples')).toBeUndefined()
     expect(findNavigationLayout(null, undefined)).toBeUndefined()
   })