Keystatic & Astro

Keystatic은 콘텐츠를 구성하고 GitHub와 동기화할 수 있는 오픈 소스 헤드리스 콘텐츠 관리 시스템입니다.

새 Astro + Keystatic 프로젝트를 처음부터 시작하는 경우 Keystatic CLI를 사용하여 몇 초 만에 새 프로젝트를 생성할 수 있습니다.

npm create @keystatic@latest

pnpm create @keystatic@latest

yarn create @keystatic

Astro 템플릿을 선택하면 배포할 준비가 됩니다!

전제 조건

서버 측 렌더링 (SSR) 및 output: 'hybrid'가 구성된 기존 Astro 프로젝트.

종속성 설치

패키지 관리자의 astro add 명령을 사용하여 Astro 프로젝트에 Markdoc (콘텐츠 항목용) 및 React (Keystatic 관리 UI 대시보드용) 통합을 모두 추가하세요.

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 통합을 추가하세요.

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 구성 파일 생성

콘텐츠 스키마를 정의하려면 Keystatic 구성 파일이 필요합니다. 또한 이 파일을 사용하면 프로젝트를 특정 GitHub 저장소에 연결할 수 있습니다 (원하는 경우).

프로젝트 루트에 keystatic.config.ts 라는 파일을 만들고 다음 코드를 추가하여 저장소 타입 (local) 및 단일 콘텐츠 컬렉션 (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.document({
          label: 'Content',
          formatting: true,
          dividers: true,
          links: true,
          images: true,
        }),
      },
    }),
  },
});

Keystatic은 이제 스키마를 기반으로 콘텐츠를 관리하도록 구성되었습니다.

Keystatic을 로컬에서 실행

Keystatic 관리 UI 대시보드를 시작하려면 Astro의 개발 서버를 시작하세요.

npm run dev

실행 중인 Keystatic 관리 UI를 확인하려면 브라우저에서 http://127.0.0.1:4321/keystatic을 방문하세요.

새 게시물 만들기

Keystatic 관리 UI 대시보드에서 ““Posts”” 컬렉션을 클릭합니다.
버튼을 이용하여 새 게시물을 작성하세요. “My First Post”라는 제목과 내용을 추가한 후 게시물을 저장하세요.
이제 이 게시물이 “Posts” 컬렉션에 표시됩니다. 이 대시보드 페이지에서 개별 게시물을 보고 편집할 수 있습니다.
Astro 프로젝트 파일을 보기 위해 돌아갑니다. 이제 이 새 게시물에 대한 src/content/posts 디렉터리에서 새로운 .mdoc 파일을 찾을 수 있습니다.
- 디렉터리src/
  - 디렉터리content/
    디렉터리posts/
    my-first-post.mdoc
코드 편집기에서 해당 파일로 이동하여 입력한 Markdown 콘텐츠를 볼 수 있는지 확인합니다. 예를 들어:
```
---
title: My First Post
---

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

Keystatic 콘텐츠 렌더링

Astro 프로젝트와 마찬가지로 Astro의 콘텐츠 컬렉션 API를 사용하여 게시물 및 컬렉션을 쿼리하고 표시하세요.

컬렉션 목록 표시하기

다음 예시에서는 개별 게시물 페이지에 대한 링크와 함께 각 게시물 제목 목록을 표시합니다.

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

쿼리, 필터링, 컬렉션 콘텐츠 표시 등에 대한 자세한 내용은 전체 콘텐츠 컬렉션 문서를 참조하세요.

Keystatic + Astro 배포

웹사이트를 배포하려면 배포 가이드를 방문하여 선호하는 호스팅 제공업체의 지침을 따르세요.

또한 프로젝트의 배포된 인스턴스에서 콘텐츠를 관리할 수 있도록 Keystatic을 GitHub에 연결하는 것이 좋습니다.

공식 자료

Keystatic 공식 가이드 확인하기
Keystatic 시작 템플릿