Appearance

Velite 模式 ​

要在 Velite 中使用 Zod，请从 'velite' 导入 z 实用工具。这是对 Zod 库的重新导出，支持 Zod 的所有功能。

查阅 Zod 文档 获取关于 Zod 工作原理及可用功能的完整说明。

js
import { z } from 'velite'

// `z` 是 Zod 的重新导出

此外，Velite 扩展了 Zod 模式，添加了构建内容模型时一些常用功能，你可以从 'velite' 导入 s 来使用这些扩展模式。

js
import { s } from 'velite'

// `s` 在 Zod 基础上扩展了一些自定义模式，
// `s` 也包含了 zod 的所有成员，因此你可以将 `s` 当作 `z` 来使用

s.isodate() ​

string => string

将日期字符串格式化为 ISO 日期字符串。

ts
date: s.isodate()
// 情况 1. 有效的日期字符串
// '2017-01-01' => '2017-01-01T00:00:00.000Z'

// 情况 2. 有效的日期时间字符串
// '2017-01-01 10:10:10' => '2017-01-01T10:10:10.000Z'

// 情况 3. 无效的日期字符串
// 'foo bar invalid' => 报错 'Invalid date string'

s.unique(by) ​

string => string

验证集合中的值是否唯一。

ts
name: s.unique('taxonomies')
// 情况 1. 唯一值
// 'foo' => 'foo'

// 情况 2. 非唯一值（在所有通过 'taxonomies' 标识为唯一的集合中）
// 'foo' => 报错 'Already exists'

参数 ​

by: 唯一标识符 ​

  • 类型：string
  • 默认值：'global'

s.slug(by, reserved) ​

string => string

基于 s.unique()，在集合中保持唯一，不允许使用保留值，并验证 slug 格式。

ts
slug: s.slug('taxonomies', ['admin', 'login'])
// 情况 1. 唯一的 slug 值
// 'hello-world' => 'hello-world'

// 情况 2. 非唯一值（在所有通过 'taxonomies' 标识为唯一的集合中）
// 'hello-world' => 报错 'Slug already exists'

// 情况 3. 保留的 slug 值
// 'admin' => 报错 'Slug is reserved'

// 情况 4. 无效的 slug 值
// 'Hello World' => 报错 'Invalid slug'

参数 ​

by: 唯一标识符 ​

  • 类型：string
  • 默认值：'global'

reserved: 保留值 ​

  • 类型：string[]
  • 默认值：[]

s.file(options) ​

string => string

相对于此文件的文件路径，将文件复制到 config.output.assets 目录并返回公共 URL。

ts
avatar: s.file()
// 情况 1. 相对路径
// 'avatar.png' => '/static/avatar-34kjfdsi.png'

// 情况 2. 不存在的文件
// 'not-exists.png' => 报错 'File not exists'

// 情况 3. 绝对路径或完整 URL（如果允许）
// '/icon.png' => '/icon.png'
// 'https://zce.me/logo.png' => 'https://zce.me/logo.png'

参数 ​

options.allowNonRelativePath: ​

是否允许非相对路径。如果为 true，值将被直接返回；如果为 false，值将被作为相对路径处理。

  • 类型：boolean
  • 默认值：true

s.image(options) ​

string => Image

相对于此文件的图像路径，类似 s.file()，将文件复制到 config.output.assets 目录并返回 Image（包含元数据的图像对象）。

ts
avatar: s.image()
// 情况 1. 相对路径
// 'avatar.png' => {
//   src: '/static/avatar-34kjfdsi.png',
//   width: 100,
//   height: 100,
//   blurDataURL: 'data:image/png;base64,xxx',
//   blurWidth: 8,
//   blurHeight: 8
// }

// 情况 2. 不存在的文件
// 'not-exists.png' => 报错 'File not exists'

// 情况 3. 绝对路径或完整 URL（如果允许）
// '/icon.png' => { src: '/icon.png', width: 0, height: 0, blurDataURL: '', blurWidth: 0, blurHeight: 0 }
// 'https://zce.me/logo.png' => { src: 'https://zce.me/logo.png', width: 0, height: 0, blurDataURL: '', blurWidth: 0, blurHeight: 0 }

参数 ​

options.absoluteRoot: ​

绝对路径的根路径。如果提供，值将被作为绝对路径处理。

  • 类型：string
  • 默认值：undefined

类型 ​

ts
/**
 * 包含元数据和模糊图像的图像对象
 */
interface Image {
  /**
   * 图像的公共 URL
   */
  src: string
  /**
   * 图像宽度
   */
  width: number
  /**
   * 图像高度
   */
  height: number
  /**
   * 图像的模糊数据 URL
   */
  blurDataURL: string
  /**
   * 模糊图像宽度
   */
  blurWidth: number
  /**
   * 模糊图像高度
   */
  blurHeight: number
}

s.metadata() ​

string => Metadata

将输入或文档正文解析为 Markdown 内容并返回 Metadata。

目前仅支持 readingTime（阅读时间）和 wordCount（字数统计）。

ts
metadata: s.metadata()
// 文档正文 => { readingTime: 2, wordCount: 100 }

类型 ​

ts
/**
 * 文档元数据。
 */
interface Metadata {
  /**
   * 阅读时间（分钟）。
   */
  readingTime: number
  /**
   * 字数统计。
   */
  wordCount: number
}

s.excerpt(options) ​

string => string

将输入或文档正文解析为 Markdown 内容并返回摘要文本。

ts
excerpt: s.excerpt()
// 文档正文 => 摘要文本

参数 ​

options: 摘要选项 ​

options.length: ​

摘要长度。

  • 类型：number
  • 默认值：260

s.markdown(options) ​

string => string

将输入或文档正文解析为 Markdown 内容并返回 HTML 内容。有关更多信息，请参阅 Markdown 支持。

ts
content: s.markdown()
// => HTML 内容

参数 ​

options: Markdown 选项 ​

  • 类型：MarkdownOptions，参见 MarkdownOptions
  • 默认值：{ gfm: true, removeComments: true, copyLinkedFiles: true }

s.mdx(options) ​

string => string

将输入或文档正文解析为 MDX 内容并返回组件函数体。有关更多信息，请参阅 MDX 支持。

ts
code: s.mdx()
// => 函数体

参数 ​

options: MDX 选项 ​

  • 类型：MdxOptions，参见 MdxOptions
  • 默认值：{ gfm: true, removeComments: true, copyLinkedFiles: true }

s.raw() ​

string => string

返回原始文档正文。

ts
code: s.raw()
// => 原始文档正文

s.toc(options) ​

string => TocEntry[] | TocTree

将输入或文档正文解析为 Markdown 内容并返回 目录。

ts
toc: s.toc()
// 文档正文 => 目录

参数 ​

options: 目录选项 ​

  • 类型：TocOptions，参见 选项
options.original: ​

保留原始目录。

  • 类型：boolean
  • 默认值：false

类型 ​

ts
interface TocEntry {
  /**
   * 目录项标题
   */
  title: string
  /**
   * 可以用来访问内容的
   * URL
   */
  url: string
  /**
   * 嵌套项目
   */
  items: TocEntry[]
}

/**
 * 目录树
 */
export interface TocTree {
  /**
   *  目录标题后紧接着的节点索引，如果未找到标题则为 `-1`，
   *  如果未提供 `heading` 则为 `undefined`。
   */
  index?: number
  /**
   *  `heading` 之后第一个不属于其部分的节点索引，
   *  如果未找到标题则为 `-1`，如果未提供 `heading` 则为 `undefined`，
   *  如果 `heading` 和目录中第一个标题之间没有节点，则与 `index` 相同。
   */
  endIndex?: number
  /**
   *  表示生成目录的列表，如果无法创建目录（可能是因为未找到标题
   *  或未找到后续标题）则为 `undefined`。
   */
  map?: List
}

有关 Result 和 Options 的更多信息，请参阅 mdast-util-toc。

s.path(options) ​

=> string

基于文件路径获取扁平化路径。

ts
path: s.path()
// => 扁平化路径，例如：'posts/2021-01-01-hello-world'

参数 ​

options: 扁平化选项 ​

  • 类型：PathOptions
options.removeIndex: ​

从路径中移除 index。

  • 类型：boolean
  • 默认值：true

Zod 原始类型 ​

此外，所有 Zod 内置模式都可以正常使用，例如：

ts
title: s.string().mix(3).max(100)
description: s.string().optional()
featured: s.boolean().default(false)

你可以查阅 https://zod.dev 获取完整的支持文档。

定义自定义模式 ​

有关自定义模式的更多信息，请参阅 自定义模式。

Distributed under the MIT License.

© 2025 Lei, All rights reserved.