Nuxt Integration

Docus is built as a Nuxt layer, allowing it to seamlessly extend Nuxt applications while providing full access to the Nuxt ecosystem.

Nuxt Layer Architecture

Docus uses Nuxt’s layer feature to provide a complete documentation framework that can be extended:

[nuxt.config.ts]

export default defineNuxtConfig({
  extends: ['docus'],
  // Your configuration
})

How Layers Work

Layer Extension

Docus is extended using the extends property, inheriting all components, composables, and configuration

Override Priority

Your local files automatically override Docus layer files with the same name

Configuration Merging

Configurations are deep-merged, allowing you to customize any aspect

Nuxt layers enable Docus to be fully extensible while maintaining a clean separation between framework and user code.

Included Modules

Docus includes and configures several essential Nuxt modules:

[layer/nuxt.config.ts]

export default defineNuxtConfig({
  modules: [
    '@nuxt/ui',
    '@nuxt/content',
    '@nuxt/image',
    '@nuxtjs/robots',
    '@nuxtjs/mcp-toolkit',
    'nuxt-og-image',
    'nuxt-llms',
  ],
})

Core Modules

@nuxt/ui

Provides the component library and design system used throughout Docus.

ui: {
  colors: {
    primary: 'emerald',
    neutral: 'zinc',
  },
}

Nuxt UI Documentation

@nuxt/content

Powers the Markdown and MDC content system with collections and queries.

content: {
  experimental: { sqliteConnector: 'native' },
  build: {
    markdown: {
      highlight: {
        langs: ['bash', 'typescript', 'vue'],
      },
    },
  },
}

Nuxt Content Documentation

@nuxt/image

Optimizes images with automatic resizing and format conversion.

<NuxtImg src="/hero.png" width="800" height="600" />

Nuxt Image Documentation

@nuxtjs/robots

Generates robots.txt for SEO.

robots: {
  groups: [{
    userAgent: '*',
    allow: '/',
  }],
  sitemap: '/sitemap.xml',
}

@nuxtjs/mcp-toolkit

Provides Model Context Protocol server for AI integration.

mcp: {
  name: 'Docus documentation',
  browserRedirect: '/en/ai/mcp',
}

nuxt-og-image

Generates Open Graph images for social media.

defineOgImageComponent('OgImageDocs', {
  title: 'Getting Started',
  description: 'Learn how to use Docus',
})

nuxt-llms

Generates llms.txt files for AI consumption.

llms: {
  domain: 'https://docus.dev',
  title: 'Docus',
  description: 'Write beautiful docs with Markdown.',
}

Custom Docus Modules

Docus includes four internal modules that provide core functionality:

Config Module

Automatically configures site metadata, SEO, and i18n:

[layer/modules/config.ts]

export default defineNuxtModule({
  async setup(_options, nuxt) {
    // Infer site URL and metadata
    const url = inferSiteURL()
    const meta = await getPackageJsonMetadata(nuxt.options.rootDir)
    const gitInfo = await getLocalGitInfo(nuxt.options.rootDir)
    
    // Configure defaults
    nuxt.options.appConfig.header = defu(nuxt.options.appConfig.header, {
      title: meta.name || gitInfo?.name || '',
    })
    
    // Setup i18n locale filtering
    if (nuxt.options.i18n) {
      const filteredLocales = filterLocalesByAvailability()
      nuxt.options.i18n.strategy = 'prefix'
    }
  },
})

function

Automatically detects site URL from environment variables or hosting platform

function

Extracts name and description from package.json

function

Reads Git repository information for GitHub integration

Routing Module

Manages route generation and i18n routing:

[layer/modules/routing.ts]

export default defineNuxtModule({
  setup(_options, nuxt) {
    const isI18nEnabled = !!(nuxt.options.i18n?.locales)
    
    // Add landing page if not exists
    if (!landingPageExists(nuxt.options.rootDir)) {
      extendPages((pages) => {
        pages.push({
          name: isI18nEnabled ? 'lang-index' : 'index',
          path: isI18nEnabled ? '/:lang?' : '/',
          file: resolve('../app/templates/landing.vue'),
        })
      })
    }
  },
})

Markdown Rewrite Module

Configures Vercel rewrites for AI agents to access raw Markdown:

[layer/modules/markdown-rewrite.ts]

export default defineNuxtModule({
  setup(_options, nuxt) {
    nuxt.hooks.hook('nitro:init', (nitro) => {
      nitro.hooks.hook('compiled', async () => {
        // Add routes for markdown content access
        const routes = [
          {
            src: '^/$',
            dest: '/llms.txt',
            has: [{ type: 'header', key: 'accept', value: '(.*)text/markdown(.*)' }],
          },
        ]
        
        // Write to Vercel config
        vcConfig.routes.unshift(...routes)
      })
    })
  },
})

The markdown-rewrite module only activates on Vercel deployments. It’s skipped in development and other hosting platforms.

CSS Module

Manages CSS processing and custom icon collections:

[layer/modules/css.ts]

export default defineNuxtModule({
  setup() {
    // Configure custom icon collections
    const nuxt = useNuxt()
    nuxt.options.icon ||= {}
    nuxt.options.icon.customCollections ||= []
    nuxt.options.icon.customCollections.push({
      prefix: 'custom',
      dir: join(nuxt.options.srcDir, 'assets/icons'),
    })
  },
})

Nuxt Content Integration

Docus deeply integrates with Nuxt Content:

Content Collections

Automatic collection setup based on structure:

[layer/content.config.ts]

const collections = {
  docs: defineCollection({
    type: 'page',
    source: {
      cwd,
      include: hasDocsFolder ? 'docs/**' : '**',
      prefix: hasDocsFolder ? '/docs' : '/',
      exclude: ['index.md'],
    },
    schema: z.object({
      links: z.array(z.object({
        label: z.string(),
        icon: z.string(),
        to: z.string(),
      })).optional(),
    }),
  }),
}

MDC Configuration

[layer/nuxt.config.ts]

content: {
  build: {
    markdown: {
      remarkPlugins: {
        'remark-mdc': {
          options: {
            autoUnwrap: true,
          },
        },
      },
    },
  },
},
mdc: {
  highlight: {
    shikiEngine: 'javascript',
  },
},

Syntax Highlighting
SQLite Connector

Docus uses Shiki with JavaScript engine for fast, accurate code highlighting in multiple languages.

Experimental native SQLite connector improves content query performance:

content: {
  experimental: { sqliteConnector: 'native' },
}

Nitro & Prerendering

Docus configures Nitro for optimal static site generation:

[layer/nuxt.config.ts]

nitro: {
  prerender: {
    crawlLinks: true,
    failOnError: false,
    autoSubfolderIndex: false,
  },
},
hooks: {
  'nitro:config'(nitroConfig) {
    // Add locale routes for prerendering
    const routes = locales.map(locale => `/${locale.code}`)
    nitroConfig.prerender.routes.push(...routes)
    nitroConfig.prerender.routes.push('/sitemap.xml')
  },
},

boolean

default:"true"

Automatically discovers and prerenders all linked pages

boolean

default:"false"

Continues prerendering even if individual pages fail

Vite Configuration

Docus extends Vite configuration for optimal bundling:

[layer/nuxt.config.ts]

() => {
  extendViteConfig((config) => {
    config.optimizeDeps ||= {}
    config.optimizeDeps.include ||= []
    config.optimizeDeps.include.push('@nuxt/content > slugify')
    
    // Fix ESM export issues
    if (process.env.AI_GATEWAY_API_KEY) {
      config.optimizeDeps.include.push('@vercel/oidc')
    }
  })
}

Adding Modules

Extend Docus with additional Nuxt modules:

[nuxt.config.ts]

export default defineNuxtConfig({
  extends: ['docus'],
  modules: [
    '@nuxtjs/i18n',
    '@nuxtjs/plausible',
    'nuxt-studio',
  ],
})

Install Module

npm install @nuxtjs/plausible

Add to Config

Add the module to the modules array

Configure

Add module-specific configuration

Compatibility

Docus is compatible with:

Nuxt 3

Full support for Nuxt 3.x

Node.js 18+

Requires Node.js 18 or higher

TypeScript

Full TypeScript support with types

Edge Functions

Works with Vercel Edge, Netlify Edge, Cloudflare Workers

Compatibility Date

[layer/nuxt.config.ts]

compatibilityDate: '2025-07-22',
experimental: {
  asyncContext: true,
},

Docus uses modern Nuxt features including async context for improved performance and developer experience.

Get Started

Concepts

Essentials

AI Features

Nuxt Integration

Nuxt Layer Architecture

How Layers Work

Included Modules

Core Modules

Custom Docus Modules

Config Module

Routing Module

Markdown Rewrite Module

CSS Module

Nuxt Content Integration

Content Collections

MDC Configuration

Nitro & Prerendering

Vite Configuration

Adding Modules

Compatibility

Nuxt 3

Node.js 18+

TypeScript

Edge Functions

Compatibility Date

Next Steps

Nuxt Docs

Customization

​Nuxt Layer Architecture

​How Layers Work

​Included Modules

​Core Modules

​Custom Docus Modules

​Config Module

​Routing Module

​Markdown Rewrite Module

​CSS Module

​Nuxt Content Integration

​Content Collections

​MDC Configuration

​Nitro & Prerendering

​Vite Configuration

​Adding Modules

​Compatibility

Nuxt 3

Node.js 18+

TypeScript

Edge Functions

​Compatibility Date

​Next Steps

Nuxt Docs

Customization

Nuxt Layer Architecture

How Layers Work

Included Modules

Core Modules

Custom Docus Modules

Config Module

Routing Module

Markdown Rewrite Module

CSS Module

Nuxt Content Integration

Content Collections

MDC Configuration

Nitro & Prerendering

Vite Configuration

Adding Modules

Compatibility

Compatibility Date

Next Steps