快速开始

安装

前置要求

• Node.js 版本 18.17 或更高，建议使用 LTS 版本。
• 支持 macOS、Windows 和 Linux 系统。

npm

$ npm install velite -D

pnpm

$ pnpm add velite -D

yarn

$ yarn add velite -D

bun

$ bun add velite -D

Velite 是一个 仅支持 ESM 的包

不要使用 require() 导入它，并确保最近的 package.json 包含 "type": "module"，或者将相关文件（如 velite.config.js）的文件扩展名更改为 .mjs/.mts。此外，在异步 CJS 上下文中，可以使用 await import('velite') 代替。

定义内容集合

在项目的根目录下创建一个 velite.config.js 文件来定义内容集合配置：

import { defineConfig, s } from 'velite'

// `s` 是从 Zod 扩展而来，包含一些自定义模式，
// 如果您不需要这些扩展模式，也可以从 `velite` 导入重新导出的 `z`。

export default defineConfig({
  collections: {
    posts: {
      name: 'Post', // 集合类型名称
      pattern: 'posts/**/*.md', // 内容文件的 glob 模式
      schema: s
        .object({
          title: s.string().max(99), // Zod 原始类型
          slug: s.slug('posts'), // 验证格式，在 posts 集合中唯一
          // slug: s.path(), // 从文件路径自动生成 slug
          date: s.isodate(), // 输入类日期字符串，输出 ISO 日期字符串。
          cover: s.image(), // 输入图片相对路径，输出包含模糊图片的对象。
          video: s.file().optional(), // 输入文件相对路径，输出文件公共路径。
          metadata: s.metadata(), // 提取 Markdown 的阅读时间、字数统计等。
          excerpt: s.excerpt(), // Markdown 内容的摘要
          content: s.markdown() // 将 Markdown 转换为 HTML
        })
        // 更多附加字段（计算字段）
        .transform(data => ({ ...data, permalink: `/blog/${data.slug}` }))
    },
    others: {
      // 其他集合模式选项
    }
  }
})

有关 Velite 扩展字段模式的更多信息，请参阅 Velite 模式。

TIP

配置文件支持 TypeScript、ESM 和 CommonJS。强烈建议使用 TypeScript 的全部功能来编写配置文件。

创建内容文件

将您的内容添加到 content 目录中，如下所示：

 root
+├── content
+│   ├── posts
+│   │   └── hello-world.md
+│   └── others
+│       └── other.yml
 ├── public
 ├── package.json
 └── velite.config.js

content/posts/hello-world.md

---
title: Hello world
slug: hello-world
date: 1992-02-25 13:22
cover: cover.jpg
video: video.mp4
---

Lorem ipsum dolor sit amet, consectetur adipiscing elit. Sed non risus. Suspendisse

![some image](img.png)

[link to file](plain.txt)

使用 Velite 构建内容

在终端中运行 velite 命令，Velite 将构建内容及相关文件。

npm

$ npx velite

pnpm

$ pnpm velite

yarn

$ yarn velite

bun

$ bun velite

然后您将获得以下输出：

 root
+├── .velite
+│   ├── posts.json                  # posts 集合输出
+│   ├── others.json                 # others 集合输出
+│   ├── index.d.ts                  # TypeScript 类型定义文件
+│   └── index.js                    # JavaScript 入口文件 (esm)
 ├── content
 │   ├── posts
 │   │   ├── hello-world.md
 │   │   └── other.md
 │   └── others
 │       └── other.yml
 ├── public
+│   └── static
+│       ├── cover-2a4138dh.jpg      # 来自 frontmatter 引用
+│       ├── img-2hd8f3sd.jpg        # 来自内容引用
+│       ├── plain-37d62h1s.txt      # 来自内容引用
+│       └── video-72hhd9f.mp4       # 来自 frontmatter 引用
 ├── package.json
 └── velite.config.js

TIP

如果您使用 Git 进行版本控制，建议通过将 .velite 添加到 .gitignore 来忽略该目录。这告诉 Git 忽略此目录及其中的所有文件。

echo '\n.velite' >> .gitignore

如果您有静态文件输出，还需要忽略 public/static 目录：

echo '\npublic/static' >> .gitignore

在监听模式下运行 Velite

当将 --watch 标志与 velite dev 或 velite 一起使用时，Velite 将监听内容文件，并在它们更改时自动重新构建。

npm

$ npx velite dev
[VELITE] output entry file in '.velite' in 0.68ms
[VELITE] output 1 posts, 1 others in 0.47ms
[VELITE] output 2 assets in 1.38ms
[VELITE] build finished in 84.49ms
[VELITE] watching for changes in 'content'

pnpm

$ pnpm velite dev
[VELITE] output entry file in '.velite' in 0.68ms
[VELITE] output 1 posts, 1 others in 0.47ms
[VELITE] output 2 assets in 1.38ms
[VELITE] build finished in 84.49ms
[VELITE] watching for changes in 'content'

yarn

$ yarn velite dev
[VELITE] output entry file in '.velite' in 0.68ms
[VELITE] output 1 posts, 1 others in 0.47ms
[VELITE] output 2 assets in 1.38ms
[VELITE] build finished in 84.49ms
[VELITE] watching for changes in 'content'

bun

$ bun velite dev
[VELITE] output entry file in '.velite' in 0.68ms
[VELITE] output 1 posts, 1 others in 0.47ms
[VELITE] output 2 assets in 1.38ms
[VELITE] build finished in 84.49ms
[VELITE] watching for changes in 'content'

有关定义集合的更多信息，请参阅 定义集合。

在项目中使用输出

Velite 将在 .velite 目录中生成一个 index.js 文件，您可以在项目中导入它：

import { posts } from './.velite'

console.log(posts) // => [{ title: 'Hello world', slug: 'hello-world', ... }, ...]

TIP

Velite 是框架无关的，您可以在任何您喜欢的框架或库中使用其输出。

从版本 0.2.0 开始，Velite 将按您在配置中指定的格式输出入口文件。因此您可以选择您喜欢的格式。

::>

有关使用集合的更多信息，请参阅 使用集合。