nuxt-content · larbish · May 7, 2026 · May 7, 2026 · May 7, 2026 · May 7, 2026
diff --git a/docs/app/app.css b/docs/app/app.css
@@ -0,0 +1,3 @@
+@theme {
+    --font-sans: "Public Sans", sans-serif;
+}
diff --git a/docs/app/assets/css/main.css b/docs/app/assets/css/main.css
diff --git a/docs/content/en/1.getting-started/4.project-structure.md b/docs/content/en/1.getting-started/4.project-structure.md
@@ -140,7 +140,8 @@ You need a `nuxt.config.ts` to be set if you want to override your app with Nuxt
 ```bash
 my-docs/
 ├── app/                 # App directory (optional)
-    ├── app.config.ts    # App configuration
+│   ├── app.config.ts    # App configuration
+│   ├── app.css          # Custom theme (auto-imported by Docus)
 │   ├── components/      # Custom Vue components
 │   ├── layouts/         # Custom layouts
 │   ├── pages/           # Custom Vue pages (outside of content)

diff --git a/docs/content/en/2.concepts/4.theme.md b/docs/content/en/2.concepts/4.theme.md
@@ -13,17 +13,11 @@ For a full overview of Nuxt UI theming, check out the Nuxt UI documentation.
 
 ## Override with `@theme`
 
-You can customize your theme with CSS variables inside a `@theme` directive to define your project's custom design tokens, like fonts, colors, and breakpoints
+You can customize your theme with CSS variables inside a `@theme` directive to define your project's custom design tokens, like fonts, colors, and breakpoints.
 
-You can override this theme by creating a `main.css` file in your application.
-
-This way you can override your theme:
-
-::code-group
-```css [assets/css/main.css]
-@import "tailwindcss";
-@import "@nuxt/ui";
+To override the theme, create an `app/app.css` file in your project:
 
+```css [app/app.css]
 @theme {
   --font-sans: 'Public Sans', sans-serif;
 
@@ -43,12 +37,8 @@ This way you can override your theme:
 }
 ```
 
-```ts [nuxt.config.ts]
-export default defineNuxtConfig({
-  modules: ['@nuxt/ui'],
-  css: ['~/assets/css/main.css']
-})
-```
+::warning
+Docus automatically imports `app/app.css` — you don't need to add it to the `css` array in `nuxt.config.ts`, and you should **not** include `@import "tailwindcss"` in this file as Docus handles it for you.
 ::
 
 ## Colors

diff --git a/docs/content/fr/1.getting-started/4.project-structure.md b/docs/content/fr/1.getting-started/4.project-structure.md
@@ -140,6 +140,7 @@ Un fichier `nuxt.config.ts` doit être existant pour surcharger votre app Nuxt.
 my-docs/
 ├── app/                 # Répertoire app (optionnel)
 │   ├── app.config.ts    # App configuration
+│   ├── app.css          # Thème personnalisé (auto-importé par Docus)
 │   ├── components/      # Composants Vue personnalisés
 │   ├── layouts/         # Layouts personnalisés
 │   ├── pages/           # Pages Vue personnalisées (en dehors du contenu)

diff --git a/docs/content/fr/2.concepts/4.theme.md b/docs/content/fr/2.concepts/4.theme.md
@@ -15,15 +15,9 @@ Pour un aperçu complet du système de thème Nuxt UI, consultez la documentatio
 
 Vous pouvez personnaliser votre thème avec des variables CSS à l'intérieur d'une directive `@theme` pour définir les tokens de design personnalisés de votre projet, comme les polices, couleurs et breakpoints.
 
-Vous pouvez surcharger ce thème en créant un fichier `main.css` dans votre application.
-
-De cette façon, vous pouvez surcharger votre thème :
-
-::code-group
-```css [assets/css/main.css]
-@import "tailwindcss";
-@import "@nuxt/ui";
+Pour surcharger le thème, créez un fichier `app/app.css` dans votre projet :
 
+```css [app/app.css]
 @theme {
   --font-sans: 'Public Sans', sans-serif;
 
@@ -43,12 +37,8 @@ De cette façon, vous pouvez surcharger votre thème :
 }
 ```
 
-```ts [nuxt.config.ts]
-export default defineNuxtConfig({
-  modules: ['@nuxt/ui'],
-  css: ['~/assets/css/main.css']
-})
-```
+::warning
+Docus importe automatiquement `app/app.css` — vous n'avez pas besoin de l'ajouter au tableau `css` dans `nuxt.config.ts`, et vous ne devez **pas** inclure `@import "tailwindcss"` dans ce fichier car Docus s'en charge pour vous.
 ::
 
 ## Couleurs

diff --git a/docs/nuxt.config.ts b/docs/nuxt.config.ts
@@ -1,7 +1,6 @@
 export default defineNuxtConfig({
   extends: ['docus'],
   modules: ['@nuxtjs/i18n', 'nuxt-studio'],
-  css: ['~/assets/css/main.css'],
   site: {
     name: 'Docus',
   },

diff --git a/layer/app/plugins/i18n.ts b/layer/app/plugins/i18n.ts
@@ -1,7 +1,7 @@
 import type { RouteLocationNormalized } from 'vue-router'
 import { consola } from 'consola'
 
-const log = consola.withTag('Docus')
+const log = consola.withTag('docus')
 
 // Lazy import functions for locale files (bundled but not eagerly loaded)
 const localeFiles = import.meta.glob<{ default: Record<string, unknown> }>('../../i18n/locales/*.json')

diff --git a/layer/modules/assistant/index.ts b/layer/modules/assistant/index.ts
@@ -21,7 +21,7 @@ export interface AssistantModuleOptions {
   model?: string
 }
 
-const log = logger.withTag('Docus')
+const log = logger.withTag('docus')
 
 const defaults: Required<AssistantModuleOptions> = {
   apiPath: '/__docus__/assistant',
@@ -77,7 +77,9 @@ export default defineNuxtModule<AssistantModuleOptions>({
     )
 
     if (!hasAiGatewayAuth) {
-      log.warn('AI assistant disabled: neither AI_GATEWAY_API_KEY nor VERCEL_OIDC_TOKEN found')
+      nuxt.hook('modules:done', () => {
+        log.warn('AI assistant disabled: neither `AI_GATEWAY_API_KEY` nor `VERCEL_OIDC_TOKEN` found')
+      })
       return
     }
 

diff --git a/layer/modules/config.ts b/layer/modules/config.ts
@@ -5,7 +5,7 @@ import { join } from 'node:path'
 import { inferSiteURL, getPackageJsonMetadata } from '../utils/meta'
 import { getGitBranch, getGitEnv, getLocalGitInfo } from '../utils/git'
 
-const log = logger.withTag('Docus')
+const log = logger.withTag('docus')
 
 type I18nLocale = string | { code: string, name?: string }
 type DocusI18nOptions = { locales?: I18nLocale[], strategy?: string }

diff --git a/layer/modules/css.ts b/layer/modules/css.ts
@@ -1,21 +1,37 @@
-import { defineNuxtModule, addTemplate, createResolver } from '@nuxt/kit'
-import { joinURL } from 'ufo'
+import { defineNuxtModule, addTemplate, createResolver, logger } from '@nuxt/kit'
+import { existsSync } from 'node:fs'
+import { readFile } from 'node:fs/promises'
+import { resolve } from 'pathe'
 import { resolveModulePath } from 'exsolve'
 
+const log = logger.withTag('docus')
+
 export default defineNuxtModule({
   meta: {
-    name: 'css',
+    name: 'docus-css',
   },
   async setup(_options, nuxt) {
-    const dir = nuxt.options.rootDir
     const resolver = createResolver(import.meta.url)
 
-    const contentDir = joinURL(dir, 'content')
+    const contentDir = resolve(nuxt.options.rootDir, 'content')
     const uiPath = resolveModulePath('@nuxt/ui', { from: import.meta.url, conditions: ['style'] })
     const tailwindPath = resolveModulePath('tailwindcss', { from: import.meta.url, conditions: ['style'] })
     const layerDir = resolver.resolve('../app')
     const assistantDir = resolver.resolve('../modules/assistant')
 
+    let userDocusPath: string | null = resolve(nuxt.options.srcDir, 'app.css')
+    if (existsSync(userDocusPath)) {
+      const userDocusCss = await readFile(userDocusPath, 'utf-8')
+      if (userDocusCss.includes('@import "tailwindcss"')) {
+        nuxt.hook('modules:done', () => {
+          log.warn('`app.css` contains `@import "tailwindcss";` consider removing it to avoid duplicate css.')
+        })
+      }
+    }
+    else {
+      userDocusPath = null
+    }
+
     const cssTemplate = addTemplate({
       filename: 'docus.css',
       getContents: () => {
@@ -25,7 +41,13 @@ export default defineNuxtModule({
 @source "${contentDir.replace(/\\/g, '/')}/**/*";
 @source "${layerDir.replace(/\\/g, '/')}/**/*";
 @source "../../app.config.ts";
-@source "${assistantDir.replace(/\\/g, '/')}/**/*";`
+@source "${assistantDir.replace(/\\/g, '/')}/**/*";
+
+@layer base {
+  :root {
+    --ui-container: 90rem;
+  }
+}` + (userDocusPath ? `\n@import ${JSON.stringify(userDocusPath)};` : '')
       },
     })
 

diff --git a/layer/modules/markdown-rewrite.ts b/layer/modules/markdown-rewrite.ts
@@ -2,7 +2,7 @@ import { defineNuxtModule, logger } from '@nuxt/kit'
 import { resolve } from 'node:path'
 import { readFile, writeFile } from 'node:fs/promises'
 
-const log = logger.withTag('Docus')
+const log = logger.withTag('docus')
 
 type I18nLocale = string | { code: string }
 type DocusI18nOptions = { locales?: I18nLocale[] }

diff --git a/layer/modules/skills/index.ts b/layer/modules/skills/index.ts
@@ -19,7 +19,7 @@ export interface SkillsModuleOptions {
 const SKILL_NAME_REGEX = /^[a-z0-9](?:[a-z0-9-]*[a-z0-9])?$/
 const MAX_NAME_LENGTH = 64
 
-const log = logger.withTag('Docus')
+const log = logger.withTag('docus')
 
 const defaults: Required<SkillsModuleOptions> = {
   dir: 'skills',
@@ -38,7 +38,9 @@ export default defineNuxtModule<SkillsModuleOptions>({
     const catalog = await scanSkills(skillsDir)
     if (!catalog.length) return
 
-    log.info(`Found ${catalog.length} agent skill${catalog.length > 1 ? 's' : ''}: ${catalog.map(s => s.name).join(', ')}`)
+    nuxt.hook('modules:done', () => {
+      log.info(`Found ${catalog.length} agent skill${catalog.length > 1 ? 's' : ''}: ${catalog.map(s => s.name).join(', ')}`)
+    })
 
     nuxt.options.runtimeConfig.skills = { catalog }
 

diff --git a/layer/package.json b/layer/package.json
@@ -50,6 +50,7 @@
     "motion-v": "^2.2.1",
     "nuxt-llms": "^0.2.0",
     "nuxt-og-image": "^6.4.5",
+    "pathe": "^2.0.3",
     "pkg-types": "^2.3.0",
     "scule": "^1.3.0",
     "shiki-stream": "^0.1.4",

diff --git a/pnpm-lock.yaml b/pnpm-lock.yaml