Keystatic & Astro

Keystatic 是一个开源的无头内容管理系统，它允许你构建内容并实现与 GitHub 的同步。

:::tip如果你要从头开始创建一个新的 Astro + Keystatic 项目，你可以使用 Keystatic CLI 在几秒钟内生成一个新项目：

npm create @keystatic@latest

pnpm create @keystatic@latest

yarn create @keystatic

选择 Astro 模板后，你就可以开始部署你的 Keystatic + Astro 项目了！

:::

前期准备

一个已经配置了适配器的的现有 Astro 项目。

:::note如果你计划将 Keystatic 的数据与 GitHub 同步，确保你的 GitHub 账号拥有此项目仓库的 write 权限。:::

安装依赖

使用你的包管理器的 astro add 命令，将 Markdoc（用于内容条目）和 React（用于 Keystatic 管理 UI 仪表板）的集成添加到你的 Astro 项目中。

npx astro add react markdoc

pnpm astro add react markdoc

yarn astro add react markdoc

你还需要两个 Keystatic 包：

npm install @keystatic/core @keystatic/astro

pnpm add @keystatic/core @keystatic/astro

yarn add @keystatic/core @keystatic/astro

添加 Astro 集成

在你的 Astro 配置文件中添加来自 @keystatic/astro 的 Astro 集成：

// astro.config.mjs
import { defineConfig } from 'astro/config'

import react from '@astrojs/react'
import markdoc from '@astrojs/markdoc'
import keystatic from '@keystatic/astro'

// https://astro.build/config
export default defineConfig({
  integrations: [react(), markdoc(), keystatic()],
  output: 'static',
})

创建 Keystatic 配置文件

为了定义你的内容模式，你需要创建一个 Keystatic 配置文件。此外，如果你选择这样做，该文件还可以帮助你将项目与特定的 GitHub 仓库链接起来。

在项目的根目录下创建一个名为 keystatic.config.ts 的文件。在该文件中，定义你的存储类型为 local，并设置一个名为 posts 的内容集合：

// keystatic.config.ts
import { config, fields, collection } from '@keystatic/core';

export default config({
  storage: {
    kind: 'local',
  },

  collections: {
    posts: collection({
      label: 'Posts',
      slugField: 'title',
      path: 'src/content/posts/*',
      format: { contentField: 'content' },
      schema: {
        title: fields.slug({ name: { label: 'Title' } }),
        content: fields.markdoc({
          label: 'Content',
        }),
      },
    }),
  },
});

:::note[已经在使用内容集合了吗？]如果你的 Astro 项目中已经使用了内容集合，请确保更新上述 schema，使其与你现有 schema 中定义的集合完全一致。:::

现在，Keystatic 已经可以根据你的 schema 配置来管理内容了。

在本地运行 Keystatic

要启动 Keystatic 管理界面，你需要运行 Astro 的开发服务器：

 npm run dev

在浏览器中输入 http://127.0.0.1:4321/keystatic，即可查看正在运行的 Keystatic 管理界面。

创建新文章

打开 Keystatic 管理界面，然后在仪表板中选择 “Posts” 集合。
使用按钮创建一个新文章。添加标题 “我的第一篇文章” 和一些内容，然后保存文章。
这篇文章现在应该在你的 “Posts” 集合中可见。你可以从这个管理界面查看和编辑你的文章。
现在，返回你的 Astro 项目文件并查看 src/content/posts 目录，你会发现这篇新文章已经生成了一个新的 .mdoc 文件：
- 文件夹src/
  - 文件夹content/
    文件夹posts/
    my-first-post.mdoc
打开你的代码编辑器，导航到该文件，确认你可以看到你之前输入的 Markdown 内容。例如：
```
---
title: 我的第一篇文章
---

这是我非常激动的第一篇文章！
```

渲染 Keystatic 内容

你可以使用 Astro 的内容集合 API 来查询和显示你的帖子和集合，就如同在其他 Astro 项目中一样。

显示集合列表

以下示例将展示一个帖子标题列表，每个标题都会链接到对应的帖子页面。

---
import { getCollection } from 'astro:content'

const posts = await getCollection('posts')
---
<ul>
  {posts.map(post => (
    <li>
      <a href={`/posts/${post.slug}`}>{post.data.title}</a>
    </li>
  ))}
</ul>

显示单个条目

要展示单个帖子的内容，你可以引入并使用 <Content /> 组件，这样可以方便地将内容渲染成 HTML。

---
import { getEntry } from 'astro:content'

const post = await getEntry('posts', 'my-first-post')
const { Content } = await post.render()
---

<main>
  <h1>{post.data.title}</h1>
  <Content />
</main>