入门

配置

Nuxt Content 采用合理的默认配置。

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

nuxt.config.ts
export default defineNuxtConfig({
  content: {
    // 选项
  }
})
除了通过 content.markdown 配置外，您还可以使用 Markdown 组件 (MDC) 通过 mdc 属性自定义 Markdown 元素的渲染。

build

Nuxt Content 会在构建时读取并解析所有可用内容。此选项允许您控制内容解析。

markdown

配置 markdown 解析器。

toc

toc: {
  depth: 2,
  searchDepth: 2
}

控制目录（Table of Contents）的生成行为。

取值：

  • depth：目录中包含的最大标题深度。
  • searchDepth：搜索标题时嵌套标签的最大深度。
nuxt.config.ts
export default defineNuxtConfig({
  content: {
    build: {
      markdown: {
        toc: {
          depth: 3, // 包含 h3 标题
        }
      }
    }
  }
})

remarkPlugins

remarkPlugins: {}

使用的 remark 插件列表。

nuxt.config.ts
export default defineNuxtConfig({
  content: {
    build: {
      markdown: {
        // 对象语法可用于覆盖默认选项
        remarkPlugins: {
          // 覆盖 remark-emoji 选项
          'remark-emoji': {
            options: {
              emoticon: true
            }
          },
          // 禁用 remark-gfm
          'remark-gfm': false,
          // 添加 remark-oembed
          'remark-oembed': {
            // 选项
          }
        },
      }
    }
  }
})

rehypePlugins

rehypePlugins: {}

使用的 rehype 插件列表。

nuxt.config.ts
export default defineNuxtConfig({
  content: {
    build: {
      markdown: {
        // 对象语法可用于覆盖默认选项
        rehypePlugins: {
          'rehype-figure': {

          }
        },
      }
    }
  }
})

contentHeading

contentHeading: true

将此选项设置为 false 时，禁用自动生成的 title 和 description 字段（默认从第一个 H1 标题及其后续段落中提取）。

highlight

highlight: false

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

选项类型说明
themeShikiTheme 或 Record<string, ShikiTheme>要使用的颜色主题。
langsShikiLang[]可用于高亮的加载的语言。
  • highlight.theme

主题可以是单个字符串，也支持带多个主题的对象。

此选项兼容 Color Mode 模块。

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

nuxt.config.ts
export default defineNuxtConfig({
  content: {
    build: {
      markdown: {
        highlight: {
          // 所有配色方案中使用的主题
          theme: 'github-light',
          // 或者
          theme: {
            // 默认主题（同单一字符串）
            default: 'github-light',
            // `html.dark` 时使用的主题
            dark: 'github-dark',
            // `html.sepia` 时使用的主题
            sepia: 'monokai'
          }
        }
      }
    }
  }
})
  • highlight.langs

默认情况下，模块加载了若干语言用于语法高亮：

默认
['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: [
            // 更多关于 Shiki 语言请参阅：https://shiki.style/guide/load-lang
            JSON.parse(
              readFileSync('./shiki/languages/gdscript.tmLanguage.json', 'utf-8'),
            ),
          ]
        }
      }
    }
  }
})

更多关于添加语言信息，请参阅 Shiki 文档。

pathMeta

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

pathMeta.forceLeadingSlash

如果设置为 true，路径将强制添加前置斜杠。默认值为 true。

pathMeta.slugifyOptions

内容模块使用 slugify 生成 slug，您可以通过此选项自定义 slugify 行为。

更多信息请查看 slugify options。

transformers

Nuxt Content 为每种内容类型提供特定的转换器，用于解析原始内容并准备查询和渲染。通过此选项，您可以定义自定义转换器以支持新内容类型或增强支持的内容类型功能。

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

更多关于转换器内容，请参阅 Transformers 文档。

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

如果您无法使用普通的文件存储 SQLite 数据库（例如因只读文件系统或平台限制），您可以完全在内存中运行 SQLite。Nuxt Content 会在首次查询时从生成的转储文件恢复数据库。在无服务器平台上，该数据库会在每次冷启动时重新创建；尽可能预渲染更多路由以避免重复的运行时初始化。

nuxt.config.ts
export default defineNuxtConfig({
  content: {
    database: {
      type: 'sqlite',
      filename: ':memory:'
    }
  }
})

D1

如果计划将应用部署到 Cloudflare Workers，需要使用 d1 数据库适配器。在 Cloudflare 控制面板创建 d1 绑定，并填写 bindingName 字段。

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

Postgres

如果计划使用 PostgreSQL 数据库部署应用，需要使用 postgresql 数据库适配器。

首先，确保安装 pg 包：

终端
npm i pg

然后，在 nuxt.config.ts 配置 postgresql 适配器：

nuxt.config.ts
export default defineNuxtConfig({
  content: {
    database: {
      type: 'postgresql',
      url: process.env.POSTGRES_URL,
      /* 其他 `pg` 选项 */
    }
  }
})

LibSQL

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

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

终端
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。

PGlite

如果计划使用 PGlite 数据库部署应用，需要使用 pglite 数据库适配器。

首先，确保安装 @electric-sql/pglite 包：

终端
npm i @electric-sql/pglite

然后，在 nuxt.config.ts 配置 pglite 适配器：

nuxt.config.ts
export default defineNuxtConfig({
  content: {
    database: {
      type: 'pglite',
      dataDir: '.data/content/pglite'
    }
  }
})
建议仅在开发环境使用 PGlite。

renderer

配置内容渲染器。

anchorLinks

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

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

取值：

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

alias

alias: {}

别名用于替换 markdown 组件，渲染自定义组件替代默认组件。

nuxt.config.ts
export default defineNuxtConfig({
  content: {
    renderer: {
      alias: {
        p: 'MyCustomParagraph'
      }
    }
  }
})

watch

默认
watch: {
  enabled: true
}

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

取值：

  • enabled：启用/禁用热重载。
  • port：WebSocket 服务器使用的端口。
  • showURL：切换开发服务器启动消息中是否显示 URL。

Nuxt Content 使用 listhen 提供本地开发服务器。更多信息请查阅 listhen 文档。

观察器为开发特性，生产环境不会包含。
export default defineNuxtConfig({
  content: {
    watch: {
      port: 4000,
      showURL: true
    }
  }
})
此功能仅在 Node.js v22.5.0 及以上版本可用。在较旧版本启用此选项不会生效。

安装

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

迁移

如何从 v2 迁移到 v3