Keystatic 和 Astro

Keystatic 是一个开源、无头内容管理系统，允许你构建内容并将其与 GitHub 同步。

¥Keystatic is an open source, headless content-management system that allows you to structure your content and sync it with GitHub.

If you’re starting a new Astro + Keystatic project from scratch, you can use the Keystatic CLI to generate a new project in seconds:

npm create @keystatic@latest

pnpm create @keystatic@latest

yarn create @keystatic

Select the Astro template, and you’ll be ready to deploy!

先决条件

¥Prerequisites

现有的 Astro 项目配置服务器端渲染 (SSR) 和 output: 'hybrid' 或 output: 'server'。

安装依赖

¥Installing dependencies

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

¥Add both the Markdoc (for content entries) and the React (for the Keystatic Admin UI Dashboard) integrations to your Astro project, using the astro add command for your package manager.

npx astro add react markdoc

pnpm astro add react markdoc

yarn astro add react markdoc

你还需要两个 Keystatic 包：

¥You will also need two Keystatic packages:

npm install @keystatic/core @keystatic/astro

pnpm add @keystatic/core @keystatic/astro

yarn add @keystatic/core @keystatic/astro

添加 Astro 集成

¥Adding the Astro integration

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

¥Add the Astro integration from @keystatic/astro in your Astro config file:

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: 'hybrid',
})

创建 Keystatic 配置文件

¥Creating a Keystatic config file

需要 Keystatic 配置文件来定义你的内容架构。该文件还允许你将项目连接到特定的 GitHub 存储库（如果你决定这样做）。

¥A Keystatic config file is required to define your content schema. This file will also allow you to connect a project to a specific GitHub repository (if you decide to do so).

在项目的根目录中创建一个名为 keystatic.config.ts 的文件，并添加以下代码来定义存储类型 (local) 和单个内容集合 (posts)：

¥Create a file called keystatic.config.ts in the root of the project and add the following code to define both your storage type (local) and a single content collection (posts):

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',
        }),
      },
    }),
  },
});

Keystatic 现在已配置为根据你的架构管理你的内容。

¥Keystatic is now configured to manage your content based on your schema.

本地运行 Keystatic

¥Running Keystatic locally

要启动 Keystatic 管理 UI 仪表板，请启动 Astro 的开发服务器：

¥To launch your Keystatic Admin UI dashboard, start Astro’s dev server:

npm run dev

在浏览器中访问 http://127.0.0.1:4321/keystatic 以查看 Keystatic 管理 UI 正在运行。

¥Visit http://127.0.0.1:4321/keystatic in the browser to see the Keystatic Admin UI running.

创建新帖子

¥Creating a new post

In the Keystatic Admin UI dashboard, click on the “Posts” collection.
Use the button to create a new post. Add the title “My First Post” and some content, then save the post.
This post should now be visible from your “Posts” collection. You can view and edit your individual posts from this dashboard page.
Return to view your Astro project files. You will now find a new .mdoc file inside the src/content/posts directory for this new post:
- Directorysrc/
  - Directorycontent/
    Directoryposts/
    my-first-post.mdoc
Navigate to that file in your code editor and verify that you can see the Markdown content you entered. For example:
```
---
title: My First Post
---

This is my very first post. I am **super** excited!
```

渲染关键静态内容

¥Rendering Keystatic content

使用 Astro 的 Content Collections API 进行查询并显示你的帖子和集合，就像在任何 Astro 项目中一样。

¥Use Astro’s Content Collections API to query and display your posts and collections, just as you would in any Astro project.

显示集合列表

¥Displaying a collection list

以下示例显示每个帖子标题的列表，以及指向单个帖子页面的链接。

¥The following example displays a list of each post title, with a link to an individual post page.

---
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>

显示单个条目

¥Displaying a single entry

要显示单个帖子的内容，你可以将 <Content /> 组件导入并使用到将你的内容渲染为 HTML：

¥To display content from an individual post, you can import and use the <Content /> component to render your content to 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>

有关查询、过滤、显示集合内容等的更多信息，请参阅完整内容馆藏文档。

¥For more information on querying, filtering, displaying your collections content and more, see the full content collections documentation.

部署 Keystatic + Astro

¥Deploying Keystatic + Astro

要部署你的网站，请访问我们的部署指南并按照你首选托管提供商的说明进行操作。

¥To deploy your website, visit our deployment guides and follow the instructions for your preferred hosting provider.

你可能还需要将 Keystatic 连接到 GitHub，以便可以管理项目已部署实例上的内容。

¥You’ll also probably want to connect Keystatic to GitHub so you can manage content on the deployed instance of the project.

官方资源

¥Official Resources

看看官方 Keystatic 指南
Keystatic 入门模板