Document-driven

The Document-driven development mode gives a lot more power to Markdown-based websites.


Document-driven development gives a lot more power to Markdown-based websites.

This mode creates a direct binding between the content/ directory and pages.

It also offers page, navigation, surround and globals variables.

This feature is currently available on the edge channel.

Enable the mode

Existing project

Add the documentDriven option in the nuxt.config:

import { defineNuxtConfig } from 'nuxt'export default defineNuxtConfig({  modules: ['@nuxt/content'],  content: {    documentDriven: true  }})

Fresh project

Start with a fresh project with the document driven mode enabled:

npx nuxi init my-website -t doc-driven

You can also use an object to configure the behavior of the mode, checkout the configuration section.

Catch-all page

The document driven mode ships a pre-configured catch-all route.

This injected Vue page is useful for having a minimal project structure:

my-project/
  content/
    index.md
  nuxt.config.ts
  package.json
  tsconfig.json

It comes with a direct binding between your page’s metadada to the OpenGraph tags using the useContentHead() composable, providing effective SEO with no configuration.

Page slots

That page comes with 2 slot components that you can replace at your project level.

To do so, you only have to create a component with the same name in your project components/ directory.

  • <DocumentDrivenNotFound />
components/DocumentDrivenNotFound.vue
<template>  <h1>Page not found</h1></template>
  • <DocumentDrivenEmpty />

This component will be shown when there is no content for the current page, but the page exists.

components/DocumentDrivenEmpty.vue
<template>  <h1>This page is empty</h1></template>

This component will be shown when no page has been found for the current URL.

Layout binding

As the page data is available beforehand, the layout can be defined in the page front-matter:

content/blog/hello-world.md
---layout: article---This page will use the article layout!

By default, it uses the default layout if none is specified.

If you want to use another layout by default, use the layoutFallbacks option in the nuxt.config:

nuxt.config.ts
export default defineNuxtConfig({  content: {    documentDriven: {      layoutFallbacks: ['theme'],    }  }})

This option will search for a theme key in globals, then search for a layout key inside that object. If found, that layout key will be used as a fallback.

Global variables

Queries are be made from a route middlewares and are resolved before your page renders.

This gives access to the useContent() composable anywhere in your app with the following variables:

  • page
  • surround
  • navigation
  • globals
<script setup lang="ts">const { navigation, page, surround, globals } = useContent()console.log(page.value)</script>

Extend global variables

This mode gives you a convenient way to access file data globally in your application.

Use the documentDriven.globals key of in your nuxt.config to specify a query:

nuxt.config.ts
export default defineNuxtConfig({  content: {    documentDriven: {      globals: {        theme: {          where: [            {              _id: 'content:_theme.yml'            }          ],          without: ['_']        }      }    }  }})

This configuration will search for a _theme.yml file in the content/ directory.

If found, a theme object will be accessible via useContent().globals:

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.

<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.

<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 to see a working example.