介绍内容集合:Astro 2.0 中的类型安全 Markdown

作者
Ben Holmes

处理 Markdown/MDX 文件很困难。随着网站的成长,在成百上千的本地内容(博客文章、新闻通讯等)中维护一致的数据变得越来越困难。

内容是 Web 的重要组成部分,那么我们为什么会对(一语双关)不尽人意的开发者体验感到满意呢?Astro 的使命一直是帮助开发者构建快速的、以内容为中心的网站……接受这个挑战是理所当然的。

Astro 2.0 推出了内容集合 API:一种处理本地 Markdown 和 MDX 的新方式。内容集合可以帮助你开箱即用地管理本地内容,并提供内置的类型安全。这是我们迄今为止最激动人心的版本,今天你就可以尝试。

为你的 Markdown 提供 TypeScript 支持

内容集合通过将本地内容组织到项目 src/content 目录内的“集合”中来工作。这是一个特殊的目录,可以将类似的 Markdown 和 MDX 文件分组在一起(例如:blog/docs/newsletter/ 等)。

内置的查询函数在你输入时提供提示和自动补全。只需几行代码,就可以在 Astro 组件内获取内容并将其渲染为 HTML。

集合中的所有内容都是类型安全的,包括你的 frontmatter。使用可选的 schema 定义你的集合,Astro 将确保每个文件都具有正确的 frontmatter,并为你自动生成 TypeScript 类型。

const blog = defineCollection({
schema: z.object({
// Define your expected frontmatter properties
title: z.string(),
// Mark certain properties as optional
draft: z.boolean().optional(),
// Transform datestrings to full Date objects
publishDate: z.string().transform((val) => new Date(val))
// Improve SEO with descriptive warnings
description: z.string().max(160, 'Short descriptions have better SEO!')
// ...
}),
});

这种魔法要归功于 Zod,一个强大的 TypeScript 验证库。使用 Zod 富有表现力的 schema 构建器,你可以确保像 title 这样的重要属性始终存在且类型正确。当你出错时,Zod 会提供有用的错误消息,涵盖从缺失属性到重要的 SEO 建议等所有方面。

在我们的文档指南中了解更多关于内容集合的工作方式。

为每个人提供更好的错误提示

想象一下,你正在开发你的网站,突然……轰!你的开发环境因这个错误而停止。发生了什么?

如果你的回答是“某个随机文件的 frontmatter 中缺少了预期的 title”,恭喜你!你是世界上第一个 JS 通灵者。但如果你和我们大多数人一样,寻找这个 bug 可能需要查看堆栈跟踪、反复试错、一些嘈杂的 console.log 语句,以及一点点运气。

现在,让我们看看 Astro 2.0 中同样的错误。

你首先会注意到的是 Astro 2.0 重新设计的错误浮层。但更重要的是,信息变得更加详细。出错文件的确切文件名会立即显示出来。其中包含文件片段以帮助你理解问题,还有一个链接可以直接在你的代码编辑器中打开该文件。另外一个好处是,还包含了文档提示来帮助你调试问题。

开始使用内容集合

在今天发布的 Astro 2.0 中,内容集合还有很多值得探索的地方。你可以前往我们的内容集合指南开始使用,并探索我们更新的博客文档作品集入门模板,看看内容集合的实际应用。

在我们扩展内容集合功能集的同时,也欢迎你的反馈。我们感谢所有参与内容集合 RFC 的人,并邀请大家在我们新的公共路线图中提出未来的想法。


特别感谢 ContentlayerNuxt Content 在内容领域的探索和带来的启发 ♥