Invalid setting toc.depth.

[longmaobure]

Environment

Operating System: Windows11 Node Version: v20.19.0 Nuxt Version: 4.2.1 Builder: - User Config: experimental, devtools, compatibilityDate, modules, runtimeConfig, css, icon, vite, fonts, routeRules, app, schemaOrg, image, content Runtime Modules: '@pinia/nuxt^0.11.3', '@nuxt/eslint^1.10.0', '@nuxtjs/tailwindcss^6.14.0', '@nuxt/content^3.8.2'

Version

v3

Reproduction

https://content.nuxt.com/docs/getting-started/configuration#markdown

Description

When I set content.build.markdown.toc.depth in the configuration file of nuxt.config.ts, it didn't work as expected. I expected that when I set it, I should return the h1 tag to me, but it didn't.

Additional context

// nuxt.config.js
export default defineNuxtConfig({
  compatibilityDate: '2025-07-15',
  devtools: { enabled: true },
  app: {
    head: {
      title: '我的 Nuxt 博客',
      meta: [{ name: 'description', content: '这是一个 Nuxt4 博客示例' }]
    }
  },
  // components: [
  //   {
  //     path: '~/components/articles',
  //     pathPrefix: false
  //   }
  // ],
  // modules: ['@pinia/nuxt', '@nuxt/eslint', '@nuxtjs/tailwindcss'],
  modules: ['@pinia/nuxt', '@nuxt/eslint', '@nuxtjs/tailwindcss', '@nuxt/content'],
  css: ['@/assets/css/tailwind.css'],
  pinia: {
    storesDirs: ['./app/stores/**']
  },
  content: {
    build: {
      markdown: {
        toc: {
          depth: 1,
          searchDepth: 1
        }
      }
    },
    highlight: {
      theme: 'github-light', // 可以换 "github-light", "nord", "dracula"
      preload: ['ts', 'js', 'vue', 'json', 'html', 'css']
    }
  }
});

Logs

[farnabaz]

This is an expected behavior. By standard, H1 should only appear once in the whole page. Table of Content does not include h1 and it starts from H2.

[longmaobure]

Another problem, you can see the title attribute in body.toc, but it seems that the official document does not mention how to specify this title attribute. By looking at the source code, you can write it at the top of md using frontmatter syntax.

---
toc: 
   title: "tocTitle"
---
``` Whether this should be added to the documents;

[longmaobure]

And when debugging, I also found that the title is specified in' content.build.markdown.toc' in' nuxt.config.ts', which will use the specified value in the toc.title of all md files; Is this the expected effect?

[farnabaz]

I believe title is not part of the types for content.build.markdown.toc. This occurs because the config is passed directly to the generateTOC function in the MDC module. However, this behavior is undocumented and not intended.

Using toc.title in front matter is an expected feature historically, but it is not documented and may be removed in the next major release. These exist for backward compatibility and are likely to be deprecated. I recommend not relying on toc.title; instead, use links within the content.