콘텐츠 컬렉션 API 참조

Added in: astro@2.0.0

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

`astro:content`에서 가져오기

import {
  z,
  defineCollection,
  getCollection,
  getEntry,
  getEntries,
  reference,
 } from 'astro:content';

`defineCollection()`

타입: (input: CollectionConfig) => CollectionConfig

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

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

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

`type`

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

Added in: astro@2.5.0

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

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

`schema`

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

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

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

`reference()`

타입: (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 };

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

`getCollection()`

타입: (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;
});
---

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

`getEntry()`

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

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

`getEntries()`

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

`getEntryBySlug()`

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

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

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

const enterprise = await getEntryBySlug('blog', 'enterprise');
---

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

`getDataEntryById()`

타입: (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');
---

`astro:content` 타입

import type {
  CollectionEntry,
  CollectionKey,
  ContentCollectionKey,
  DataCollectionKey,
  SchemaContext,
 } from 'astro:content';

`CollectionEntry`

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

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

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

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

`id`

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

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

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

`collection`

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

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

`data`

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

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

`slug`

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

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

`body`

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

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

`render()`

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

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

<Content /> - Astro 파일에서 문서의 내용을 렌더링하는 데 사용되는 컴포넌트입니다.
headings - Markdown 및 MDX 가져오기에 대해 생성된 제목 목록, Astro의 getHeadings() 유틸리티 미러링.
remarkPluginFrontmatter - remark 또는 rehype 플러그인이 적용된 후 수정된 frontmatter 객체. any 타입으로 설정됩니다.

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

const { Content, headings, remarkPluginFrontmatter } = await entry.render();
---

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

`CollectionKey`

Added in: astro@3.1.0

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

import { type CollectionKey, getCollection } from 'astro:content';

async function getCollection(collection: CollectionKey) {
  return getCollection(collection);
}

`ContentCollectionKey`

Added in: astro@3.1.0

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

`DataCollectionKey`

Added in: astro@3.1.0

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

`SchemaContext`

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

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

image - 콘텐츠 컬렉션에서 로컬 이미지를 사용할 수 있게 해주는 image() 스키마 도우미

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

기여하기

커뮤니티

콘텐츠 컬렉션 API 참조

`astro:content`에서 가져오기

`defineCollection()`

`type`

`schema`

`reference()`

`getCollection()`

`getEntry()`

`getEntries()`

`getEntryBySlug()`

`getDataEntryById()`

`astro:content` 타입

`CollectionEntry`

`id`

`collection`

`data`

`slug`

`body`

`render()`

`CollectionKey`

`ContentCollectionKey`

`DataCollectionKey`

`SchemaContext`

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

GitHub Issue 생성

의견 보내기

의견 보내기

콘텐츠 컬렉션 API 참조

astro:content에서 가져오기

defineCollection()

type

schema

reference()

getCollection()

getEntry()

getEntries()

getEntryBySlug()

getDataEntryById()

astro:content 타입

CollectionEntry

id

collection

data

slug

body

render()

CollectionKey

ContentCollectionKey

DataCollectionKey

SchemaContext

`astro:content`에서 가져오기

`defineCollection()`

`type`

`schema`

`reference()`

`getCollection()`

`getEntry()`

`getEntries()`

`getEntryBySlug()`

`getDataEntryById()`

`astro:content` 타입

`CollectionEntry`

`id`

`collection`

`data`

`slug`

`body`

`render()`

`CollectionKey`

`ContentCollectionKey`

`DataCollectionKey`

`SchemaContext`