feat: disable document driven with route meta (#1333)

Co-authored-by: Sébastien Chopin <seb@nuxtjs.com>
Co-authored-by: Yaël Guilloux <yael.guilloux@gmail.com>

docs/content/3.guide/1.writing/7.document-driven.md

@@ -164,6 +164,38 @@ const { theme } = useContent().globals
 
 Any changes to these files will be automatically reflected in the application during development.
 
+## Disable or control the page data
+
+Using special `documentDriven` meta in your pages, you can disable this feature for specific route or control it's behavior.
+
+### Disable document driven
+
+Setting `documentDriven` to `false` will disable document driven. This means that exposed refs from `useContent()` will be `undefined`.
+
+```html
+<script setup lang="ts">
+definePageMeta({
+  documentDriven: false
+})
+</script>
+```
+
+### Control data
+
+To control document driven data you can pass an object to `documentDriven` meta key and enable/disable specific parts of it.
+
+```html
+<script setup lang="ts">
+definePageMeta({
+  documentDriven: {
+    page: true, // Keep page fetching enabled
+    surround: false // Disable surround fetching
+  }
+})
+</script>
+```
+
+
 ## Example
 
 Jump into the [Document Driven Example](/examples/essentials/document-driven) to see a working example.

src/runtime/plugins/documentDriven.ts

@@ -46,6 +46,12 @@ export default defineNuxtPlugin((nuxt) => {
   }
 
   const refresh = async (to: RouteLocationNormalized | RouteLocationNormalizedLoaded, force: boolean = false) => {
+    const routeConfig = (to.meta.documentDriven || {}) as any
+    // Disabled document driven mode on next route
+    if (to.meta.documentDriven === false) {
+      return
+    }
+
     const { navigation, page, globals, surround } = useContentState()
 
     // Normalize route path
@@ -57,7 +63,7 @@ export default defineNuxtPlugin((nuxt) => {
      *
      * `navigation`
      */
-    if (moduleOptions.navigation) {
+    if (moduleOptions.navigation && routeConfig.navigation !== false) {
       const navigationQuery = () => {
         const { navigation } = useContentState()
 
@@ -128,7 +134,7 @@ export default defineNuxtPlugin((nuxt) => {
     /**
      * `page`
      */
-    if (moduleOptions.page) {
+    if (moduleOptions.page && routeConfig.page !== false) {
       const pageQuery = () => {
         const { page } = useContentState()
 
@@ -155,7 +161,7 @@ export default defineNuxtPlugin((nuxt) => {
     /**
      * `surround`
      */
-    if (moduleOptions.surround) {
+    if (moduleOptions.surround && routeConfig.surround !== false) {
       const surroundQuery = () => {
         // Return same surround as page is already loaded
         if (!force && page.value && page.value._path === _path) {
@@ -195,22 +201,23 @@ export default defineNuxtPlugin((nuxt) => {
       if (_globals) {
         globals.value = _globals
       }
-      // Find used layout
-      const layoutName = findLayout(to, _page, _navigation, _globals)
-
-      // Prefetch layout component
-      const layout = layouts[layoutName]
-
-      if (layout && layout?.__asyncLoader && !layout.__asyncResolved) {
-        await layout.__asyncLoader()
-      }
-      // Apply layout
-      to.meta.layout = layoutName
 
       // Use `redirect` key to redirect to another page
       if (_page?.redirect) { return _page?.redirect }
 
       if (_page) {
+        // Find used layout
+        const layoutName = findLayout(to, _page, _navigation, _globals)
+
+        // Prefetch layout component
+        const layout = layouts[layoutName]
+
+        if (layout && layout?.__asyncLoader && !layout.__asyncResolved) {
+          await layout.__asyncLoader()
+        }
+        // Apply layout
+        to.meta.layout = layoutName
+
         // Update values
         page.value = _page
         process.client && pagesCache.set(_path, _page)

test/document-driven.test.ts

@@ -13,4 +13,18 @@ describe('fixtures:document-driven', async () => {
 
     expect(html).contains('Home | Document Driven Fixture')
   })
+
+  test('disabled document driven', async () => {
+    const html = await $fetch('/disabled')
+
+    expect(html).contains('<div>surround: </div>')
+    expect(html).contains('<div>page: </div>')
+  })
+
+  test('disabled surround document driven', async () => {
+    const html = await $fetch('/no-surround')
+
+    expect(html).contains('<div>surround: </div>')
+    expect(html).contains('<div>page: {')
+  })
 })

test/features/navigation.ts

@@ -12,7 +12,6 @@ export const testNavigation = () => {
           _params: jsonStringify(query)
         }
       })
-      console.log(JSON.stringify(list, null, 2))
 
       expect(list.find(item => item._path === '/')).toBeTruthy()
       expect(list.find(item => item._path === '/').children).toBeUndefined()

test/fixtures/document-driven/content/no-surround.md

@@ -0,0 +1 @@
+# Surround disabled in document driven

test/fixtures/document-driven/pages/disabled.vue

@@ -0,0 +1,15 @@
+<template>
+  <div>
+    Document driven is disabled for this page
+    <div>page: {{ page }}</div>
+    <div>surround: {{ surround }}</div>
+  </div>
+</template>
+
+<script setup lang="ts">
+definePageMeta({
+  documentDriven: false
+})
+
+const { page, surround } = useContent()
+</script>

test/fixtures/document-driven/pages/no-surround.vue

@@ -0,0 +1,17 @@
+<template>
+  <div>
+    Document driven page is disabled for this route
+    <div>page: {{ page }}</div>
+    <div>surround: {{ surround }}</div>
+  </div>
+</template>
+
+<script setup lang="ts">
+definePageMeta({
+  documentDriven: {
+    surround: false
+  }
+})
+
+const { page, surround } = useContent()
+</script>