컨텐츠로 건너뛰기

콘텐츠 컬렉션 API 참조

Added in: astro@2.0.0

콘텐츠 컬렉션은 src/content/에서 Markdown 또는 MDX 문서를 구성하고 쿼리하는 API를 제공합니다. 기능 및 사용 예시는 콘텐츠 컬렉션 안내서를 참조하세요.

astro:content에서 가져오기

섹션 제목: astro:content에서 가져오기
import {
z,
defineCollection,
getCollection,
getEntry,
getEntries,
reference,
} from 'astro:content';

타입: (input: CollectionConfig) => CollectionConfig

defineCollection()src/content/config.* 파일에 컬렉션을 구성하는 유틸리티입니다.

src/content/config.ts
import { z, defineCollection } from 'astro:content';
const blog = defineCollection({
type: 'content',
schema: z.object({
title: z.string(),
permalink: z.string().optional(),
}),
});
// `collections` 내보내기를 통해 정의된 컬렉션을 Astro에 노출합니다.
export const collections = { blog };

이 함수는 다음 속성을 허용합니다.

타입: 'content' | 'data'
기본값: 'content'

Added in: astro@2.5.0

type은 컬렉션에 저장된 항목의 형식을 정의하는 문자열입니다.

  • 'content' - Markdown (.md), MDX (.mdx), Markdoc (.mdoc)와 같은 콘텐츠 작성 형식
  • 'data' - JSON (.json) 또는 YAML (.yaml)과 같은 데이터 전용 형식의 경우

타입: ZodType | (context: SchemaContext) => ZodType

schema는 컬렉션에 대한 문서 프런트매터의 타입과 모양을 구성하는 선택적 Zod 객체입니다. 각 값은 Zod 유효성 검사기를 사용해야 합니다.

사용 예시는 콘텐츠 컬렉션 안내서를 참조하세요.

타입: (collection: string) => ZodEffects<ZodString, { collection, id: string } | { collection, slug: string }>

Added in: astro@2.5.0

reference() 함수는 콘텐츠 구성에서 한 컬렉션에서 다른 컬렉션으로의 관계 또는 “reference”를 정의하는 데 사용됩니다. 이는 컬렉션 이름을 전달받고 콘텐츠 프런트매터 또는 데이터 파일에 지정된 항목 식별자의 유효성을 검사합니다.

이 예시에서는 authors 컬렉션에 대한 블로그 작성자의 참조와 동일한 blog 컬렉션에 대한 관련 게시물 배열을 정의합니다.

import { defineCollection, reference, z } from 'astro:content';
const blog = defineCollection({
type: 'content',
schema: z.object({
// `id`로 `authors` 컬렉션에서 단일 저자 참조
author: reference('authors'),
// `slug`의 `blog` 컬렉션에서 관련 게시물 배열을 참조하세요.
relatedPosts: z.array(reference('blog')),
})
});
const authors = defineCollection({
type: 'data',
schema: z.object({ /* ... */ })
});
export const collections = { blog, authors };

사용 예시는 콘텐츠 컬렉션 안내서를 참조하세요.

타입: (collection: string, filter?: (entry: CollectionEntry<TCollectionName>) => boolean) => CollectionEntry<TCollectionName>[]

getCollection()은 컬렉션 이름별로 콘텐츠 컬렉션 항목 목록을 검색하는 함수입니다.

기본적으로 컬렉션의 모든 항목을 반환하고 항목 속성별로 범위를 좁힐 수 있는 선택적 filter 함수를 허용합니다. 이를 통해 data 객체를 통해 id, slug 또는 프런트매터 값을 기반으로 컬렉션의 일부 항목만 쿼리할 수 있습니다.

---
import { getCollection } from 'astro:content';
// 모든 `src/content/blog/` 항목을 가져옵니다.
const allBlogPosts = await getCollection('blog');
// 프런트매터에 `draft: true`가 포함된 게시물만 반환합니다.
const draftBlogPosts = await getCollection('blog', ({ data }) => {
return data.draft === true;
});
---

사용 예시는 콘텐츠 컬렉션 안내서를 참조하세요.

Added in: astro@2.5.0

타입:

  • (collection: string, contentSlugOrDataId: string) => CollectionEntry<TCollectionName>
  • ({ collection: string, id: string }) => CollectionEntry<TCollectionName>
  • ({ collection: string, slug: string }) => CollectionEntry<TCollectionName>

getEntry()는 컬렉션 이름과 항목 id (type: 'data' 컬렉션의 경우) 또는 항목 slug (type: 'content' 컬렉션의 경우)로 단일 컬렉션 항목을 검색하는 함수입니다. getEntry()data, body, render() 속성에 액세스하기 위해 참조된 항목을 가져오는 데에도 사용할 수 있습니다.

---
import { getEntry } from 'astro:content';
// `src/content/blog/enterprise.md` 가져오기
const enterprisePost = await getEntry('blog', 'enterprise');
// `src/content/captains/picard.yaml` 가져오기
const picardProfile = await getEntry('captains', 'picard');
// `data.captain`이 참조하는 프로필 가져오기
const enterpriseCaptainProfile = await getEntry(enterprisePost.data.captain);
---

컬렉션 항목 쿼리의 예시는 콘텐츠 컬렉션 가이드를 참조하세요.

Added in: astro@2.5.0

타입:

  • (Array<{ collection: string, id: string }>) => CollectionEntry<TCollectionName>[]
  • (Array<{ collection: string, slug: string }>) => CollectionEntry<TCollectionName>[]

getEntries()는 동일한 컬렉션에서 여러 컬렉션 항목을 검색하는 함수입니다. 이는 참조된 항목의 배열을 반환하여 관련 data, body, render() 속성에 액세스하는 데 유용합니다.

---
import { getEntries } from 'astro:content';
const enterprisePost = await getEntry('blog', 'enterprise');
// `data.relatedPosts`에 의해 참조되는 관련 게시물 가져오기
const enterpriseRelatedPosts = await getEntries(enterprisePost.data.relatedPosts);
---

타입: (collection: string, slug: string) => Promise<CollectionEntry<TCollectionName>>

getEntryBySlug()는 컬렉션 이름과 항목 slug로 단일 컬렉션 항목을 검색하는 함수입니다.

---
import { getEntryBySlug } from 'astro:content';
const enterprise = await getEntryBySlug('blog', 'enterprise');
---

사용 예시는 콘텐츠 컬렉션 가이드를 참조하세요.

타입: (collection: string, id: string) => Promise<CollectionEntry<TCollectionName>>

Added in: astro@2.5.0

getDataEntryById()는 컬렉션 이름과 항목 id로 단일 컬렉션 항목을 검색하는 함수입니다.

---
import { getDataEntryById } from 'astro:content';
const picardProfile = await getDataEntryById('captains', 'picard');
---
import type {
CollectionEntry,
CollectionKey,
ContentCollectionKey,
DataCollectionKey,
SchemaContext,
} from 'astro:content';

getCollection(), getEntry(), getEntries()를 포함한 쿼리 함수는 각각 CollectionEntry 타입의 항목을 반환합니다. 이 타입은 astro:content에서 유틸리티로 사용할 수 있습니다.

import type { CollectionEntry } from 'astro:content';

CollectionEntry는 제네릭 타입입니다. 이 타입을 쿼리하려는 컬렉션의 이름과 함께 사용하세요. 예를 들어, blog 컬렉션의 항목은 CollectionEntry<'blog'>와 같은 타입을 가질 것입니다.

CollectionEntry는 다음 값을 가지는 객체입니다.

사용 가능 대상: type: 'content'type: 'data' 컬렉션 타입 예시:

  • 콘텐츠 컬렉션: 'entry-1.md' | 'entry-2.md' | ...
  • 데이터 컬렉션: 'author-1' | 'author-2' | ...

src/content/[collection]에 상대적인 파일 경로를 사용하는 고유 ID입니다. 컬렉션 항목 파일 경로를 기반으로 가능한 모든 문자열 값을 열거합니다. type: 'content'로 정의된 컬렉션은 ID에 파일 확장자를 포함하지만 type: 'data'로 정의된 컬렉션은 포함하지 않습니다.

사용 가능 대상: type: 'content'type: 'data' 컬렉션 타입 예시: 'blog' | 'authors' | ...

항목이 위치한 src/content/ 아래의 최상위 폴더 이름입니다. 이는 스키마 및 쿼리 함수에서 컬렉션을 참조하는 데 사용되는 이름입니다.

사용 가능 대상: type: 'content'type: 'data' 컬렉션 타입: CollectionSchema<TCollectionName>

컬렉션 스키마에서 추론된 프런트매터 속성의 객체입니다 (defineCollection() 참조를 확인하세요). 스키마가 구성되지 않은 경우 기본값은 any입니다.

사용 가능 대상: type: 'content' 컬렉션 전용 타입 예시: 'entry-1' | 'entry-2' | ...

Markdown 또는 MDX 문서용 URL 지원 슬러그입니다. 파일 확장자가 없는 id가 기본값이지만 파일의 프런트매터에서 slug 속성을 설정하여 재정의할 수 있습니다.

사용 가능 대상: type: 'content' 컬렉션 전용 타입: string

Markdown 또는 MDX 문서의 컴파일되지 않은 원시 본문을 포함하는 문자열입니다.

사용 가능 대상: type: 'content' 컬렉션 전용 타입: () => Promise<RenderedEntry>

렌더링을 위해 지정된 Markdown 또는 MDX 문서를 컴파일하는 함수입니다. 이 함수는 다음 속성을 반환합니다.

---
import { getEntryBySlug } from 'astro:content';
const entry = await getEntryBySlug('blog', 'entry-1');
const { Content, headings, remarkPluginFrontmatter } = await entry.render();
---

사용 예시는 콘텐츠 컬렉션 가이드를 참조하세요.

Added in: astro@3.1.0

src/content/config.* 파일에 정의된 모든 컬렉션 이름의 문자열 유니언 타입입니다. 이 타입은 모든 컬렉션 이름을 허용하는 일반 함수를 정의할 때 유용할 수 있습니다.

import { type CollectionKey, getCollection } from 'astro:content';
async function getCollection(collection: CollectionKey) {
return getCollection(collection);
}

Added in: astro@3.1.0

src/content/config.* 파일에 정의된 type: 'content' 컬렉션의 모든 이름에 대한 문자열 유니언 타입입니다.

Added in: astro@3.1.0

src/content/config.* 파일에 정의된 type: 'data' 컬렉션의 모든 이름에 대한 문자열 유니언 타입입니다.

defineCollectionschema의 함수 모양을 위해 사용하는 context 객체입니다. 이 타입은 여러 컬렉션에 대해 재사용 가능한 스키마를 구축할 때 유용할 수 있습니다.

여기에는 다음 속성이 포함됩니다.

import type { SchemaContext } from 'astro:content';
export const imageSchema = ({ image }: SchemaContext) =>
z.object({
image: image(),
description: z.string().optional(),
});
const blog = defineCollection({
type: 'content',
schema: ({ image }) => z.object({
title: z.string(),
permalink: z.string().optional(),
image: imageSchema({ image })
}),
});
기여하기

여러분의 생각을 들려주세요!

GitHub Issue 생성

우리에게 가장 빨리 문제를 알려줄 수 있어요.

커뮤니티