> AI coding agents: see [/llms.txt](/llms.txt) for the full documentation index. Markdown version: [/docs/manual/en/concepts/configuration.md](/docs/manual/en/concepts/configuration.md).

---
title: Configuration
description: "Customize your TockDocs documentation from the Nuxt application configuration file. "
navigation:
  icon: i-lucide-settings
seo:
  description: Customize your TockDocs documentation from Nuxt application configuration file.
  title: Configuration
---

TockDocs 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.
::

## SEO

Technical SEO is tricky and boring. TockDocs 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

TockDocs 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: 'TockDocs',
  },
})
```
::

#### 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 TockDocs documentation from the Nuxt application configuration file.'
---

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

::tip{to="/docs/manual/en/concepts/edition#frontmatter"}
For more details on front-matter, see the edition guide.
::

### **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:

:site-image{.rounded-md.w-full alt="og image documentation page" src="/_og/s/c_Docs,headline_Core+Concepts,title_Configuration,description_Customize+your+TockDocs+documentation+from+Nuxt+application+configuration+file.,p_Ii9kb2NzL21hbnVhbC9lbi9jb25jZXB0cy9jb25maWd1cmF0aW9uIg.png"}

#### Landing page

Same as the documentation pages, the landing page uses the same OG image generator based on the provided title and description. The exact route depends on the encoded page metadata, so use the generated path from your build output or inspect the rendered page source.

```text
/_og/s/c_Landing,title_Your+Site,description_Your+landing+page+description.png
```

#### Override OG image

Since TockDocs 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

TockDocs automatically generates a sitemap at `/sitemap.xml` containing all your documentation pages. This helps search engines discover and index your content.

#### 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',
      favicon: '/favicon.svg',
      brandAssetsUrl: 'https://example.com/brand',
    },
  },
})
```

| Field                 | Description                                                                                             |
| --------------------- | ------------------------------------------------------------------------------------------------------- |
| `logo.class`          | Additional CSS classes on the logo image (e.g. `'h-8'`).                                                |
| `logo.favicon`        | Path to the favicon file used in the browser tab and brand asset downloads. Defaults to `/favicon.ico`. |
| `logo.brandAssetsUrl` | Link to your brand assets page, shown as a menu item.                                                   |

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

If you use an SVG favicon, you can make it theme-aware with a `prefers-color-scheme` media query inside the SVG itself.

## Color Mode

By default, TockDocs 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({
  tockdocs: {
    colorMode: 'dark',
  },
})
```

| Value          | Behavior                             |
| -------------- | ------------------------------------ |
| `''` (default) | System preference with toggle button |
| `'light'`      | Forces light mode, hides toggle      |
| `'dark'`       | Forces dark mode, hides toggle       |

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'
  },
})
```

:sub-navigation-preview{locale="en"}

::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.
::

## 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({
  tockdocs: {
    locale: 'zh', // Default: 'en'
  },
})
```

This sets the language for:

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

::tip{to="/docs/manual/en/concepts/internationalization"}
For multi-language documentation with language switching, see the [Internationalization guide](/docs/manual/en/concepts/internationalization).
::

## GitHub Integration

TockDocs 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/taowang1993/tockdocs',
    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="/docs/manual/en/getting-started/studio"}
Those configurations can also be handled in Studio editor, give it a try!
::