Getting Started

Docus Plus is a Nuxt layer you can use to extend your new or existing Nuxt project. Docus Plus itself is an extension of the Docus layer but with extra batteries and polish included (and some opinionated decisions). Docus Plus provides a documentation shell, Scalar API references, server logic, and AI integration via Mistral AI, and much more.

This page walks through the setup using the create-docus-plus CLI.

1. Create a project with the CLI

The quickest way to start is the Docus Plus generator. It creates a standalone project from the maintained default starter:

npx create-docus-plus my-docs
cd my-docs
pnpm install
pnpm dev

Without arguments, it creates a project in ./docs:

npx create-docus-plus

The CLI delegates project creation to Nuxt's initializer and downloads .starters/default from the Docus Plus repository. Nuxt handles prompts, package metadata, and existing destinations.

Manual setup

Install the Docus Plus layer with your package manager:

pnpm add @onderwijsin/docus-plus

Extend it from the consuming application's nuxt.config.ts:

export default defineNuxtConfig({
  extends: ["@onderwijsin/docus-plus"]
});

The generated project has the same package-based extension and includes working examples for the available integrations.

2. Add the environment

Create the environment values required by the layer. At minimum, configure the site URL and the environment mode:

MODE=development|preview|production
NUXT_PUBLIC_SITE_URL=http://localhost:3000
API_TOKEN=required
OPENAPI_SOURCE_TYPE=remote
OPENAPI_SOURCE_LOCATION=https://registry.scalar.com/@scalar/apis/galaxy?format=yaml
AI_GATEWAY_API_KEY=required-dummy-value
NUXT_OG_IMAGE_SECRET=required
TURNSTILE_SITE_KEY=optional
TURNSTILE_SECRET_KEY=optional
MISTRAL_API_KEY=required

We recommend using Varlock to manage your environment variables, since it provides a agent safe schema with strong type safety. The started template containes an envs/ directory with Varlock schema's. If you wish to use Varlock, you need to follow these steps:

1. run pnpm add varlock @varlock/vite-integration
2. add remote secret references to the schema files (or add a .env.local)
3. uncomment the Varlock options in nuxt.config.ts

If you don't want to use Varlock, just remove the envs/ directory and add a .env file in your project root. For a validated profile setup with Proton Pass, continue with

3. Add the landing page

Create content/index.yml. The layer validates the landing-page shape with Nuxt Content, so include SEO metadata, a hero, features, and a call to action:

seo:
  title: Example documentation
  description: Documentation for the Example project.
  ogImage: https://example.com/og-image.png
hero:
  title: Build with the Example platform
  description: Learn how to use the Example platform.
  links:
    - label: Get started
      to: /getting-started
      color: primary
features:
  title: Everything you need
  description: A focused set of guides and references.
  items:
    - icon: i-lucide-book-open
      title: Guides
      description: Explain the main integration paths.
cta:
  title: Start building
  description: Follow the guides to create your first integration.
  links:
    - label: Read the guide
      to: /getting-started
      color: primary

The starter's landing page is a complete working version of this example.

4. Add documentation pages

Create Markdown files below content/docs/. Nuxt Content turns each file into a route and Docus uses its frontmatter to build page metadata and navigation:

---
title: Getting started
description: Create your first integration.
navigation:
  icon: lucide:rocket
---

Your guide starts here.

Use numbered filenames to control ordering. Add .navigation.yml to a directory when you want a section title or icon.

5. Configure the application

Keep consumer-specific settings in the consuming application. The layer's defaults are reusable, while the app owns its identity, branding, and content:

export default defineAppConfig({
  ui: {
    colors: { primary: "indigo", neutral: "slate" }
  }
});

Read the Customization Guide for more options on customizing the UI.

Run the site

Start your documentation site locally:

pnpm dev

During a deployment build all documentation pages will be prerender.

pnpm build
pnpm start # for node runtime

Continue with the guides

• Working with content explains pages, navigation, and landing content.
• Customise the UI explains consumer branding and OG image templates.
• Integrations and deployment covers the assistant, API reference, and production output.
• Manage environment variables with Varlock covers validated profiles and Proton Pass secrets.
• Scalar and OpenAPI reference explains the automatic API Explorer and parsing.