配置

当从命令行运行 velite 时，Velite 会自动尝试在项目根目录中解析名为 velite.config.js 的配置文件（同时支持其他 JS 和 TS 扩展名）。

Velite 配置文件

Velite 使用 velite.config.js 作为配置文件。您可以在项目的根目录中创建它。

// velite.config.js
export default {
  // ...
}

TIP

配置文件支持 TypeScript、ESM 和 CommonJS。强烈推荐利用 TypeScript 的全部功能来编写配置文件。

类型化配置

为了获得更好的类型支持，Velite 提供了一个 defineConfig 恒等函数来定义配置文件的类型。

import { defineConfig } from 'velite'

export default defineConfig({
  // ...
})

此外，Velite 还提供了一个 UserConfig 类型来描述配置文件类型。

/** @type {import('velite').UserConfig} */
export default {
  // ...
}

import type { UserConfig } from 'velite'

const config: UserConfig = {
  // ...
}

export default config

TIP

推荐使用 defineConfig 恒等函数来定义配置文件类型，因为它能提供更好的类型推断。

以及其他辅助定义配置文件类型的恒等函数：

• defineCollection: 定义集合选项
• defineLoader: 定义文件加载器

root

• 类型: string
• 默认值: 'content'

内容文件的根目录，相对于解析后的配置文件路径。

strict

• 类型: boolean
• 默认值: false

如果为 true，则在任何模式验证失败时抛出错误并终止进程。否则，会记录警告但不会终止进程。

output

• 类型: object

输出配置。

output.data

• 类型: string
• 默认值: '.velite'

数据文件的输出目录，相对于解析后的配置文件路径。

output.assets

• 类型: string
• 默认值: 'public/static'

静态资源的目录，相对于解析后的配置文件路径。此目录应由应用程序提供静态服务。

output.base

• 类型: '/' | `/${string}/` | `.${string}/` | `${string}:${string}/`
• 默认值: '/static/'

资源的公共基础路径。此选项用于生成资源 URL。它应与应用程序的 base 选项相同并以斜杠结尾。

output.name

• 类型: string
• 默认值: '[name]-[hash:8].[ext]'

此选项决定每个输出资源的名称。资源将被写入 output.assets 选项指定的目录。您可以使用 [name]、[hash] 和 [ext] 模板字符串并指定长度。

output.clean

• 类型: boolean
• 默认值: false

是否在构建前清理输出目录。

output.format

• 类型: 'esm' | 'cjs'
• 默认值: 'esm'

入口文件的输出格式。

collections

• 类型: { [name: string]: Collection }

集合定义。

collections[name].name

• 类型: string

集合的名称。用于为集合生成类型名称。

const posts = defineCollection({
  name: 'Post'
})

类型名称通常是单数名词，但可以是任何有效的 TypeScript 标识符。

collections[name].pattern

• 类型: string

集合文件的 glob 模式，基于 root。

const posts = defineCollection({
  pattern: 'posts/*.md'
})

collections[name].single

• 类型: boolean
• 默认值: false

集合是否为单文件。如果为 true，则集合将被视为单个文件，输出数据将是一个对象而不是数组。

const site = defineCollection({
  pattern: 'site/index.yml',
  single: true
})

collections[name].schema

• 类型: Schema，更多信息请参见 模式 Schema。

集合的模式。

const posts = defineCollection({
  schema: s.object({
    title: s.string(), // 来自 frontmatter
    description: s.string().optional(), // 来自 frontmatter
    excerpt: s.string(), // 来自 markdown 正文
    content: s.string() // 来自 markdown 正文
  })
})

loaders

• 类型: Loader[]，参见 Loader
• 默认值: []，内置加载器: 'json', 'yaml', 'matter'

文件加载器。您可以用它来加载 Velite 不支持的文件。更多信息，请参见 自定义加载器。

markdown

• 类型: MarkdownOptions，参见 MarkdownOptions

全局 Markdown 选项。

markdown.gfm

• 类型: boolean
• 默认值: true

启用 GitHub 风格 Markdown (GFM)。

markdown.removeComments

• 类型: boolean
• 默认值: true

移除 HTML 注释。

markdown.copyLinkedFiles

• 类型: boolean
• 默认值: true

将链接的文件复制到公共路径，并将其 URL 替换为公共 URL。

markdown.remarkPlugins

• 类型: PluggableList，参见 PluggableList
• 默认值: []

Remark 插件。

markdown.rehypePlugins

• 类型: PluggableList，参见 PluggableList
• 默认值: []

Rehype 插件。

mdx

• 类型: MdxOptions，参见 MdxOptions

全局 MDX 选项。

mdx.gfm

• 类型: boolean
• 默认值: true

启用 GitHub 风格 Markdown (GFM)。

mdx.removeComments

• 类型: boolean
• 默认值: true

移除 HTML 注释。

mdx.copyLinkedFiles

• 类型: boolean
• 默认值: true

将链接的文件复制到公共路径，并将其 URL 替换为公共 URL。

更多选项，请参见 MDX 编译选项。

prepare

• 类型: (data: Result<Collections>, context: Context) => Promisable<void | false>

数据准备钩子，在写入文件前执行。您可以对输出数据应用额外的处理，例如修改它们、添加缺失的数据、处理关系或将它们写入文件。如果需要，可以返回 false 来阻止默认输出到文件的操作。

export default defineConfig({
  collections: { posts, tags },
  prepare: (data, context) => {
    // 修改数据
    data.posts.push({ ... })
    data.tags.push({ ... })

    // 上下文
    const { config } = context
    // config 是从 `velite.config.js` 解析而来，包含默认值

    // 返回 false 以阻止默认输出到文件
  }
})

complete

• 类型: (data: Result<Collections>, context: Context) => Promisable<void>

构建成功钩子，在构建完成后执行。您可以在构建完成后执行任何操作，例如打印一些提示信息或部署输出文件。