2.configuration.md

---
title: Configuration
description: Nuxt Content has many properties that can be configured to fit your needs.
---

You can configure Nuxt Content with the content property in your `nuxt.config` file.

```ts [nuxt.config.ts]
export default defineNuxtConfig({
  content: {
    // My custom configuration
  }
})
```

## `api`

- Type: `Record<string, any>`
- Default: `{ baseURL: '/api/_content' }`

Change default behaviour of Content APIs.

- `baseURL`: change the base URL of Content APIs. Default is `/api/_content`.

```ts [nuxt.config.ts]
export default defineNuxtConfig({
  content: {
    api: {
      baseURL: '/api/_my_content'
    }
  }
})
```

## `contentHead`

- Type: `boolean`
- Default: `true`

Enable content head feature. If enabled, module will automatically use `useContentHead` composable to inject content head data to your page.

## `defaultLocale`

- Type: `string`
- Default: `undefined`

Default locale for top level contents. Module will use first locale code from [`locales`](#locales) array if this option is not defined.

::callout{type="info"}
Note that in case of defining multiple locales, Module will filter content with `defaultLocale`. If you want to fetch contents of another locale, you need to use `where` option.
::

## `documentDriven`

- Type: `boolean | object`
- Default: `false`

Toggles the [document-driven mode](/document-driven/introduction).

`false` will disable the feature completely.

`true` will enable the feature with these defaults:

```ts [Document-driven defaults]
{
  // Will fetch navigation, page and surround.
  navigation: true,
  page: true,
  surround: true,
  // Will fetch `content/_theme.yml` and put it in `globals.theme` if present.
  globals: {
    theme: {
      where: {
        _id: 'content:_theme.yml'
      },
      without: ['_']
    }
  },
  // Will use `theme` global to search for a fallback `layout` key.
  layoutFallbacks: ['theme'],
  // Will inject `[...slug].vue` as the root page.
  injectPage: true
}
```

| Option            |        Type         | Description                                                    |
| ----------------- | :-----------------: | :------------------------------------------------------------- |
| `page`            |      `boolean`      | Enables the page binding, making it globally accessible.       |
| `navigation`      |      `boolean`      | Enables the navigation binding, making it globally accessible. |
| `surround`        |      `boolean`      | Enables the surround binding, making it globally accessible.   |
| `globals`         | `object \| boolean` | A list of globals to be made available globally.               |
| `layoutFallbacks` |     `string[]`      | A list of `globals` key to use to find a layout fallback.      |
| `injectPage`      |      `boolean`      | Inject `[...slug].vue` pre-configured page                     |
| `trailingSlash`   |      `boolean`      | Add a slash at the end of  `canonical` and `og:url`            |


## `markdown`

- `anchorLinks`: Control anchor link generation, by default it generates anchor links for `h2`, `h3` and `h4` heading
  - Type: `boolean | object`
  - Default: `{ depth: 4, exclude: [1] }`
  - Values:
    - `false` will disable link generation.
    - `true` will enable link generation for all headings.
    - `object` will customize the link generation.

    | Option  |    Type    | Description                                              |
    | ------- | :--------: | :------------------------------------------------------- |
    | depth   |  `number`  | Sets the maximal depth for anchor link generation.       |
    | exclude | `number[]` | A list of headings to exclude from link generation.      |
- `mdc`: Whether MDC syntax should be supported or not.
  - Type: `boolean`
  - Default: `true`
- `remarkPlugins`: A list of [remark](https://github.com/remarkjs/remark) plugins to use.
  - Type: `object`
  - Default: `{}`
  - Example
  ```ts [nuxt.config.ts]
  export default defineNuxtConfig({
    content: {
      markdown: {
        // Object syntax can be used to override default options
        remarkPlugins: {
          // Override remark-emoji options
          'remark-emoji': {
            emoticon: true
          },
          // Disable remark-gfm
          'remark-gfm': false,
          // Add remark-oembed
          'remark-oembed': {
            // Options
          }
        },
      }
    }
  })
  ```
- `rehypePlugins`: A list of  [rehype](https://github.com/remarkjs/remark-rehype) plugins to use.
  - Type: `string[]`
  - Default: `[]`
  - Example:
  ```ts [nuxt.config.ts]
  export default defineNuxtConfig({
    content: {
      markdown: {
        rehypePlugins: [
          'rehype-figure'
        ]
      }
    }
  })
  ```
- `toc`: Control behavior of Table of Contents generation.
  - Type: `object`
  - Default: `{ depth: 2, searchDepth: 2 }`
    - `depth`: Maximum heading depth to include in the table of contents.
    - `searchDepth`: Maximum depth of nested tags to search for heading.
- `tags`: Tags will be used to replace markdown components and render custom components instead of default ones.
  - Type: `object`
  ```ts [nuxt.config.ts]
  export default defineNuxtConfig({
    content: {
      markdown: {
        tags: {
          p: 'MyCustomParagraph'
        }
      }
    }
  })
  ```

## `highlight`

- Type: `false | object`

Nuxt Content uses [Shikiji](https://github.com/antfu/shikiji) to provide syntax highlighting for [`ProsePre`](/components/prose#prosepre) and [`ProseCodeInline`](/components/prose#prosecodeinline).

| Option    |                     Type                     | Description                                                                                                         |
| --------- | :------------------------------------------: | :------------------------------------------------------------------------------------------------------------------ |
| `theme`   | `ShikiTheme` or `Record<string, ShikiTheme>` | The [color theme](https://github.com/shikijs/shiki/blob/main/docs/themes.md) to use.                                |
| `preload` |                `ShikiLang[]`                 | The [preloaded languages](https://github.com/shikijs/shiki/blob/main/docs/languages.md) available for highlighting. |

- `highlight.theme`

Theme can be specified by a single string but also supports an object with multiple themes.

This option is compatible with [Color Mode module](https://color-mode.nuxtjs.org/).

If you are using multiple themes, it's recommended to always have a `default` theme specified.

```ts
export default defineNuxtConfig({
  content: {
    highlight: {
      // Theme used in all color schemes.
      theme: 'github-light'
      // OR
      theme: {
        // Default theme (same as single string)
        default: 'github-light',
        // Theme used if `html.dark`
        dark: 'github-dark',
        // Theme used if `html.sepia`
        sepia: 'monokai'
      }
    }
  }
})
```

- `highlight.preload`

By default, module preloads couple of languages for syntax highlighter: `['diff', 'json', 'js', 'ts', 'css', 'shell', 'html', 'md', 'yaml']`

If you plan to use code samples of other languages, you need to define the language in these options.

```ts
export default defineNuxtConfig({
  content: {
    highlight: {
      preload: [
        'c',
        'cpp',
        'java'
      ]
    }
  }
})
```

If you wish to add highlighting for an unsupported language, you can do so by loading the grammar file for the language.

```ts
import { readFileSync } from 'node:fs'

export default defineNuxtConfig({
  content: {
    highlight: {
      preload: [
        // Read more about shikiji languages: https://github.com/antfu/shikiji#fine-grained-bundle
        JSON.parse(
          readFileSync('./shiki/languages/gdscript.tmLanguage.json', 'utf-8'),
        ),
      ],
    },
  },
})

```

Read more about adding languages in the [Shiki documentation](https://github.com/shikijs/shiki/blob/main/docs/languages.md#adding-grammar).


## `ignores`

- Type: `string[]`
- Default: `['\\.', '-']`

List of ignore patterns to exclude content from parsing, rendering and watching.

Note that:

- patterns are converted to regular expressions
- `.` and `-` prefixed files are ignored by default

```ts [nuxt.config.ts]
export default defineNuxtConfig({
  content: {
    ignores: [
      'hidden',        // any file or folder that contains the word "hidden"
      '/hidden/',      // any folder that exactly matches the word "hidden"
      '/path/to/file', // any file path matching "/path/to/file"
      '\\.bak$',       // any file with the extension ".bak"
    ]
  }
})
```

## `locales`

- Type: `string[]`
- Default: `[]`

List of locale codes. This codes will be used to detect contents locale.

## `navigation`

- Type: `false | object`
- Default: `true`

Configure the [navigation feature](/usage/navigation).

Can be set to `false` to disable the feature completely.

| Option   |    Type    | Description                                                        |
| -------- | :--------: | :----------------------------------------------------------------- |
| `fields` | `string[]` | A list of fields to inherit from front-matter to navigation nodes. |

```ts
defineNuxtConfig({
  content: {
    navigation: {
      fields: ['author', 'publishedAt']
    }
  }
})
```

## `respectPathCase`

- Type: `boolean`
- Default: `false`

Whether to respect the case of the file path when generating the route. Defaults to `false`, which means the route will be generated in lowercase. For example, `content/en-US/foo.md` will resolve to the `en-us/foo` path. This may not be what you expect.If set to `true`, the route will be generated with the same case as the file path. `content/en-US/foo.md` will resolve to the `en-US/foo` path.

## `sources`

- Type: `Record<string, object>`
- Default: `{}`

Define different sources for contents.

Contents can be located in multiple places, in multiple directories, or in remote git repositories thanks to [`unstorage`](https://unstorage.unjs.io/).

```ts [nuxt.config.ts]
export default defineNuxtConfig({
  content: {
    sources: {
      // overwrite default source AKA `content` directory
      content: {
        driver: 'fs',
        prefix: '/docs', // All contents inside this source will be prefixed with `/docs`
        base: resolve(__dirname, 'content')
      }
      // Additional sources
      fa: {
        prefix: '/fa', // All contents inside this source will be prefixed with `/fa`
        driver: 'fs',
        // ...driverOptions
        base: resolve(__dirname, 'content-fa') // Path for source directory
      },
      github: {
        prefix: '/blog', // Prefix for routes used to query contents
        driver: 'github', // Driver used to fetch contents (view unstorage documentation)
        repo: "<owner>/<repo>",
        branch: "main",
        dir: "content", // Directory where contents are located. It could be a subdirectory of the repository.
        // Imagine you have a blog inside your content folder. You can set this option to `content/blog` with the prefix option to `/blog` to avoid conflicts with local files.
      },
    }
  }
})
```

::callout{type="info"}
It is highly recommended to prevent modifying default source. If you want to load contents from another location, consider adding an additional source.
::

## `watch`

- Type: `object | false`
- Default: `{ ws: { port: 4000, showUrl: true } }`

| Option    | Default | Description                                    |
| --------- | :-----: | :--------------------------------------------- |
| `port`    |  `4000` | Select the port used for the WebSocket server. |
| `showUrl` | `false` | Toggle URL display in dev server boot message. |


Disable content watcher and hot content reload.

The watcher is a development feature and will not be included in production.

::code-group
```ts [Enabled]
export default defineNuxtConfig({
  content: {
    watch: {
      ws: {
        port: 4000,
        showUrl: true
      }
    }
  }
})
```

```ts [Disabled]
export default defineNuxtConfig({
  content: {
    watch: false
  }
})
```
::

## `yaml`

- Type: `false | object`
- Default: `{}`

Options for yaml parser.

## `experimental`

### `search`

- Type: `boolean | undefined`{lang=ts}
- Default: `undefined`{lang=ts}

Enable search feature.

#### `indexed`

- Type: `boolean`{lang=ts}
- Default: `true`{lang=ts}

Enable indexed search. This will generate a search index file that allow faster and more performant search.

#### `ignoredTags`

- Type: `string[]`{lang=ts}
- Default: `['style', 'code']`{lang=ts}

List of tags to ignore when parsing content for the search API response. This is useful to avoid including code snippets in the search results or style that does not provide any useful information.

#### `filterQuery`

- Type: `QueryBuilderWhere`{lang=ts}
- Default: `{}`{lang=ts}

Query to ignore when parsing content for the search API response. This is useful to avoid including content that is not meant to be searchable like drafts or private content.

#### `options`

- Type: `object`{lang=ts}
- Default:

```ts
{
  fields: ['title', 'content', 'titles'],
  storeFields: ['title', 'content', 'titles'],
  searchOptions: {
    prefix: true,
    fuzzy: 0.2,
    boost: {
      title: 4,
      content: 2,
      titles: 1
    }
  }
}
```

When the indexed search is enabled, this option will automatically configure both the API endpoint and the `searchContent` composable. For simple search, you will need to pass the options to the `searchContent` composable.