Setup Nuxt Content with Nuxt pages and layouts

[proven zenith]

Hey all,
I wanna setup a Nuxtv4 project with content, ui and icons but I'm struggling how I can create a cool docs website where I can edit the content on the page whit user permissions. Is there a simple setup demo to use layouts and add .md content files?

[digital jacinth]

Hi @proven zenith. I'm kapa.ai, your friendly support bot. I will try to answer your question by searching through the knowledge base. :wave:

---

To set up a Nuxt 4 project for a documentation website with Nuxt Content, Nuxt UI, and Nuxt Icons, and to enable content editing with user permissions, you can follow these steps based on the official documentation and templates:

---

1. Install Nuxt Content, UI, and Icons

Install the required modules:

npm install @nuxt/content @nuxt/ui @nuxt/icons

Then, register them in your nuxt.config.ts:

export default defineNuxtConfig({
  modules: [
    '@nuxt/ui',
    '@nuxt/icons',
    '@nuxt/content'
  ]
})

Note: Register @nuxt/content after @nuxt/ui to ensure prose components work correctly Nuxt UI Content Integration.

---

2. Set Up Content Directory

Create a content/ directory in your project root and add your Markdown files (e.g., content/index.md, content/docs/intro.md). Nuxt Content will automatically parse these files and make them available for querying and rendering Nuxt Content Directory Structure.

---

3. Create Pages and Layouts

• Layouts:
  Create a layout in app/layouts/default.vue:

  <template>
    <div>
      <AppHeader />
      <slot />
      <AppFooter />
    </div>
  </template>
  

• Pages:
  Use a catch-all route to render Markdown content dynamically:

  app/pages/[...slug].vue:

  <script lang="ts" setup>
  const route = useRoute()
  const { data: page } = await useAsyncData(route.path, () => {
    return queryCollection('content').path(route.path).first()
  })
  </script>

<template>
<div>
<ContentRenderer v-if="page" :value="page" />
<div v-else>Page not found</div>
</div>
</template>

[Nuxt Content Rendering](<https://nuxt.com/docs/4.x/guide/directory-structure/content>)

---

### 4. **Add Nuxt Studio for Visual Editing & Permissions**

To enable editing content with user permissions, use [Nuxt Studio](<https://content.nuxt.com/studio>):

- Go to [nuxt.studio](<https://nuxt.studio>) and log in with GitHub or Google.
- Import your Nuxt Content repository (must be on GitHub).
- Invite team members and manage permissions via Studio.
- Editors can visually edit Markdown, YAML, and JSON files, and changes are synced to your GitHub repo [Nuxt Studio Setup](<https://content.nuxt.com/docs/studio/setup>).

---

### 5. **Use Nuxt UI Components for a Docs Layout**

Leverage Nuxt UI’s `UPage`, `UContentNavigation`, and `UContentToc` components for a documentation layout:

```vue
<template>
<UPage>
  <template #left>
    <UPageAside>
      <UContentNavigation :navigation="navigation" />
    </UPageAside>
  </template>
  <UPageHeader :title="page.title" :description="page.description" />
  <UPageBody>
    <ContentRenderer :value="page" />
    <USeparator />
    <UContentSurround :surround="surround" />
  </UPageBody>
  <template #right>
    <UContentToc :links="page.body.toc.links" />
  </template>
</UPage>
</template>

Nuxt UI Page Component

---

6. Start with a Template

For a quick start, you can use the Docus template, which is a ready-to-use documentation starter built with Nuxt 4, Nuxt Content, Nuxt UI, and Studio integration. It includes layouts, navigation, search, and editing out of the box.

---

Summary:

• Install and configure Nuxt Content, UI, and Icons.
• Organize your Markdown files in the content/ directory.
• Use layouts and dynamic pages to render content.
• Enable collaborative editing and permissions with Nuxt Studio.
• Use Nuxt UI components for a professional docs layout.
• Optionally, start with the Docus template for a full-featured docs site.

For more details, see the Nuxt Content documentation and Nuxt Studio setup guide.

Note: you can ask me a follow up question by @ mentioning me again :speech_balloon:

@proven zenith Kapa.ai is still learning and improving, please let me know how I did by reacting below.

[proven zenith]

@digital jacinth how can i set the defualt design for the content? everthing is among each other

[digital jacinth]

Let me check the knowledge base for you again. One moment! :books:

---

To set a default design (typography, spacing, etc.) for your Nuxt Content, you should use the Nuxt UI module, which provides beautiful and consistent styling for all prose (Markdown-rendered) components. When you use Nuxt UI with Nuxt Content, your Markdown content is automatically styled with proper spacing, headings, lists, and more, so elements are not bunched together.

How to apply default design:

1. Install and register Nuxt UI
   Make sure you have @nuxt/ui installed and registered before @nuxt/content in your nuxt.config.ts:

   export default defineNuxtConfig({
     modules: [
       '@nuxt/ui',
       '@nuxt/content'
     ]
   })
   

   Nuxt UI Content Integration

2. Use the ContentRenderer component
   When you render your Markdown using <ContentRenderer :value="page" />, Nuxt UI will automatically apply its design system to all prose components, ensuring proper spacing and styling for headings, paragraphs, lists, etc.
   Nuxt UI Typography Usage

3. Customize the theme if needed
   You can further customize the default design by overriding prose component styles in your app.config.ts. For example:

   export default defineAppConfig({
     ui: {
       prose: {
         h1: { base: 'text-4xl font-bold mb-4' },
         p: { base: 'mb-6 leading-7' }
       }
     }
   })
   

   Nuxt UI Typography Theme

4. Ensure Tailwind scans your content
   If you use Tailwind CSS, add the @source directive in your CSS to ensure Tailwind picks up classes from your Markdown:

   @import "tailwindcss";
   @import "@nuxt/ui";
   @source "../../../content/**/*";

Nuxt UI Content Integration

---

Summary:
Install and configure Nuxt UI, use the ContentRenderer, and optionally customize the theme in app.config.ts. This will give your content a clean, spaced, and visually appealing default design.

Note: you can ask me a follow up question by @ mentioning me again :speech_balloon:

@proven zenith Kapa.ai is still learning and improving, please let me know how I did by reacting below.

[proven zenith]

@digital jacinth the @inland jewel/ui import was missing in css. How can I change the default design colors

[digital jacinth]

Let me check the knowledge base for you again. One moment! :books:

---

To change the default design colors in Nuxt UI, you should configure the color aliases in your project. Here’s how you can do it:

1. Set Color Aliases in app.config.ts
   You can override the default semantic color aliases (like primary, secondary, etc.) in your app.config.ts file:

   export default defineAppConfig({
     ui: {
       colors: {
         primary: 'blue',
         secondary: 'purple',
         neutral: 'zinc'
       }
     }
   })
   

   This will change the default colors used by Nuxt UI components and prose styling. You can only use colors that exist in your theme (either Tailwind’s default colors or custom ones you’ve defined) Nuxt UI Design System Colors.

2. (Optional) Extend or Add Custom Colors
   If you want to add new semantic colors (e.g., tertiary), first register them in your nuxt.config.ts under the ui.theme.colors key, then assign them in app.config.ts:

   // nuxt.config.ts
   export default defineNuxtConfig({
     ui: {
       theme: {
         colors: [
           'primary',
           'secondary',
           'tertiary',
           'info',
           'success',
           'warning',
           'error'
         ]
       }
     }
   })
   
   // app.config.ts
   export default defineAppConfig({
     ui: {
       colors: {
         primary: 'blue',
         secondary: 'purple',
         tertiary: 'indigo'
       }
     }
   })
   

   Extend Colors Guide

3. Customize Color Shades in CSS (Optional)
   If you want to override specific color shades, you can do so in your app/assets/css/main.css using the @theme static directive:

   @import "tailwindcss";
   @import "@nuxt/ui";

@theme static {
--color-blue-500: #1e40af;
/* ...other custom shades */
}

[Customize Colors in Design System](<https://ui.nuxt.com/docs/getting-started/theme/design-system#colors>)

---

**Remember:**  
- Always import `@nuxt/ui` in your main CSS file to ensure the styles and variables are available.
- Only use color names that exist in your Tailwind or custom theme.

This approach will update the default design colors for all Nuxt UI components and your content styling.
----------------------
Note: you can ask me a follow up question by @ mentioning me again :speech_balloon:
----------------------

@proven zenith Kapa.ai is still learning and improving, please let me know how I did by reacting below.

[proven zenith]

@digital jacinth i've set the background color with bg-neutral-800 an it's set but it looks more like dark blue. Does ui or content override this?

[digital jacinth]

Let me check the knowledge base for you again. One moment! :books:

---

If you set a background color using bg-neutral-800 and it appears more like dark blue, this is likely because Nuxt UI redefines the neutral color alias to use the slate color from Tailwind by default, not the classic gray. The slate palette can have a bluish tint, especially in the darker shades, which is why bg-neutral-800 may look more blue than gray.

This behavior is intentional and part of Nuxt UI's design system, as described in the migration guide and design system documentation:

• The gray color has been renamed to neutral, and by default, neutral maps to slate (Migration to v3, Design System Colors).

• You can change which Tailwind color is used for neutral by overriding the color alias in your app.config.ts:

  export default defineAppConfig({
    ui: {
      colors: {
        neutral: 'zinc' // or 'gray' if you prefer the classic gray palette
      }
    }
  })
  

Neither Nuxt UI nor Nuxt Content will override your explicit bg-neutral-800 class, but the underlying color for neutral is determined by your project's configuration. If you want a more classic gray, set neutral to zinc or gray as shown above.

Summary:
The bluish tint comes from the default mapping of neutral to slate. You can change this mapping in your config if you want a different shade for neutralMigration to v3, Design System Colors.

Note: you can ask me a follow up question by @ mentioning me again :speech_balloon:

@proven zenith Kapa.ai is still learning and improving, please let me know how I did by reacting below.

[proven zenith]

@digital jacinth looks like I can not use ui.colors
Vue: Object literal may only specify known properties, and colors does not exist in type Partial<ModuleOptions>
I wanna change slate to neutral

[digital jacinth]

Let me check the knowledge base for you again. One moment! :books:

---

You are correct that the ui.colors key is not valid in nuxt.config.ts. According to the official documentation, to change which Tailwind color is used for the neutral alias (for example, from slate to zinc), you should use the following structure in your configuration files:

• In nuxt.config.ts, you do not use ui.colors. Instead, you use ui.theme.colors to define which color aliases are available:

export default defineNuxtConfig({
  ui: {
    theme: {
      colors: [
        'primary',
        'secondary',
        'neutral', // this is the alias, not the palette
        'info',
        'success',
        'warning',
        'error'
      ]
    }
  }
})

Extend colors

• To map the neutral alias to a specific Tailwind palette (like zinc instead of the default slate), you must set this in your app.config.ts:

export default defineAppConfig({
  ui: {
    colors: {
      neutral: 'zinc' // or 'gray', etc.
    }
  }
})

Design System Colors

Summary:

• Use ui.theme.colors in nuxt.config.ts to define which aliases are available.
• Use ui.colors in app.config.ts to map an alias (like neutral) to a Tailwind palette.
• Do not use ui.colors in nuxt.config.ts—that will cause a type error, as you saw.

If you follow this pattern, you can successfully change the neutral color from slate to zinc or any other supported palette.

Note: you can ask me a follow up question by @ mentioning me again :speech_balloon: