콘텐츠 컬렉션

추가된 버전: astro@2.0.0

콘텐츠 컬렉션은 블로그 게시물, 제품 설명, 캐릭터 프로필, 레시피 또는 모든 구조화된 콘텐츠와 같은 콘텐츠 세트를 Astro 프로젝트에서 관리하는 가장 좋은 방법입니다. 컬렉션은 문서를 구성하고 쿼리하는 데 도움이 되며, 편집기에서 Intellisense 및 타입 체크를 가능하게 하고, 모든 콘텐츠에 대해 TypeScript 타입 안전성을 제공합니다.

Astro는 프로젝트에 로컬로 저장되어 있거나, 원격으로 호스팅되거나, 자주 업데이트되는 소스에서 실시간으로 가져오는 등 어디에서나 콘텐츠를 로드, 쿼리 및 렌더링할 수 있는 성능 좋고 확장 가능한 API를 제공합니다.

콘텐츠 컬렉션이란 무엇인가요?

콘텐츠 컬렉션은 관련된, 구조적으로 동일한 데이터의 집합입니다. 이 데이터는 하나 이상의 파일(예: 블로그 게시물의 개별 Markdown 파일 폴더, 제품 설명의 단일 JSON 파일)에 로컬로 저장되거나 데이터베이스, CMS, API 엔드포인트와 같은 원격 소스에서 가져올 수 있습니다. 컬렉션의 각 멤버를 엔트리라고 합니다.

• 디렉터리src/

  • …
• 디렉터리newsletter/ “newsletter” 컬렉션

  • week-1.md 컬렉션 엔트리
  • week-2.md 컬렉션 엔트리
  • week-3.md 컬렉션 엔트리
• 디렉터리authors/ “author” 컬렉션

  • authors.json 모든 컬렉션 엔트리를 포함하는 단일 파일

컬렉션은 엔트리의 위치와 형태에 의해 정의되며, 콘텐츠 및 관련 메타데이터를 쿼리하고 렌더링하는 편리한 방법을 제공합니다. 동일한 위치에 저장되어 있고 공통 구조를 공유하는 관련 데이터 또는 콘텐츠 그룹이 있을 때마다 컬렉션을 만들 수 있습니다.

빌드 시 또는 요청 시 가져온 데이터로 작업할 수 있도록 두 가지 유형의 콘텐츠 컬렉션을 사용할 수 있습니다. 빌드 타임 컬렉션과 라이브 업데이트 컬렉션 모두 다음을 사용합니다:

• 콘텐츠와 메타데이터가 저장된 곳에서 이를 검색하여 콘텐츠 중심 API를 통해 프로젝트에서 사용할 수 있도록 하는 필수 loader.
• 편집기에서 타입 안전성, 자동 완성 및 유효성 검사를 위해 각 엔트리의 예상 형태를 정의할 수 있는 선택적 컬렉션 schema.

프로젝트 내부 또는 파일 시스템에 로컬로 저장된 컬렉션은 Astro에서 제공하는 빌드 타임 로더 중 하나를 사용하여 Markdown, MDX, Markdoc, YAML, TOML 또는 JSON 파일에서 데이터를 가져올 수 있습니다. Astro에 콘텐츠 위치를 알려주고 데이터 형태를 정의하면, 금방 블로그나 이와 유사한 콘텐츠가 많은 정적 사이트를 만들 수 있습니다!

커뮤니티에서 제작한 로더를 사용하거나 커스텀 빌드 타임 컬렉션 로더 또는 라이브 로더를 직접 빌드하여 CMS, 데이터베이스 또는 헤드리스 결제 시스템과 같은 외부 소스에서 빌드 시 또는 요청 시 라이브로 원격 데이터를 가져올 수 있습니다.

컬렉션 유형

빌드 타임 콘텐츠 컬렉션은 빌드 시 업데이트되며 데이터는 스토리지 레이어에 저장됩니다. 이는 대부분의 콘텐츠에 대해 뛰어난 성능을 제공하지만, 실시간 주식 가격과 같이 최신 데이터의 신선도가 필요한 자주 업데이트되는 데이터 소스에는 적합하지 않을 수 있습니다.

최고의 성능과 확장성을 위해 다음 중 하나 이상이 해당되는 경우 빌드 타임 콘텐츠 컬렉션을 사용하세요:

• 성능이 중요하며 빌드 시 데이터를 프리렌더링하려는 경우.
• 데이터가 비교적 정적인 경우 (예: 블로그 게시물, 문서, 제품 설명).
• 빌드 시 최적화 및 캐싱의 이점을 누리고 싶은 경우.
• MDX를 처리하거나 이미지 최적화를 수행해야 하는 경우.
• 데이터를 한 번 가져와서 여러 빌드에서 재사용할 수 있는 경우.

빠른 시작

기본 제공되는 glob() 로더를 사용하고 로컬 Markdown 또는 MDX 블로그 게시물 컬렉션에 대한 스키마를 정의하는 예제를 통해 빠르게 시작하려면 공식 Astro 블로그 스타터 템플릿을 확인하세요.

라이브 콘텐츠 컬렉션은 빌드 시가 아닌 런타임에 데이터를 가져옵니다. 이를 통해 데이터가 변경될 때 사이트를 다시 빌드할 필요 없이 통합 API를 사용하여 CMS, API, 데이터베이스 또는 기타 소스에서 자주 업데이트되는 데이터에 액세스할 수 있습니다. 그러나 데이터는 각 요청 시 가져오고 데이터 저장소에 유지되지 않고 직접 반환되므로 성능 비용이 발생할 수 있습니다.

라이브 콘텐츠 컬렉션은 자주 변경되고 페이지가 요청될 때 최신 상태여야 하는 데이터를 위해 설계되었습니다. 다음 중 하나 이상이 해당되는 경우 사용을 고려하세요:

• 실시간 정보가 필요한 경우 (예: 사용자별 데이터, 현재 재고 수준).
• 자주 변경되는 콘텐츠에 대해 지속적인 재빌드를 피하고 싶은 경우.
• 데이터가 빈번하게 업데이트되는 경우 (예: 분 단위의 제품 재고, 가격, 가용성).
• 사용자 입력 또는 요청 매개변수를 기반으로 데이터 소스에 동적 필터를 전달해야 하는 경우.
• 편집자가 초안 콘텐츠를 즉시 확인해야 하는 CMS용 미리보기 기능을 구축하는 경우.

두 종류의 컬렉션은 동일한 프로젝트에 공존할 수 있으므로 각 개별 데이터 소스에 대해 항상 최상의 컬렉션 유형을 선택할 수 있습니다. 예를 들어, 빌드 타임 컬렉션은 제품 설명을 관리하고 라이브 컬렉션은 재고 현황을 관리할 수 있습니다.

두 유형의 컬렉션은 유사한 API(예: getCollection() 및 getLiveCollection())를 사용하므로, 어떤 것을 선택하든 컬렉션 작업이 친숙하게 느껴지며 항상 어떤 유형의 컬렉션으로 작업하고 있는지 알 수 있습니다.

가능하면 빌드 타임 콘텐츠 컬렉션을 사용하고, 콘텐츠를 실시간으로 업데이트해야 하고 성능 저하를 수용할 수 있는 경우에만 라이브 컬렉션을 사용하는 것이 좋습니다. 또한 라이브 콘텐츠 컬렉션은 빌드 타임 컬렉션에 비해 몇 가지 제한 사항이 있습니다:

• MDX 미지원: MDX는 런타임에 렌더링할 수 없습니다.
• 이미지 최적화 미지원: 이미지는 런타임에 처리할 수 없습니다.
• 성능 고려 사항: 데이터는 각 요청 시 가져옵니다 (캐시되지 않은 경우).
• 데이터 저장소 유지 미지원: 데이터는 콘텐츠 레이어 데이터 저장소에 저장되지 않습니다.

컬렉션을 생성해야 하는 경우

다음과 같은 경우 데이터를 컬렉션으로 정의하세요:

• 동일한 전체 구조를 공유하는 구성할 파일이나 데이터가 여러 개 있는 경우 (예: 모두 동일한 프런트매터 속성을 가진 Markdown으로 작성된 블로그 게시물 디렉터리).
• CMS와 같이 원격으로 저장된 기존 콘텐츠가 있고, fetch() 또는 SDK를 사용하는 대신 컬렉션 도우미 기능을 활용하고 싶은 경우.
• 빌드 시 수만 개의 관련 데이터를 가져와야 하며 대규모로 처리할 수 있는 쿼리 및 캐싱 방법이 필요한 경우.

컬렉션을 사용하면 다음과 같은 많은 이점이 있습니다:

• 개별 엔트리가 “올바른지” 또는 “완전한지” 확인하기 위해 공통 데이터 형태를 정의하여 프로덕션에서의 오류를 방지합니다.
• 페이지에서 콘텐츠를 가져오고 렌더링할 때 쿼리를 직관적으로 만들 수 있도록 설계된 콘텐츠 중심 API (예: import.meta.glob() 대신 getCollection())를 제공합니다.
• 기본 제공 로더와 콘텐츠 검색을 위한 저수준 Content Loader API를 모두 사용할 수 있습니다. 또한 여러 타사 및 커뮤니티 제작 로더를 사용할 수 있으며, 어디에서나 데이터를 가져올 수 있는 고유한 커스텀 로더를 빌드할 수 있습니다.
• 성능 및 확장성. 빌드 타임 콘텐츠 컬렉션 데이터는 빌드 간에 캐시될 수 있으며 수만 개의 콘텐츠 엔트리에 적합합니다.

컬렉션을 생성하지 말아야 할 경우

컬렉션은 동일한 속성을 공유해야 하는 여러 콘텐츠 조각이 있을 때 뛰어난 구조, 안전성 및 구성을 제공합니다.

다음과 같은 경우 컬렉션이 적합한 해결책이 아닐 수 있습니다:

• 페이지가 하나 또는 소수인 경우. 대신 src/pages/about.astro와 같이 개별 페이지 컴포넌트를 직접 만드는 것이 좋습니다.
• PDF와 같이 Astro에서 처리되지 않는 파일을 표시하는 경우. 이러한 정적 자산은 프로젝트의 public/ 디렉터리에 배치하세요.
• 데이터 소스에 콘텐츠 로더와 호환되지 않거나 제공하지 않는 자체 SDK/클라이언트 라이브러리가 있고, 이를 직접 사용하는 것을 선호하는 경우.

컬렉션을 위한 TypeScript 구성

콘텐츠 컬렉션은 TypeScript를 기반으로 편집기에서 Zod 유효성 검사, Intellisense 및 타입 체크를 제공합니다. 기본적으로 Astro는 create astro CLI 명령을 사용하여 새 프로젝트를 생성할 때 strict TypeScript 템플릿을 구성합니다. Astro의 strict 및 strictest 템플릿 모두 프로젝트에 콘텐츠 컬렉션에 필요한 TypeScript 설정을 포함하고 있습니다.

프로젝트에서 TypeScript를 작성하지 않거나 Astro의 기본 제공 템플릿을 사용하지 않기 때문에 이 설정을 base로 변경한 경우, 콘텐츠 컬렉션을 사용하려면 tsconfig.json에 다음 compilerOptions를 추가해야 합니다:

tsconfig.json

{
  "extends": "astro/tsconfigs/base",
  // `strict` 또는 `strictest`에서는 필요하지 않음
  "compilerOptions": {
    "strictNullChecks": true,
    "allowJs": true
  }
}

빌드 타임 콘텐츠 컬렉션 정의하기

모든 빌드 타임 콘텐츠 컬렉션은 defineCollection()을 사용하여 특수한 src/content.config.ts 파일(.js 및 .mjs 확장자도 지원됨)에 정의되며, 단일 컬렉션 객체가 프로젝트에서 사용하기 위해 내보내집니다.

각 개별 컬렉션은 다음을 구성합니다:

• 데이터 소스를 위한 빌드 타임 loader (필수)
• 타입 안전성을 위한 빌드 타임 schema (선택 사항이지만 적극 권장됨!)

src/content.config.ts

// 1. `astro:content`에서 유틸리티 가져오기
import { defineCollection } from 'astro:content';

// 2. 로더 가져오기
import { glob, file } from 'astro/loaders';

// 3. Zod 가져오기
import { z } from 'astro/zod';

// 4. 각 컬렉션에 대해 `loader` 및 `schema` 정의하기
const blog = defineCollection({
  loader: glob({ base: './src/content/blog', pattern: '**/*.{md,mdx}' }),
  schema: z.object({
    title: z.string(),
    description: z.string(),
    pubDate: z.coerce.date(),
    updatedDate: z.coerce.date().optional(),
  }),
});

// 5. 컬렉션을 등록하기 위해 단일 `collections` 객체 내보내기
export const collections = { blog };

그런 다음 전용 getCollection() 및 getEntry() 함수를 사용하여 콘텐츠 컬렉션 데이터를 쿼리하고 콘텐츠를 렌더링할 수 있습니다.

완전히 정적인 프리렌더링된 사이트를 위해 빌드 시 빌드 타임 컬렉션 엔트리에서 페이지 경로를 생성하도록 선택할 수 있습니다. 또는 빌드 타임 컬렉션을 온디맨드로 렌더링하여 페이지가 처음 요청될 때까지 페이지 빌드를 지연시킬 수 있습니다. 이는 페이지 수가 매우 많고(예: 수천 개 또는 수만 개) 필요한 경우에만 정적 페이지 빌드를 지연시키고 싶을 때 유용합니다.

빌드 타임 컬렉션 로더

Astro는 빌드 시 로컬 콘텐츠를 가져오기 위한 두 가지 기본 제공 로더(glob() 및 file())를 제공합니다. 프로젝트 또는 파일 시스템의 데이터 위치를 전달하면 이러한 로더가 자동으로 데이터를 처리하고 영구 데이터 저장소 콘텐츠 레이어를 업데이트합니다.

원격 데이터를 빌드 시 가져오기 위해 커스텀 로더를 구축하여 데이터를 검색하고 데이터 저장소를 업데이트할 수 있습니다. 또는 타사 또는 커뮤니티에서 게시한 로더 통합을 사용할 수 있습니다. 인기 있는 콘텐츠 관리 시스템뿐만 아니라 Obsidian vault, GitHub 저장소 또는 Bluesky 게시물과 같은 일반적인 데이터 소스를 위한 로더가 이미 여러 개 존재합니다.

glob() 로더

glob() 로더는 파일 시스템 어디에서나 Markdown, MDX, Markdoc, JSON, YAML 또는 TOML 파일 디렉터리에서 엔트리를 가져옵니다. 블로그 게시물 디렉터리와 같이 콘텐츠 엔트리를 로컬에 별도의 파일로 저장하는 경우 glob() 로더만 있으면 콘텐츠에 액세스할 수 있습니다.

이 로더는 micromatch에서 지원하는 글로브 패턴을 사용하여 일치시킬 엔트리 파일의 pattern과 파일이 위치한 base 파일 경로가 필요합니다. 각 엔트리에 대한 고유한 id는 파일 이름에서 자동으로 생성되지만 필요한 경우 커스텀 ID를 정의할 수 있습니다.

src/content.config.ts

import { defineCollection } from 'astro:content';
import { glob } from 'astro/loaders';

const blog = defineCollection({
  loader: glob({ pattern: "**/*.md", base: "./src/data/blog" }),
});

export const collections = { blog };

커스텀 ID 정의하기

Markdown, MDX, Markdoc, JSON 또는 TOML 파일과 함께 glob() 로더를 사용할 때 모든 콘텐츠 엔트리 id는 콘텐츠 파일 이름을 기반으로 URL 친화적인 형식으로 자동 생성됩니다. 이 고유한 id는 컬렉션에서 엔트리를 직접 쿼리하는 데 사용됩니다. 또한 콘텐츠에서 새 페이지와 URL을 생성할 때도 유용합니다.

파일 프런트매터 또는 JSON 파일의 데이터 객체에 고유한 slug 속성을 추가하여 단일 엔트리의 생성된 id를 재정의할 수 있습니다. 이는 다른 웹 프레임워크의 “permalink” 기능과 유사합니다.

src/blog/1.md

---
title: 블로그 게시물
slug: my-custom-id/supports/slashes
---
블로그 게시물 콘텐츠가 여기에 들어갑니다.

src/categories/1.json

{
  "title": "My Category",
  "slug": "my-custom-id/supports/slashes",
  "description": "카테고리 설명이 여기에 들어갑니다."
}

빌드 타임 컬렉션을 정의할 때 glob() 로더의 generateID() 도우미 함수에 옵션을 전달하여 id 생성 방식을 조정할 수도 있습니다. 예를 들어, 각 컬렉션 엔트리에 대해 대문자를 소문자로 변환하는 기본 동작을 되돌리고 싶을 수 있습니다:

src/content.config.ts

const authors = defineCollection({
  /* ID에서 대문자를 유지하면서 authors 디렉터리의 모든 JSON 파일을 검색합니다. */
  loader: glob({
    pattern: '**/*.json',
    base: "./src/data/authors",
    generateId: ({ entry }) => entry.replace(/\.json$/, ''),
  }),
});

file() 로더

file() 로더는 컬렉션에 정의된 단일 로컬 파일에서 여러 엔트리를 가져옵니다. file() 로더는 JSON 및 YAML 파일에서 객체의 단일 배열을 자동으로 감지하고 구문 분석하며(파일 확장자 기반), TOML 파일에서는 각 최상위 테이블을 독립적인 엔트리로 처리합니다.

src/content.config.ts

import { defineCollection } from 'astro:content';
import { file } from 'astro/loaders';

const dogs = defineCollection({
  loader: file("src/data/dogs.json"),
});

export const collections = { dogs };

파일의 각 엔트리 객체에는 엔트리를 식별하고 쿼리할 수 있도록 고유한 id 키 속성이 있어야 합니다. glob() 로더와 달리 file() 로더는 각 엔트리에 대해 ID를 자동으로 생성하지 않습니다.

엔트리를 id 속성이 있는 객체 배열로 제공하거나 고유한 id가 키인 객체 형태로 제공할 수 있습니다:

src/data/dogs.json

// 배열의 각 객체에 `id` 속성을 지정합니다.
[
  { "id": "poodle", "coat": "curly", "shedding": "low" },
  { "id": "afghan", "coat": "short", "shedding": "low" }
]

src/data/dogs.json

// 각 키가 `id`로 사용됩니다.
{
  "poodle": { "coat": "curly", "shedding": "low" },
  "afghan": { "coat": "silky", "shedding": "low" }
}

다른 데이터 형식 파싱하기

file() 로더를 사용하여 단일 JSON, YAML 및 TOML 파일을 컬렉션 엔트리로 파싱하는 기능은 내장되어 있습니다(중첩된 JSON 문서 제외). .csv와 같이 지원되지 않는 파일 유형에서 컬렉션을 로드하려면 파서 함수를 만들어야 합니다. 이 함수는 필요한 경우 비동기로 만들 수 있습니다 (예: 웹에서 파일을 가져오거나 파서가 비동기인 경우).

다음 예제는 타사 CSV 파서를 가져온 다음 file() 로더에 커스텀 parser 함수를 전달하는 방법을 보여줍니다:

src/content.config.ts

import { defineCollection } from "astro:content";
import { file } from "astro/loaders";
import { parse as parseCsv } from "csv-parse/sync";

const cats = defineCollection({
  loader: file("src/data/cats.csv", {
    parser: (text) => parseCsv(text, { columns: true, skipEmptyLines: true }),
  }),
});

중첩된 .json 문서

parser() 인수를 사용하여 중첩된 JSON 문서에서 단일 컬렉션을 로드할 수 있습니다. 예를 들어, 이 JSON 파일은 여러 컬렉션을 포함하고 있습니다:

src/data/pets.json

{"dogs": [{}], "cats": [{}]}

Astro의 기본 제공 JSON 파싱을 사용하여 각 컬렉션에 대해 file() 로더에 커스텀 parser() 함수를 전달하여 이러한 컬렉션을 분리할 수 있습니다:

src/content.config.ts

import { file } from "astro/loaders";
import { defineCollection } from "astro:content";

const dogs = defineCollection({
  loader: file("src/data/pets.json", { parser: (text) => JSON.parse(text).dogs })
});
const cats = defineCollection({
  loader: file("src/data/pets.json", { parser: (text) => JSON.parse(text).cats })
});

커스텀 빌드 타임 로더

Content Loader API를 사용하여 CMS, 데이터베이스 또는 API 엔드포인트와 같은 데이터 소스에서 원격 콘텐츠를 가져오는 커스텀 로더를 구축할 수 있습니다.

그런 다음 컬렉션 구성에서 커스텀 로더를 가져오고 정의하여 필요한 값을 전달할 수 있습니다:

src/content.config.ts

import { defineCollection } from 'astro:content';
import { myLoader } from './loader.ts';

const blog = defineCollection({
  loader: myLoader({
    url: "https://api.example.com/posts",
    apiKey: "my-secret",
  }),
});

팁

Astro 통합 디렉터리에서 커뮤니티 제작 및 타사 로더를 찾아보세요.

커스텀 로더를 사용하여 데이터를 가져오면 원격 데이터에서 자동으로 컬렉션이 생성됩니다. 이를 통해 로컬 컬렉션의 모든 이점을 누릴 수 있습니다. 여기에는 데이터를 쿼리하고 표시하기 위한 getCollection() 및 render()와 같은 컬렉션 전용 API 도우미뿐만 아니라 스키마 유효성 검사도 포함됩니다.

Astro 통합 또는 Vite 플러그인을 만드는 것과 유사하게, 다른 사람들이 자신의 프로젝트에서 사용할 수 있도록 로더를 npm 패키지로 배포할 수 있습니다.

고유한 로더를 빌드하는 방법에 대한 예제는 전체 Content Loader API를 참조하세요.

컬렉션 스키마 정의하기

스키마는 Zod 유효성 검사를 통해 컬렉션 내에서 일관된 프런트매터 또는 엔트리 데이터를 강제합니다. 스키마는 해당 데이터를 참조하거나 쿼리해야 할 때 데이터가 예측 가능한 형태로 존재함을 보장합니다. 파일이 컬렉션 스키마를 위반하는 경우 Astro는 유용한 오류를 제공하여 알려줍니다.

스키마는 콘텐츠에 대한 Astro의 자동 TypeScript 타이핑도 지원합니다. 컬렉션에 대한 스키마를 정의하면 Astro는 해당 스키마에 대한 TypeScript 인터페이스를 자동으로 생성하고 적용합니다. 그 결과 컬렉션을 쿼리할 때 속성 자동 완성 및 타입 체크를 포함한 완전한 TypeScript 지원을 받을 수 있습니다.

팁

Astro가 새 스키마 또는 업데이트된 스키마를 인식하려면 개발 서버를 다시 시작하거나 콘텐츠 레이어를 동기화 (s + enter)하여 astro:content 모듈을 정의해야 할 수 있습니다.

schema를 제공하는 것은 선택 사항이지만 적극 권장됩니다! 스키마를 사용하기로 선택한 경우 컬렉션 엔트리의 모든 프런트매터 또는 데이터 속성은 Zod 데이터 타입을 사용하여 정의해야 합니다.

src/content.config.ts

import { defineCollection } from 'astro:content';
import { z } from 'astro/zod';
import { glob, file } from 'astro/loaders';

const blog = defineCollection({
  loader: glob({ pattern: "**/*.md", base: "./src/data/blog" }),
  schema: z.object({
    title: z.string(),
    description: z.string(),
    pubDate: z.coerce.date(),
    updatedDate: z.coerce.date().optional(),
  })
});
const dogs = defineCollection({
  loader: file("src/data/dogs.json"),
  schema: z.object({
    id: z.string(),
    breed: z.string(),
    temperament: z.array(z.string()),
  }),
});

export const collections = { blog, dogs };

Zod로 데이터 타입 정의하기

Astro는 콘텐츠 스키마를 강화하기 위해 Zod를 사용합니다. Zod를 사용하면 Astro는 컬렉션 내의 모든 파일 데이터를 검증할 수 있을 뿐만 아니라 프로젝트 내부에서 콘텐츠를 쿼리할 때 자동 TypeScript 타입을 제공할 수 있습니다.

Astro에서 Zod를 사용하려면 "astro/zod"에서 z 유틸리티를 가져오세요. 이는 Zod 라이브러리의 재내보내기이며 Zod 4의 모든 기능을 지원합니다.

일반적인 데이터 타입의 치트 시트를 확인하고 Zod가 어떻게 작동하고 어떤 기능을 사용할 수 있는지 알아보려면 z 유틸리티 참조를 확인하세요.

Zod 스키마 메서드

모든 Zod 스키마 메서드 (예: .parse(), .transform())를 사용할 수 있지만 몇 가지 제한 사항이 있습니다. 특히 image().refine()을 사용하여 이미지에 대해 커스텀 유효성 검사를 수행하는 것은 지원되지 않습니다.

컬렉션 참조 정의하기

컬렉션 엔트리는 다른 관련 엔트리를 “참조”할 수도 있습니다.

reference() 함수를 사용하면 컬렉션 스키마의 속성을 다른 컬렉션의 엔트리로 정의할 수 있습니다. 예를 들어, 모든 space-shuttle 엔트리가 타입 체크, 자동 완성 및 유효성 검사를 위해 pilot 컬렉션 자체 스키마를 사용하는 pilot 속성을 포함하도록 요구할 수 있습니다.

일반적인 예는 JSON으로 저장된 재사용 가능한 작성자 프로필이나 동일한 컬렉션에 저장된 관련 게시물 URL을 참조하는 블로그 게시물입니다:

src/content.config.ts

import { defineCollection, reference } from 'astro:content';
import { glob } from 'astro/loaders';
import { z } from 'astro/zod';

const blog = defineCollection({
  loader: glob({ base: './src/content/blog', pattern: '**/*.{md,mdx}' }),
  schema: z.object({
    title: z.string(),
    // `authors` 컬렉션에서 `id`로 단일 작성자 참조
    author: reference('authors'),
    // `blog` 컬렉션에서 `id`로 관련 게시물 배열 참조
    relatedPosts: z.array(reference('blog')),
  })
});

const authors = defineCollection({
  loader: glob({ pattern: '**/*.json', base: "./src/data/authors" }),
  schema: z.object({
    name: z.string(),
    portfolio: z.url(),
  })
});

export const collections = { blog, authors };

이 예제 블로그 게시물은 관련 게시물의 id와 게시물 작성자의 id를 지정합니다:

src/content/blog/welcome.md

---
title: "내 블로그에 오신 것을 환영합니다"
author: ben-holmes # `src/data/authors/ben-holmes.json`을 참조합니다.
relatedPosts:
- about-me # `src/content/blog/about-me.md`를 참조합니다.
- my-year-in-review # `src/content/blog/my-year-in-review.md`를 참조합니다.
---

이러한 참조는 collection 키와 id 키를 포함하는 객체로 변환되어 템플릿에서 쉽게 쿼리할 수 있습니다.

빌드 타임 컬렉션 쿼리하기

Astro는 빌드 타임 컬렉션을 쿼리하고 하나 이상의 콘텐츠 엔트리를 반환하는 도우미 함수를 제공합니다.

• getCollection()은 전체 컬렉션을 가져와 엔트리 배열을 반환합니다.
• getEntry()는 컬렉션에서 단일 엔트리를 가져옵니다.

이러한 함수는 고유한 id, 모든 정의된 속성을 가진 data 객체를 포함하는 엔트리를 반환하며, Markdown, MDX 또는 Markdoc 문서의 원시 컴파일되지 않은 본문을 포함하는 body도 반환합니다.

src/pages/index.astro

---
import { getCollection, getEntry } from 'astro:content';

// 컬렉션의 모든 엔트리를 가져옵니다.
// 컬렉션 이름을 인수로 필요로 합니다.
const allBlogPosts = await getCollection('blog');

// 컬렉션에서 단일 엔트리를 가져옵니다.
// 컬렉션 이름과 `id`가 필요합니다.
const poodleData = await getEntry('dogs', 'poodle');
---

생성된 컬렉션의 정렬 순서는 비결정적이며 플랫폼에 따라 다릅니다. 즉, getCollection()을 호출하고 특정 순서(예: 날짜별로 정렬된 블로그 게시물)로 반환된 엔트리가 필요한 경우 컬렉션 엔트리를 직접 정렬해야 합니다:

src/pages/blog.astro

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

const posts = (await getCollection('blog')).sort(
  (a, b) => b.data.pubDate.valueOf() - a.data.pubDate.valueOf(),
);
---

CollectionEntry 타입에 의해 반환되는 전체 속성 목록을 확인하세요.

Astro 템플릿에서 콘텐츠 사용하기

컬렉션을 쿼리한 후에는 Astro 컴포넌트 템플릿 내부에서 직접 각 엔트리의 콘텐츠와 메타데이터에 액세스할 수 있습니다.

예를 들어, data 속성을 사용하여 엔트리의 프런트매터 정보를 표시하는 블로그 게시물 링크 목록을 만들 수 있습니다:

src/pages/index.astro

---
import { getCollection } from 'astro:content';
const posts = await getCollection('blog');
---
<h1>내 게시물</h1>
<ul>
  {posts.map(post => (
    <li><a href={`/blog/${post.id}`}>{post.data.title}</a></li>
  ))}
</ul>

본문 콘텐츠 렌더링하기

쿼리가 완료되면 astro:content의 render() 함수를 사용하여 Markdown 및 MDX 엔트리를 HTML로 렌더링할 수 있습니다. 이 함수를 호출하면 <Content /> 컴포넌트와 렌더링된 모든 헤딩 목록을 포함하여 렌더링된 HTML 콘텐츠에 액세스할 수 있습니다.

src/pages/blog/post-1.astro

---
import { getEntry, render } from 'astro:content';

const entry = await getEntry('blog', 'post-1');

const { Content } = await render(entry);
---
<h1>{entry.data.title}</h1>
<p>게시일: {entry.data.published.toDateString()}</p>
<Content />

MDX 엔트리로 작업할 때 고유한 컴포넌트를 <Content />에 전달하여 HTML 요소를 커스텀 대안으로 바꿀 수도 있습니다.

콘텐츠를 props로 전달하기

컴포넌트는 전체 컬렉션 엔트리를 prop으로 전달할 수도 있습니다.

CollectionEntry 유틸리티를 사용하여 TypeScript로 컴포넌트의 props 타입을 올바르게 지정할 수 있습니다. 이 유틸리티는 컬렉션 스키마 이름과 일치하는 문자열 인수를 취하며 해당 컬렉션 스키마의 모든 속성을 상속합니다.

src/components/BlogCard.astro

---
import type { CollectionEntry } from 'astro:content';
interface Props {
  post: CollectionEntry<'blog'>;
}

// `post`는 'blog' 컬렉션 스키마 타입과 일치합니다.
const { post } = Astro.props;
---

컬렉션 쿼리 필터링하기

getCollection()은 엔트리의 id 또는 data 속성을 기반으로 쿼리를 필터링할 수 있는 선택적 “filter” 콜백을 받습니다.

이를 사용하여 원하는 모든 콘텐츠 기준으로 필터링할 수 있습니다. 예를 들어, draft 속성으로 필터링하여 블로그에 초안 블로그 게시물이 게시되지 않도록 할 수 있습니다:

src/pages/blog.astro

---
// 예시: `draft: true`인 콘텐츠 엔트리 필터링
import { getCollection } from 'astro:content';
const publishedBlogEntries = await getCollection('blog', ({ data }) => {
  return data.draft !== true;
});
---

개발 서버를 실행할 때는 사용할 수 있지만 프로덕션에서는 빌드되지 않는 초안 페이지를 만들 수도 있습니다:

src/pages/blog.astro

---
// 예시: 프로덕션 빌드 시에만 `draft: true`인 콘텐츠 엔트리 필터링
import { getCollection } from 'astro:content';
const blogEntries = await getCollection('blog', ({ data }) => {
  return import.meta.env.PROD ? data.draft !== true : true;
});
---

필터 인수는 컬렉션 내의 중첩된 디렉터리 필터링도 지원합니다. id에는 전체 중첩 경로가 포함되므로 각 id의 시작 부분으로 필터링하여 특정 중첩 디렉터리의 항목만 반환할 수 있습니다:

src/pages/blog.astro

---
// 예시: 컬렉션의 하위 디렉터리별로 엔트리 필터링
import { getCollection } from 'astro:content';
const englishDocsEntries = await getCollection('docs', ({ id }) => {
  return id.startsWith('en/');
});
---

참조된 데이터에 액세스하기

스키마에 정의된 참조에 액세스하려면 먼저 컬렉션 엔트리를 쿼리하세요. 반환된 data 객체에서 참조를 사용할 수 있습니다 (예: entry.data.author 및 entry.data.relatedPosts).

그런 다음 반환된 값을 전달하여 getEntry() 함수(또는 여러 참조된 엔트리를 검색하려면 getEntries())를 다시 사용할 수 있습니다. 스키마의 reference() 함수는 이러한 값을 하나 이상의 collection 및 id 객체로 변환하여 관련 데이터를 쿼리하는 편리한 방법을 제공합니다.

src/pages/blog/adventures-in-space.astro

---
import { getEntry, getEntries } from 'astro:content';

// 먼저 블로그 게시물 쿼리
const blogPost = await getEntry('blog', 'Adventures in Space');

// 단일 참조 항목 검색: 블로그 게시물의 작성자
// `{collection: "authors", id: "ben-holmes"}` 쿼리와 동일
const author = await getEntry(blogPost.data.author);

// 참조된 항목의 배열 검색: 모든 관련 게시물
// `[{collection: "blog", id: "visiting-mars"}, {collection: "blog", id: "leaving-earth-for-the-first-time"}]` 쿼리와 동일
const relatedPosts = await getEntries(blogPost.data.relatedPosts);
---

<h1>{blogPost.data.title}</h1>
<p>작성자: {author.data.name}</p>

<!-- ... -->

<h2>추천 게시물:</h2>
{relatedPosts.map(post => (
  <a href={post.id}>{post.data.title}</a>
))}

콘텐츠에서 경로 생성하기

콘텐츠 컬렉션은 src/pages/ 디렉터리 외부에 저장됩니다. 즉, Astro의 파일 기반 라우팅에 의해 기본적으로 컬렉션 항목에 대한 페이지나 경로가 생성되지 않습니다.

개별 블로그 게시물과 같이 각 컬렉션 엔트리에 대해 HTML 페이지를 생성하려면 동적 경로를 수동으로 만들어야 합니다. 동적 경로는 들어오는 요청 매개변수(예: src/pages/blog/[...id].astro의 Astro.params.id)를 매핑하여 각 페이지에 대한 올바른 엔트리를 가져옵니다.

경로를 생성하는 정확한 방법은 페이지가 프리렌더링되는지(기본값) 아니면 서버에 의해 요청 시 렌더링되는지에 따라 달라집니다.

정적 출력을 위한 빌드 (기본값)

빌드 타임 컬렉션을 사용하여 정적 웹사이트(Astro의 기본 동작)를 빌드하는 경우, 빌드 중에 단일 페이지 컴포넌트(예: src/pages/[id].astro)에서 여러 페이지를 생성하려면 getStaticPaths() 함수를 사용하세요.

정적 경로 빌드를 위해 컬렉션 데이터를 사용할 수 있도록 getStaticPaths() 내부에서 getCollection()을 호출하세요. 그런 다음 각 콘텐츠 엔트리의 id 속성을 사용하여 개별 URL 경로를 생성합니다. 각 페이지는 페이지 템플릿에서 사용하기 위해 전체 컬렉션 엔트리를 prop으로 받습니다.

src/pages/posts/[id].astro

---
import { getCollection, render } from 'astro:content';
// 1. 모든 컬렉션 엔트리에 대해 새 경로 생성
export async function getStaticPaths() {
  const posts = await getCollection('blog');
  return posts.map(post => ({
    params: { id: post.id },
    props: { post },
  }));
}
// 2. 템플릿의 경우 prop에서 직접 엔트리를 가져올 수 있음
const { post } = Astro.props;
const { Content } = await render(post);
---
<h1>{post.data.title}</h1>
<Content />

이렇게 하면 blog 컬렉션의 모든 엔트리에 대해 페이지 경로가 생성됩니다. 예를 들어, src/blog/hello-world.md에 있는 엔트리는 id가 hello-world이므로 최종 URL은 /posts/hello-world/가 됩니다.

참고

커스텀 슬러그가 여러 경로 세그먼트가 있는 URL을 생성하기 위해 / 문자를 포함하는 경우, 이 동적 라우팅 페이지의 .astro 파일 이름에 나머지 매개변수(예: [...id])를 사용해야 합니다.

요청 시 온디맨드로 경로 빌드하기

온디맨드 렌더링을 위한 어댑터가 설치된 경우 요청 시 동적 페이지 경로를 생성할 수 있습니다. 먼저 요청을 검사(Astro.request 또는 Astro.params 사용)하여 온디맨드 슬러그를 찾은 다음 Astro의 콘텐츠 컬렉션 도우미 함수 중 하나를 사용하여 이를 검색합니다:

• 첫 번째 요청 시 한 번 생성되는 빌드 타임 컬렉션 페이지의 경우 getEntry().
• 각 요청 시 데이터를 (다시) 가져오는 라이브 컬렉션 페이지의 경우 getLiveEntry().

src/pages/posts/[id].astro

---
export const prerender = false; // 'server' 모드에서는 필요하지 않음

import { getEntry, render } from "astro:content";

// 1. 들어오는 서버 요청에서 슬러그 가져오기
const { id } = Astro.params;
if (id === undefined) {
  return Astro.redirect("/404");
}

// 2. 요청 슬러그를 사용하여 직접 엔트리 쿼리
const post = await getEntry("blog", id);

// 3. 엔트리가 존재하지 않는 경우 리디렉션
if (post === undefined) {
  return Astro.redirect("/404");
}

// 4. 템플릿에서 엔트리를 HTML로 렌더링
const { Content } = await render(post);
---
<h1>{post.data.title}</h1>
<Content />

팁

블로그 게시물 목록, 태그 페이지 등과 같은 블로그 기능에 대한 컬렉션에서 동적 페이지를 만드는 전체 예제를 보려면 GitHub의 블로그 튜토리얼 데모 코드의 src/pages/ 폴더를 살펴보세요!

라이브 콘텐츠 컬렉션

라이브 컬렉션은 빌드 타임 콘텐츠 컬렉션과 다른 API를 사용하지만 구성 및 도우미 함수는 친숙하게 느껴지도록 설계되었습니다.

주요 차이점은 다음과 같습니다:

1. 실행 시점: 빌드 시점이 아닌 요청 시점에 실행됩니다.
2. 구성 파일: src/content.config.ts 대신 src/live.config.ts를 사용합니다.
3. 컬렉션 정의: defineCollection() 대신 defineLiveCollection()을 사용합니다.
4. 로더 API: load 메서드 대신 loadCollection 및 loadEntry 메서드를 구현합니다.
5. 데이터 반환: 데이터를 데이터 저장소에 저장하는 대신 직접 반환합니다.
6. 사용자용 함수: getCollection()/getEntry() 대신 getLiveCollection()/getLiveEntry()를 사용합니다.

또한 라이브 컬렉션 데이터의 온디맨드 렌더링을 위해 어댑터가 구성되어 있어야 합니다.

특별한 파일 src/live.config.ts에 라이브 컬렉션을 정의하세요 (빌드 타임 컬렉션을 위한 src/content.config.ts와는 별도입니다).

각 개별 컬렉션은 다음을 구성합니다:

• 데이터 소스를 위한 라이브 loader, 선택적으로 타입 안전성을 위해 필요 (필수)
• 타입 안전성을 위한 라이브 컬렉션 schema (선택 사항)

빌드 타임 컬렉션과 달리 기본 제공 라이브 로더는 없습니다. 특정 데이터 소스에 대한 커스텀 라이브 로더를 생성하거나 라이브 컬렉션의 loader 속성에 전달할 타사 로더를 찾아야 합니다.

선택적으로 라이브 로더에 타입 안전성을 포함할 수 있습니다. 따라서 라이브 컬렉션에 대한 Zod schema 정의는 선택 사항입니다. 그러나 하나를 제공하면 라이브 로더의 타입보다 우선합니다.

src/live.config.ts

// 실시간 데이터 액세스를 위한 라이브 컬렉션 정의
import { defineLiveCollection } from 'astro:content';
import { storeLoader } from '@mystore/astro-loader';

const products = defineLiveCollection({
  loader: storeLoader({
    apiKey: process.env.STORE_API_KEY,
    endpoint: 'https://api.mystore.com/v1',
  }),
});

// 컬렉션을 등록하기 위해 단일 `collections` 객체 내보내기
export const collections = { products };

그런 다음 전용 getLiveCollection() 및 getLiveEntry() 함수를 사용하여 라이브 데이터에 액세스하고 콘텐츠를 렌더링할 수 있습니다.

빌드 타임 컬렉션과 같이 사이트를 다시 빌드할 필요 없이 각 요청 시 런타임에 데이터를 새로 가져와 라이브 컬렉션 엔트리에서 온디맨드로 페이지 경로를 생성할 수 있습니다. 이는 사이트 빌드 사이에 유지되는 성능 좋은 데이터 스토리지 레이어에 콘텐츠를 보관하는 것보다 최신의 실시간 데이터에 액세스하는 것이 더 중요할 때 유용합니다.

라이브 로더 만들기

Live Loader API를 사용하여 CMS, 데이터베이스 또는 API 엔드포인트와 같은 데이터 소스에서 요청 시 원격 콘텐츠를 새로 가져오는 커스텀 라이브 로더를 구축할 수 있습니다. 라이브 로더가 원하는 데이터 소스에서 콘텐츠 엔트리를 가져오고 반환하는 방법과 데이터 요청이 실패할 경우의 오류 처리 방법을 지정해야 합니다.

라이브 로더를 사용하여 데이터를 가져오면 원격 데이터에서 자동으로 컬렉션이 생성됩니다. 이를 통해 데이터를 쿼리하고 표시하기 위한 getLiveCollection() 및 render()와 같은 컬렉션 전용 API 도우미뿐만 아니라 유용한 오류 처리를 포함한 Astro 콘텐츠 컬렉션의 모든 이점을 누릴 수 있습니다.

팁

Astro 통합 디렉터리에서 커뮤니티 제작 및 타사 라이브 로더를 찾아보세요.

Live Loader API를 사용하여 라이브 로더를 구축하는 기본 사항을 확인하세요.

라이브 컬렉션에서 Zod 스키마 사용하기

라이브 컬렉션과 함께 Zod 스키마를 사용하여 런타임에 데이터를 검증하고 변환할 수 있습니다. 이 Zod 유효성 검사는 빌드 타임 컬렉션의 스키마와 동일한 방식으로 작동합니다.

라이브 컬렉션에 대한 스키마를 정의하면 컬렉션을 쿼리할 때 라이브 로더의 타입보다 우선합니다:

src/live.config.ts

import { defineLiveCollection } from 'astro:content';
import { z } from 'astro/zod';
import { apiLoader } from './loaders/api-loader';

const products = defineLiveCollection({
  loader: apiLoader({ endpoint: process.env.API_URL }),
  schema: z
    .object({
      id: z.string(),
      name: z.string(),
      price: z.number(),
      // API의 카테고리 형식 변환
      category: z.string().transform((str) => str.toLowerCase().replace(/\s+/g, '-')),
      // 날짜의 형식을 Date 객체로 강제 변환
      createdAt: z.coerce.date(),
    })
    .transform((data) => ({
      ...data,
      // 형식이 지정된 가격 필드 추가
      displayPrice: `$${data.price.toFixed(2)}`,
    })),
});

export const collections = { products };

라이브 컬렉션과 함께 Zod 스키마를 사용하면 유효성 검사 오류가 자동으로 캡처되어 AstroError 객체로 반환됩니다:

src/pages/store/index.astro

---
export const prerender = false; // 'server' 모드에서는 필요하지 않음

import { LiveCollectionValidationError } from 'astro/content/runtime';
import { getLiveEntry } from 'astro:content';

const { entry, error } = await getLiveEntry('products', '123');

// 유효성 검사 오류를 구체적으로 처리할 수 있음
if (LiveCollectionValidationError.is(error)) {
  console.error(error.message);
  return Astro.rewrite('/500');
}

// TypeScript는 entry.data가 로더의 타입이 아닌 Zod 스키마와 일치함을 알고 있습니다.
console.log(entry?.data.displayPrice); // 예: "$29.99"
---

Zod가 어떻게 작동하고 어떤 기능을 사용할 수 있는지에 대한 전체 문서는 Zod의 README를 참조하세요.

라이브 데이터 액세스하기

Astro는 각 요청 시 라이브 데이터에 액세스하고 하나(또는 그 이상)의 콘텐츠 엔트리를 반환하는 라이브 컬렉션 도우미 함수를 제공합니다. 이는 빌드 타임 컬렉션 대응 함수와 유사하게 사용할 수 있습니다.

• getLiveCollection()은 전체 컬렉션을 가져와 엔트리 배열을 반환합니다.
• getLiveEntry()는 컬렉션에서 단일 엔트리를 가져옵니다.

이러한 함수는 라이브 로더에서 정의된 모든 속성을 가진 data 객체와 고유한 id를 포함하는 엔트리를 반환합니다. npm 패키지로 배포된 타사 또는 커뮤니티 로더를 사용하는 경우 반환되는 데이터의 예상 형태는 해당 설명서를 확인하세요.

컬렉션 이름과 선택적 필터링 조건을 전달하여 이러한 함수를 사용하여 라이브 데이터에 액세스할 수 있습니다.

src/pages/store/[slug].astro

---
export const prerender = false; // 'server' 모드에서는 필요하지 않음

import { getLiveCollection, getLiveEntry } from 'astro:content';

// 로더별 필터 사용
const { entries: draftArticles } = await getLiveCollection('articles', {
  status: 'draft',
  author: 'john-doe',
});

// ID로 특정 제품 가져오기
const { entry: product } = await getLiveEntry('products', Astro.params.slug);
---

콘텐츠 렌더링하기

라이브 로더가 rendered 속성을 반환하는 경우, 빌드 타임 컬렉션과 동일한 방법을 사용하여 render() 함수와 <Content /> 컴포넌트를 사용하여 페이지에서 직접 콘텐츠를 렌더링할 수 있습니다.

또한 콘텐츠를 표시할 수 없을 때 404 페이지로 다시 작성하는 등 라이브 로더가 반환한 오류에 액세스할 수도 있습니다:

src/pages/store/[id].astro

---
export const prerender = false; // 'server' 모드에서는 필요하지 않음

import { getLiveEntry, render } from 'astro:content';
const { entry, error } = await getLiveEntry('articles', Astro.params.id);
if (error) {
  return Astro.rewrite('/404');
}

const { Content } = await render(entry);
---

<h1>{entry.data.title}</h1>
<Content />

오류 처리

라이브 로더는 네트워크 문제, API 오류 또는 유효성 검사 문제로 인해 실패할 수 있습니다. API는 오류 처리를 명시적으로 수행하도록 설계되었습니다.

getLiveCollection() 또는 getLiveEntry()를 호출할 때 오류는 다음 중 하나입니다:

• 로더에 의해 정의된 오류 유형 (오류를 반환한 경우)
• 엔트리를 찾을 수 없는 경우 LiveEntryNotFoundError
• 컬렉션 데이터가 예상 스키마와 일치하지 않는 경우 LiveCollectionValidationError
• 캐시 힌트가 유효하지 않은 경우 LiveCollectionCacheHintError
• 로더에서 발생한 포착되지 않은 오류와 같은 기타 오류의 경우 LiveCollectionError

런타임에 오류 유형을 확인하기 위해 instanceof를 사용할 수 있습니다:

src/pages/store/[id].astro

---
export const prerender = false; // 'server' 모드에서는 필요하지 않음

import { LiveEntryNotFoundError } from 'astro/content/runtime';
import { getLiveEntry } from 'astro:content';

const { entry, error } = await getLiveEntry('products', Astro.params.id);

if (error) {
  if (error instanceof LiveEntryNotFoundError) {
    console.error(`제품을 찾을 수 없음: ${error.message}`);
    Astro.response.status = 404;
  } else {
    console.error(`제품 로드 오류: ${error.message}`);
    return Astro.redirect('/500');
  }
}
---

편집기에서 JSON 스키마 파일 사용하기

추가된 버전: astro@4.13.0

Astro는 컬렉션에 대해 JSON 스키마 파일을 자동으로 생성하며, 이를 편집기에서 사용하여 데이터 파일에 대한 IntelliSense 및 타입 체크를 받을 수 있습니다.

JSON 스키마 파일은 프로젝트의 각 컬렉션에 대해 생성되어 .astro/collections/ 디렉터리에 출력됩니다. 예를 들어, 이름이 authors인 컬렉션과 posts인 컬렉션이 두 개 있는 경우 Astro는 .astro/collections/authors.schema.json 및 .astro/collections/posts.schema.json을 생성합니다.

JSON 파일에서 JSON 스키마 사용

JSON 파일에서 $schema 필드를 설정하여 Astro가 생성한 스키마를 수동으로 가리킬 수 있습니다. 값은 데이터 파일에서 스키마까지의 상대 파일 경로여야 합니다. 다음 예제에서 src/data/authors/에 있는 데이터 파일은 authors 컬렉션에 대해 생성된 스키마를 사용합니다:

src/data/authors/armand.json

{
  "$schema": "../../../.astro/collections/authors.schema.json",
  "name": "Armand",
  "skills": ["Astro", "Starlight"]
}

VS Code에서 JSON 파일 그룹에 대해 스키마 사용

VS Code에서는 json.schemas 설정을 사용하여 컬렉션의 모든 파일에 적용할 스키마를 구성할 수 있습니다. 다음 예제에서 src/data/authors/ 디렉터리의 모든 파일은 authors 컬렉션에 대해 생성된 스키마를 사용합니다:

{
  "json.schemas": [
    {
      "fileMatch": ["/src/data/authors/**"],
      "url": "./.astro/collections/authors.schema.json"
    }
  ]
}

VS Code의 YAML 파일에서 스키마 사용

VS Code에서는 Red Hat YAML 확장을 사용하여 YAML 파일에서 JSON 스키마를 사용하기 위한 지원을 추가할 수 있습니다. 이 확장이 설치되면 특별한 주석 구문을 사용하여 YAML 파일에서 스키마를 참조할 수 있습니다:

src/data/authors/armand.yml

# yaml-language-server: $schema=../../../.astro/collections/authors.schema.json
name: Armand
skills:
  - Astro
  - Starlight

VS Code에서 YAML 파일 그룹에 대해 스키마 사용

Red Hat YAML 확장을 사용하면 yaml.schemas 설정을 사용하여 컬렉션의 모든 YAML 파일에 적용할 스키마를 구성할 수 있습니다. 다음 예제에서 src/data/authors/ 디렉터리의 모든 YAML 파일은 authors 컬렉션에 대해 생성된 스키마를 사용합니다:

{
  "yaml.schemas": {
    "./.astro/collections/authors.schema.json": ["/src/content/authors/*.yml"]
  }
}

자세한 내용은 Red Hat YAML 확장 설명서의 “Associating schemas”를 참조하세요.