配置

Nuxt Content 已经配置了合理的默认设置。

要配置内容模块并自定义其行为，你可以在你的 nuxt.config 中使用 content 属性：

nuxt.config.ts

export default defineNuxtConfig({
  content: {
    // Options
  }
})

除了通过 content.markdown 进行配置外，你还可以使用 Markdown 组件 (MDC) 通过 mdc 属性自定义 Markdown 元素的渲染。

`build`

Nuxt Content 在构建时读取并解析所有可用的内容。此选项使你可以控制内容的解析。

`markdown`

配置 Markdown 解析器。

`toc`

toc: {
  depth: 2,
  searchDepth: 2
}

type Toc = {
  depth: number
  searchDepth: number
}

控制目录生成的行为。

值：

depth：目录中包含的最大标题深度。
searchDepth：搜索标题的嵌套标签的最大深度。

nuxt.config.ts

export default defineNuxtConfig({
  content: {
    build: {
      markdown: {
        toc: {
          depth: 3, // include h3 headings
        }
      }
    }
  }
})

`remarkPlugins`

remarkPlugins 是用于扩展 Markdown 渲染功能的重要机制。它们基于 remark 生态系统，允许你插入插件以 修改、增强或转换 Markdown 的语法树（AST），从而实现：

自定义语法支持
添加注释、图表、提示框等功能
内容转换（如自动生成 slug、目录、外链图标等）

在 Nuxt Content v3 中，remarkPlugins 是用于扩展 Markdown 渲染功能的重要机制。它们基于 remark 生态系统，允许你插入插件以 修改、增强或转换 Markdown 的语法树（AST），从而实现：

自定义语法支持
添加注释、图表、提示框等功能
内容转换（如自动生成 slug、目录、外链图标等）

常见插件推荐：

插件	描述
`remark-gfm`	支持 GitHub 风格 Markdown（如表格、任务列表）
`remark-emoji`	支持 `:smile:` 语法替换为 emoji
`remark-toc`	自动生成 `[toc]` 目录
`remark-footnotes`	支持脚注 `[^1]`
`remark-math`	支持 LaTeX 数学公式
`remark-code-titles`	代码块上添加标题
`remark-images`	自动为图片加 alt/title
`remark-autolink-headings`	自动为标题生成锚点链接
`remark-slug`	为标题自动生成 id，供跳转链接使用

remarkPlugins: {}

type RemarkPlugins = Record<string, false | MarkdownPlugin>

要使用的 remark 插件列表。

nuxt.config.ts

export default defineNuxtConfig({
  content: {
    build: {
      markdown: {
        // Object syntax can be used to override default options
        remarkPlugins: {
          // Override remark-emoji options
          'remark-emoji': {
            options: {
              emoticon: true
            }
          },
          // Disable remark-gfm
          'remark-gfm': false,
          // Add remark-oembed
          'remark-oembed': {
            // Options
          }
        },
      }
    }
  }
})

`rehypePlugins`

在 Nuxt Content v3 中，rehypePlugins 是用来增强 Markdown 渲染结果的 HTML 输出阶段 的插件系统，基于 rehype。它可以用于：

给标题添加锚点链接
代码块高亮
转换 HTML 标签结构
增强可访问性（如添加 aria 属性）
插入自定义组件

常用插件说明：

插件	描述
`rehype-slug`	为所有标题 (`<h1>`~`<h6>`) 自动添加 `id`，用于生成锚点
`rehype-autolink-headings`	为有 `id` 的标题添加跳转链接图标或包装 `<a>`
`rehype-highlight`	使用 `highlight.js` 为代码块添加高亮（内置样式）
`rehype-katex`	支持数学公式（搭配 `remark-math`）
`rehype-raw`	支持原始 HTML 标签渲染（需显式允许）
`rehype-stringify`	将 HAST 转换为 HTML 字符串（已内置）

rehypePlugins: {}

type RehypePlugins = object

要使用的 rehype 插件列表。

nuxt.config.ts

export default defineNuxtConfig({
  content: {
    build: {
      markdown: {
        // Object syntax can be used to override default options
        rehypePlugins: {
          'rehype-figure': {

          }
        },
      }
    }
  }
})

`highlight`

highlight: false

type Highlight = false | object

Nuxt Content 使用 Shiki 为 ProsePre 和 ProseCode 提供语法高亮。

选项	类型	描述
`theme`	`ShikiTheme` or `Record<string, ShikiTheme>`	使用颜色主题
`langs`	`ShikiLang[]`	可用于高亮显示的已加载语言。

highlight.theme

主题可以通过单个字符串指定，但也支持包含多个主题的对象。

此选项与 Color Mode 模块兼容。

如果你使用多个主题，建议始终指定一个 default 主题。

nuxt.config.ts

export default defineNuxtConfig({
  content: {
    build: {
      markdown: {
        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.langs

默认情况下，该模块加载一些语言用于语法高亮：

Default

['json', 'js', 'ts', 'html', 'css', 'vue', 'shell', 'mdc', 'md', 'yaml']

如果你计划使用其他语言的代码示例，则需要在这些选项中定义该语言。

nuxt.config.ts

export default defineNuxtConfig({
  content: {
    build: {
      markdown: {
        highlight: {
          langs: [
            'c',
            'cpp',
            'java'
          ]
        }
      }
    }
  }
})

如果你希望为不受支持的语言添加高亮，可以通过加载该语言的语法文件来实现。

nuxt.config.ts

import { readFileSync } from 'node:fs'

export default defineNuxtConfig({
  content: {
    build: {
      markdown: {
        highlight: {
          langs: [
            // Read more about Shiki languages: https://shiki.style/guide/load-lang
            JSON.parse(
              readFileSync('./shiki/languages/gdscript.tmLanguage.json', 'utf-8'),
            ),
          ]
        }
      }
    }
  }
})

阅读更多关于在 Shiki 文档中添加语言的信息。

`pathMeta`

Content 模块使用文件路径生成 slug、默认标题和内容顺序，你可以使用 pathMeta 选项自定义此行为。

`pathMeta.forceLeadingSlash`

如果设置为 true，路径将以斜杠开头。默认值为 true。

`pathMeta.slugifyOptions`

Content 模块使用 slugify 生成 slug，你可以使用此选项自定义 slugify 的行为。

查看 slugify 选项以获取更多信息。

`transformers`

Nuxt Content 为每种内容类型都有特定的转换器，用于解析原始内容并准备好进行查询和渲染。使用此选项，你可以定义自定义转换器以支持新的内容类型或改进受支持内容类型的功能。

export default defineNuxtConfig({
  content: {
    build: {
      transformers: [
        '~/transformers/title-suffix',
      ],
    },
  },
})

import { defineTransformer } from '@nuxt/content'

export default defineTransformer({
  name: 'title-suffix',
  extensions: ['.md'],
  transform(file) {
    return {
      ...file,
      title: file.title + ' (suffix)',
    }
  },
})

`database`

默认情况下，Nuxt Content 使用本地 SQLite 数据库来存储和查询内容。如果你想使用其他数据库或者计划部署到 Cloudflare Workers，你可以修改此选项。

以下是支持的数据库适配器列表：

`SQLite`

如果你想更改默认数据库位置并将其移动到其他地方，可以使用 sqlite 适配器来实现。这是 database 选项的默认值。根据你的运行时环境，将使用不同的 sqlite 适配器（Node: better-sqlite-3, Bun: bun:sqlite）。

nuxt.config.ts

export default defineNuxtConfig({
  content: {
    database: {
      type: 'sqlite',
      filename: 'SQLITE_DB_LOCATION'
    }
  }
})

`D1`

如果你计划将应用程序部署到 Cloudflare Workers，则需要使用 d1 数据库适配器。在 Cloudflare 仪表板中创建一个 d1 绑定，并填写 bindingName 字段。

nuxt.config.ts

export default defineNuxtConfig({
  content: {
    database: {
      type: 'd1',
      bindingName: 'CF_BINDING_NAME'
    }
  }
})

`Postgres`

如果你计划使用 PostgreSQL 数据库部署应用程序，则需要使用 postgres 数据库适配器。

首先，请确保安装了 pg 包：

Terminal

npx npm i pg

然后，在你的 nuxt.config.ts 中配置 postgres 适配器：

nuxt.config.ts

export default defineNuxtConfig({
  content: {
    database: {
      type: 'postgres',
      url: process.env.POSTGRES_URL,
      /* Other options for `pg` */
    }
  }
})

`LibSQL`

如果你计划使用 LibSQL 数据库部署应用程序，则需要使用 libsql 数据库适配器。

首先，请确保安装了 @libsql/client 包：

Terminal

npx npm i @libsql/client

然后，在你的 nuxt.config.ts 中配置 libsql 适配器：

nuxt.config.ts

export default defineNuxtConfig({
  content: {
    database: {
      type: 'libsql',
      url: process.env.TURSO_DATABASE_URL,
      authToken: process.env.TURSO_AUTH_TOKEN,
    }
  }
})

最流行的 LibSQL 托管服务是 Turso。

`renderer`

配置内容渲染器。

`anchorLinks`

{ h2: true, h3: true, h4: true }

type AnchorLinks = boolean | Record<'h1' | 'h2' | 'h3' | 'h4' | 'h5' | 'h6', boolean>

控制锚点链接的生成，默认情况下为 h2、h3 和 h4 标题生成锚点链接。

值：

false：将禁用链接生成。
true：将为所有标题启用链接生成。

`alias`

alias: {}

type Alias = Record<string, string>

别名用于替换 Markdown 组件，并渲染自定义组件而不是默认组件。

nuxt.config.ts

export default defineNuxtConfig({
  content: {
    renderer: {
      alias: {
        p: 'MyCustomParagraph'
      }
    }
  }
})

`watch`

Default

watch: {
  enabled: true,
  port: 4000,
  showURL: false
}

配置开发环境中的内容热重载。

值：

enabled：启用/禁用热重载。
port：选择用于 WebSocket 服务器的端口。
showURL：切换在开发服务器启动消息中显示 URL。

Nuxt Content 使用 listhen 提供本地开发服务器。查看 listhen 文档以获取更多信息。

监视器是开发功能，不会包含在生产环境中。

export default defineNuxtConfig({
  content: {
    watch: {
      port: 4000,
      showURL: true
    }
  }
})

export default defineNuxtConfig({
  content: {
    watch: {
      enabled: false
    }
  }
})

`preview`

启用 Preview API

这是在 Nuxt Studio 上启用实时预览所必需的。

值:

dev：在开发模式下启用
api：激活预览模式并设置要链接的 API。

Enable Studio

preview: {
  api: 'https://api.nuxt.studio',
}

`experimental`

尚未稳定的实验性功能。

`experimental.nativeSqlite`

从 Node.js v22.5.0 开始，node:sqlite 模块在 Node.js 中原生可用。这使得 Nuxt Content 可以使用 SQLite 作为数据库，而无需外部包。

nuxt.config.ts

export default defineNuxtConfig({
  content: {
    experimental: { nativeSqlite: true },
  },
});

此功能仅在 Node.js v22.5.0 及更高版本中可用。在旧版本中启用此功能不会有任何作用。

安装

在你的 Nuxt 应用程序中开始使用 Nuxt Content v3。

迁移

如何从 v2 迁移到 v3