---
title: "Configuration"
description: "Customize your Docus documentation from the Nuxt application configuration file. "
canonical_url: "https://docus.dev/en/concepts/configuration"
---
# Configuration

> Customize your Docus documentation from the Nuxt application configuration file.

Docus allows you to configure your documentation through the [app.config.ts](https://nuxt.com/docs/guide/directory-structure/app-config) file provided by Nuxt.

<warning>

You need a `nuxt.config.ts` to be set if you want to override your app config. Without an existing Nuxt config file, changes won't be applied.

</warning>

## SEO

Technical SEO is tricky and boring. Docus offers a solid, opt-in default setup that works out of the box, while giving you full control to customize your SEO metadata, from page titles to social sharing images.

### Metadata

Docus offers flexible `SEO` metadata configuration, allowing you to easily override values globally or on a per-page basis.

#### Global configuration

Define default `SEO` metas for your entire documentation in `app.config.ts`. These values will be used as fallbacks across pages that don't specify their own in the front-matter as described in next section.

You can also configure your `site.name` value from your `nuxt.config.ts` file, default is based on your `package.json` name.

<code-group>

```ts [app.config.ts]
export default defineAppConfig({
  seo: {
    // Default to `%s - ${site.name}`
    titleTemplate: '',
    // Default to package.json name
    title: '',
    // Default to package.json description
    description: ''
  },
})
```

```ts [nuxt.config.ts]
export default defineNuxtConfig({
  site: {
    name: 'Docus',
  },
})
```

</code-group>

#### Per-page configuration

Each Markdown file in the `content/` directory starts with a frontmatter block (`---`). You can define `SEO` metadata per page by using the `seo` key:

```md [content/concepts/configuration.md]
---
seo:
  title: 'Configuration'
  description: 'Customize your Docus documentation from the Nuxt application configuration file.'
---

<!-- Page content -->
```

<tip to="https://docus.dev/en/concepts/edition#frontmatter">

For more details on front-matter, see the edition guide.

</tip>

### Structured data

Docus emits [JSON-LD](https://json-ld.org) with [`nuxt-schema-org`](https://nuxtseo.com/docs/schema-org):

- `WebSite` and `WebPage` on every page
- `TechArticle` and `BreadcrumbList` on documentation pages

Search engines and AI agents read it to tell what a page is without parsing your markup.

The landing page can also describe what your site *is*. Add `seo.schema` and Docus emits a linked graph of your product and the organization behind it:

```ts [app.config.ts]
export default defineAppConfig({
  seo: {
    schema: {
      type: 'SoftwareApplication',
      applicationCategory: 'DeveloperApplication',
      price: 0,
      sameAs: [
        'https://github.com/nuxt-content/docus',
        'https://www.npmjs.com/package/docus',
      ],
      organization: {
        name: 'Nuxt',
        url: 'https://nuxt.com',
        logo: '/logo/logo-dark.svg',
        sameAs: ['https://github.com/nuxt'],
      },
    },
  },
})
```

<table>
<thead>
  <tr>
    <th>
      Field
    </th>
    
    <th>
      Description
    </th>
  </tr>
</thead>

<tbody>
  <tr>
    <td>
      <code>
        type
      </code>
    </td>
    
    <td>
      What the site is: <code>
        SoftwareApplication
      </code>
      
      , <code>
        Product
      </code>
      
      , <code>
        Organization
      </code>
      
       or <code>
        Person
      </code>
      
      . Without it, only <code>
        WebSite
      </code>
      
       is emitted.
    </td>
  </tr>
  
  <tr>
    <td>
      <code>
        sameAs
      </code>
    </td>
    
    <td>
      Canonical profile URLs (GitHub, npm, X, LinkedIn), used to reconcile your identity across sources.
    </td>
  </tr>
  
  <tr>
    <td>
      <code>
        applicationCategory
      </code>
    </td>
    
    <td>
      Category of the application, defaults to <code>
        DeveloperApplication
      </code>
      
      . Only for <code>
        SoftwareApplication
      </code>
      
      .
    </td>
  </tr>
  
  <tr>
    <td>
      <code>
        operatingSystem
      </code>
    </td>
    
    <td>
      Platforms it runs on, defaults to <code>
        Web
      </code>
      
      . Only for <code>
        SoftwareApplication
      </code>
      
      .
    </td>
  </tr>
  
  <tr>
    <td>
      <code>
        price
      </code>
    </td>
    
    <td>
      Price of the application. Set <code>
        0
      </code>
      
       to advertise it as free. Only for <code>
        SoftwareApplication
      </code>
      
       and <code>
        Product
      </code>
      
      .
    </td>
  </tr>
  
  <tr>
    <td>
      <code>
        priceCurrency
      </code>
    </td>
    
    <td>
      ISO 4217 currency for <code>
        price
      </code>
      
      , defaults to <code>
        USD
      </code>
      
      .
    </td>
  </tr>
  
  <tr>
    <td>
      <code>
        organization
      </code>
    </td>
    
    <td>
      Publisher of the site, emitted as a linked <code>
        Organization
      </code>
      
      . Accepts <code>
        name
      </code>
      
      , <code>
        url
      </code>
      
      , <code>
        logo
      </code>
      
      , <code>
        sameAs
      </code>
      
      , <code>
        address
      </code>
      
       and <code>
        contactPoint
      </code>
      
      .
    </td>
  </tr>
  
  <tr>
    <td>
      <code>
        organization.parentOrganization
      </code>
    </td>
    
    <td>
      The company the publisher belongs to, nested inside the publisher <code>
        Organization
      </code>
      
      .
    </td>
  </tr>
</tbody>
</table>

<note>

Every `schemaOrg` option of the module is available in your `nuxt.config.ts`. Leave `seo.schema` out and the landing page keeps its `WebSite` and `WebPage` nodes.

</note>

### **Social sharing (OG) image**

When you share a link of your documentation on social media or some chat platforms, the link will be **unfurled**, in other terms it gives a glimpse of what someone linked (displaying a title, description, and an image). All of these are powered by the **Open Graph Protocol**.

#### Documentation pages

We're using [Nuxt OG Image](https://nuxtseo.com/docs/og-image/getting-started/introduction) under the hood to generate OG image for each documentation page based on the provided title and description. For example, the OG image for the current page is:

![og image documentation page](https://docus.dev/_og/s/c_Docs,headline_Core+Concepts,title_Configuration,description_Customize+your+Docus+documentation+from+Nuxt+application+configuration+file.,p_Ii9lbi9jb25jZXB0cy9jb25maWd1cmF0aW9uIg.png)

#### Landing page

Same as the documentation pages, the landing page uses the same OG image generator based on the provided title and description.

![og image landing page](https://docus.dev/_og/s/c_Landing,title_Write+beautiful+docs+with+Markdown,description_Ship+fast+flexible+and+SEO-optimized+documentation+with+beautiful+design+out+of+the+box.+Docus+brings+together+the+best+of+the+Nuxt+ecosystem.+Powered+by+Nuxt+UI.,p_Ii9lbiI.png)

#### Override OG image

Since Docus is a [Nuxt layer](https://nuxt.com/docs/guide/going-further/layers), you can override docs or landing page OG image by creating a file with the same name in your own `components/OgImage/` directory.

```text
components/
  OgImage/
    Docs.takumi.vue     # overrides the docs OG image
    Landing.takumi.vue  # overrides the landing OG image
```

Your component receives `title`, `description`, and `headline` (docs only) as props and can use any Tailwind CSS or inline styles supported by the [Takumi renderer](https://nuxtseo.com/docs/og-image/guides/renderers).

### Sitemap

Docus generates a sitemap at `/sitemap.xml` with [`@nuxtjs/sitemap`](https://nuxtseo.com/docs/sitemap), listing every content page. On a multilingual site it becomes a sitemap index with one sitemap per locale. Every `sitemap` option of the module is available in your `nuxt.config.ts`.

#### Excluding pages

To exclude a specific page from the sitemap, add `sitemap: false` to its frontmatter:

```md [content/draft-page.md]
---
sitemap: false
---

This page won't appear in the sitemap.
```

#### Site URL

For proper sitemap URLs, set the `NUXT_SITE_URL` environment variable:

```bash
NUXT_SITE_URL=https://your-site.com
```

## Header

Configure your documentation site's `title` or `logo`:

```ts [app.config.ts]
export default defineAppConfig({
  header: {
    title: '',
    logo: {
      light: '',
      dark: '',
      alt: '',
    },
  },
})
```

### Brand Assets

You can configure additional brand assets for your logo. Right-clicking the logo in the header opens a context menu with copy and download actions.

```ts [app.config.ts]
export default defineAppConfig({
  header: {
    title: 'My Project',
    logo: {
      light: '/logo/logo-dark.svg',
      dark: '/logo/logo-light.svg',
      alt: 'My Project Logo',
      wordmark: {
        light: '/logo/wordmark-dark.svg',
        dark: '/logo/wordmark-light.svg',
      },
      favicon: '/favicon.svg',
      brandAssetsUrl: 'https://example.com/brand',
    },
  },
})
```

<table>
<thead>
  <tr>
    <th>
      Field
    </th>
    
    <th>
      Description
    </th>
  </tr>
</thead>

<tbody>
  <tr>
    <td>
      <code>
        logo.wordmark.light
      </code>
      
       / <code>
        dark
      </code>
    </td>
    
    <td>
      Full wordmark (icon + text) for each color mode.
    </td>
  </tr>
  
  <tr>
    <td>
      <code>
        logo.display
      </code>
    </td>
    
    <td>
      Which variant to show in the header: <code>
        'logo'
      </code>
      
       (default) or <code>
        'wordmark'
      </code>
      
      .
    </td>
  </tr>
  
  <tr>
    <td>
      <code>
        logo.class
      </code>
    </td>
    
    <td>
      Additional CSS classes on the logo image (e.g. <code>
        'h-8'
      </code>
      
      ).
    </td>
  </tr>
  
  <tr>
    <td>
      <code>
        logo.favicon
      </code>
    </td>
    
    <td>
      Path to the favicon file. Defaults to <code>
        /favicon.ico
      </code>
      
      .
    </td>
  </tr>
  
  <tr>
    <td>
      <code>
        logo.brandAssetsUrl
      </code>
    </td>
    
    <td>
      Link to your brand assets page, shown as a menu item.
    </td>
  </tr>
</tbody>
</table>

When the logo is an SVG, the context menu offers **Copy logo** and **Copy wordmark** actions that copy the raw SVG with `currentColor` fills, ready to paste into Figma or any design tool. For non-SVG formats (PNG, etc.), only download actions are available.

## Color Mode

By default, Docus includes a color mode toggle in the header and footer, allowing users to switch between light and dark modes.

If your documentation only uses one theme, you can force it by setting the `colorMode` option:

```ts [app.config.ts]
export default defineAppConfig({
  docus: {
    colorMode: 'dark'
  }
})
```

<table>
<thead>
  <tr>
    <th>
      Value
    </th>
    
    <th>
      Behavior
    </th>
  </tr>
</thead>

<tbody>
  <tr>
    <td>
      <code>
        ''
      </code>
      
       (default)
    </td>
    
    <td>
      System preference with toggle button
    </td>
  </tr>
  
  <tr>
    <td>
      <code>
        'light'
      </code>
    </td>
    
    <td>
      Forces light mode, hides toggle
    </td>
  </tr>
  
  <tr>
    <td>
      <code>
        'dark'
      </code>
    </td>
    
    <td>
      Forces dark mode, hides toggle
    </td>
  </tr>
</tbody>
</table>

### Keyboard Shortcut

Press <kbd value="D">



</kbd>

 to toggle between light and dark mode when the color mode toggle is visible.

You can customize or disable this shortcut in `app.config.ts`:

```ts [app.config.ts]
export default defineAppConfig({
  docus: {
    shortcuts: {
      toggleColorMode: 'd', // Default
    },
  },
})
```

Set `toggleColorMode` to an empty string to disable the shortcut. See the [Assistant](https://docus.dev/en/ai/assistant#keyboard-shortcuts) page for the shortcut format (`meta_d`, `ctrl_shift_p`, etc.).

When a color mode is forced, the toggle button is hidden from the header and footer, and the color mode commands are removed from the command palette.

## Navigation

### Sub Navigation

For documentation sites with many content sections, you can enable a sub-navigation that splits your top-level content folders into sections and filters the left sidebar to show only the active section's pages.

Two display modes are available:

- **header** — renders a secondary tab bar below the header (desktop only, with a drawer on mobile)
- **aside** — renders section anchors at the top of the left sidebar (with a drawer on mobile)

```ts [app.config.ts]
export default defineAppConfig({
  navigation: {
    sub: 'header', // or 'aside'
  },
})
```

<video src="https://res.cloudinary.com/nuxt/video/upload/v1773263594/docus/subnav_idh2ae.mp4">



</video>

<note>

The tabs are automatically generated from your top-level folders in `content/`. Each folder's title and icon are read from its `.navigation.yml` file.

</note>

## Search

Docus includes built-in full-text search powered by [Nuxt UI ContentSearch](https://ui.nuxt.com/docs/components/content-search). By default, it uses client-side [Fuse.js](https://www.fusejs.io/) filtering which loads all search sections upfront.

### FTS5 Full-Text Search

You can switch to [SQLite FTS5](https://content.nuxt.com/docs/utils/use-search-collection) for faster, indexed search with built-in snippet highlighting. This builds an FTS5 index in the browser using SQLite WASM and only runs the search when a query is entered, instead of loading all sections upfront.

```ts [app.config.ts]
export default defineAppConfig({
  search: {
    fts: true
  }
})
```

<table>
<thead>
  <tr>
    <th>
      Mode
    </th>
    
    <th>
      Index
    </th>
    
    <th>
      Speed
    </th>
    
    <th>
      Typo tolerance
    </th>
    
    <th>
      Upfront payload
    </th>
  </tr>
</thead>

<tbody>
  <tr>
    <td>
      Fuse.js (default)
    </td>
    
    <td>
      In-memory JS scan
    </td>
    
    <td>
      O(n) per query
    </td>
    
    <td>
      Full fuzzy
    </td>
    
    <td>
      All sections loaded
    </td>
  </tr>
  
  <tr>
    <td>
      FTS5
    </td>
    
    <td>
      SQLite inverted index
    </td>
    
    <td>
      O(log n) lookup
    </td>
    
    <td>
      Prefix only
    </td>
    
    <td>
      None
    </td>
  </tr>
</tbody>
</table>

## Socials Links

Add your social media links in the footer using a `Record<string, string>` where the key matches an icon from [Simple Icons](https://simpleicons.org/) library.

```ts [app.config.ts]
export default defineAppConfig({
  socials: {
    x: 'https://x.com/nuxt_js',
    discord: 'https://discord.com/invite/ps2h6QT',
    nuxt: 'https://nuxt.com',
  }
})
```

## Table of Contents

You can customize the table of content on the right sidebar of each page.

```ts [app.config.ts]
export default defineAppConfig({
  toc: {
    // Rename the title of the table of contents
    title: 'On this page',
    // Add a bottom section to the table of contents
    bottom: {
      title: 'Community',
      links: [{
        icon: 'i-lucide-book-open',
        label: 'Nuxt UI docs',
        to: 'https://ui.nuxt.com/getting-started/installation/nuxt',
        target: '_blank'
      }]
    }
  }
})
```

## Locale

For single-language documentation (without the full `@nuxtjs/i18n` module), you can configure the locale through `app.config.ts`:

```ts [app.config.ts]
export default defineAppConfig({
  docus: {
    locale: 'fr', // Default: 'en'
  }
})
```

This sets the language for:

- UI component translations
- The `lang` and `dir` attributes on the `<html>` tag
- Built-in Docus interface strings

<tip to="https://docus.dev/en/concepts/internationalization">

For multi-language documentation with language switching, see the [Internationalization guide](https://docus.dev/en/concepts/internationalization).

</tip>

## GitHub Integration

Docus reads your `.git/` folder to get the `url` and `branch` of your repository to add:

- GitHub icon in the header and footer
- `Edit this page` and `Report an issue` links in the footer of each page.

You can customize the `url`, `branch` and `rootDir` of your docs application by adding the following configuration to your `app.config.ts` file:

```ts [app.config.ts]
export default defineAppConfig({
  github: {
    url: 'https://github.com/nuxt-content/docus',
    branch: 'main',
    rootDir: 'docs'
  }
})
```

If you don't want to use GitHub, you can set the `github` key to `false` to disable the GitHub integration.

```ts [app.config.ts]
export default defineAppConfig({
  github: false
})
```

<tip to="https://docus.dev/en/getting-started/studio">

Those configurations can also be handled in Studio editor, give it a try!

</tip>


## Sitemap

See the full [sitemap](https://docus.dev/sitemap.md) for all pages.