Astro에서 Markdown 사용하기

Markdown은 일반적으로 블로그 게시물 및 문서와 같이 텍스트가 많은 콘텐츠를 작성하는 데 사용됩니다. Astro에는 title, description, tags와 같은 사용자 정의 속성을 정의하기 위해 프런트매터 YAML (또는 TOML)을 포함할 수 있는 Markdown 파일에 대한 기본 지원이 포함되어 있습니다.

Astro에서는 GitHub Flavored Markdown으로 콘텐츠를 작성한 다음 .astro 컴포넌트에 이를 렌더링할 수 있습니다. 이는 콘텐츠용으로 설계된 친숙한 작성 형식과 Astro의 컴포넌트 구문 및 아키텍처의 유연성을 결합한 것입니다.

Markdown 파일 구성하기

로컬 Markdown 파일은 src/ 디렉터리 어디에나 저장할 수 있습니다. src/pages/에 위치한 Markdown 파일은 자동으로 사이트에 Markdown 페이지를 생성합니다.

Markdown 콘텐츠와 프런트매터 속성은 로컬 파일 가져오기를 통해, 또는 콘텐츠 컬렉션 헬퍼 함수로 가져온 데이터에서 쿼리하고 렌더링할 때 컴포넌트에서 사용할 수 있습니다.

파일 가져오기 vs 콘텐츠 컬렉션 쿼리

로컬 Markdown은 단일 파일의 경우 import 구문을 사용하여, 여러 파일을 한 번에 가져올 때는 Vite의 import.meta.glob()을 사용하여 .astro 컴포넌트로 가져올 수 있습니다. 이렇게 Markdown 파일에서 내보낸 데이터는 .astro 컴포넌트에서 사용할 수 있습니다.

연관된 Markdown 파일 그룹이 있는 경우 컬렉션으로 정의하는 것을 고려해 보세요. 이렇게 하면 파일 시스템의 어느 곳에나 또는 원격으로 Markdown 파일을 저장할 수 있는 등 여러 가지 이점이 있습니다.

컬렉션은 파일 가져오기 대신 Markdown 콘텐츠를 쿼리하고 렌더링하기 위해 콘텐츠별 최적화된 API를 사용합니다. 컬렉션은 블로그 게시물이나 제품 항목과 같이 동일한 구조를 공유하는 데이터 집합을 위한 것입니다. 스키마에서 해당 형태를 정의하면 편집기에서 유효성 검사, 타입 안전, 인텔리센스를 사용할 수 있습니다.

파일 가져오기 대신 콘텐츠 컬렉션을 사용하는 경우에 대해 자세히 알아보세요.

동적 JSX 유사 표현식

Markdown 파일을 가져오거나 쿼리한 후에는 프런트매터 데이터와 본문 콘텐츠를 포함하는 .astro 컴포넌트에 동적 HTML 템플릿을 작성할 수 있습니다.

---
title: 'The greatest post of all time'
author: 'Ben'
---

Here is my _great_ post!

---
import * as greatPost from './posts/great-post.md';
const posts = Object.values(import.meta.glob('./posts/*.md', { eager: true }));
---

<p>{greatPost.frontmatter.title}</p>
<p>Written by: {greatPost.frontmatter.author}</p>

{greatPost.compiledContent()}

<p>Post Archive:</p>
<ul>
  {posts.map(post => <li><a href={post.url}>{post.frontmatter.title}</a></li>)}
</ul>

사용 가능한 속성

콘텐츠 컬렉션 쿼리의 Markdown

헬퍼 함수 getCollection() 또는 getEntry()를 사용하여 컬렉션에서 데이터를 가져올 때, Markdown의 프런트매터 속성은 data 객체(예: post.data.title)에서 사용할 수 있습니다. 또한 body는 원시 형태의 컴파일되지 않은 본문 내용을 문자열로 포함합니다.

render() 함수는 Markdown 본문 내용, 생성된 제목 목록, 그리고 remark나 rehype 플러그인이 적용된 후의 수정된 프런트매터 객체를 반환합니다.

컬렉션 쿼리에서 반환된 콘텐츠 사용하기에 대해 자세히 알아보세요.

Markdown 가져오기

import 또는 import.meta.glob()을 사용하여 Markdown을 가져올 때 내보낸 다음 속성은 .astro 컴포넌트에서 사용할 수 있습니다:

file - 절대 파일 경로 (예: /home/user/projects/.../file.md).
url - 페이지의 URL (예: /en/guides/markdown-content).
frontmatter - 파일의 YAML (또는 TOML) 프런트매터에 지정된 모든 데이터를 포함합니다.
<Content /> - 파일의 전체 렌더링된 콘텐츠를 반환하는 컴포넌트입니다.
rawContent() - 원시 Markdown 문서를 문자열로 반환하는 함수입니다.
compiledContent() - HTML 문자열로 컴파일된 Markdown 문서를 반환하는 비동기 함수입니다.
getHeadings() - { depth: number; slug: string; text: string }[] 타입을 가지는 파일의 모든 제목 (예: <h1>부터 <h6>)의 배열을 반환하는 비동기 함수입니다. 각 제목의 slug는 특정 제목에 대해 생성된 ID에 해당하며, 앵커 링크에 사용될 수 있습니다.

Markdown 블로그 게시물 예시에서는 다음 Astro.props 객체를 전달할 수 있습니다:

Astro.props = {
  file: "/home/user/projects/.../file.md",
  url: "/en/guides/markdown-content/",
  frontmatter: {
    /** 블로그 게시물의 프런트매터 */
    title: "Astro 0.18 Release",
    date: "Tuesday, July 27 2021",
    author: "Matthew Phillips",
    description: "Astro 0.18 is our biggest release since Astro launch.",
  },
  getHeadings: () => [
    {"depth": 1, "text": "Astro 0.18 Release", "slug": "astro-018-release"},
    {"depth": 2, "text": "Responsive partial hydration", "slug": "responsive-partial-hydration"}
    /* ... */
  ],
  rawContent: () => "# Astro 0.18 Release\nA little over a month ago, the first public beta [...]",
  compiledContent: () => "<h1>Astro 0.18 Release</h1>\n<p>A little over a month ago, the first public beta [...]</p>",
}

`<Content />` 컴포넌트

<Content /> 컴포넌트는 Markdown 파일에서 Content를 가져와서 사용할 수 있습니다. 이 컴포넌트는 파일의 전체 본문 콘텐츠를 HTML로 렌더링하여 반환합니다. 선택적으로 Content의 이름을 원하는 컴포넌트 이름으로 변경할 수 있습니다.

이와 유사하게 <Content /> 컴포넌트를 렌더링하여 Markdown 컬렉션 항목의 HTML 콘텐츠를 렌더링을 할 수 있습니다.

---
// 가져오기 문
import {Content as PromoBanner} from '../components/promoBanner.md';

// 컬렉션 쿼리
import { getEntry, render } from 'astro:content';
const product = await getEntry('products', 'shirt');
const { Content } = await render(product);
---
<h2>Today's promo</h2>
<PromoBanner />

<p>Sale Ends: {product.data.saleEndDate.toDateString()}</p>
<Content />

제목 ID

Markdown으로 제목을 작성하면 자동으로 앵커 링크가 제공되므로 페이지의 특정 섹션으로 바로 연결할 수 있습니다. Astro는 ASCII가 아닌 콘텐츠를 쉽게 작성할 수 있도록 페이지에 <meta charset="utf-8"> 태그를 자동으로 추가합니다.

---
title: My page of content
---
## Introduction

I can link internally to [my conclusion](#conclusion) on the same page when writing Markdown.

## Conclusion

I can visit `https://example.com/page-1/#introduction` in a browser to navigate directly to my Introduction.

Astro는 github-slugger를 기반으로 제목의 id를 생성합니다. 더 많은 예시는 github-slugger 문서에서 찾을 수 있습니다.

제목 ID와 플러그인

Astro는 Markdown과 MDX 파일의 모든 제목 요소(<h1>부터 <h6>)에 id 속성을 주입합니다. 이 데이터는 가져온 파일의 Markdown 내보내기 속성으로 제공되는 getHeadings() 유틸리티를 통해, 또는 콘텐츠 컬렉션 쿼리에서 반환된 Markdown을 사용할 때는 render() 함수를 통해 가져올 수 있습니다.

Markdown 프로세서 플러그인(예: rehype-slug)을 사용해 id 속성을 삽입함으로써 이러한 제목 ID를 사용자 지정할 수 있습니다. 사용자 지정 ID는 Astro의 기본 ID 대신 HTML 출력과 getHeadings()가 반환하는 항목에 반영됩니다.

Astro는 사용자 지정 플러그인이 실행된 후 id 속성을 삽입하므로, 플러그인에서 설정한 모든 ID는 유지됩니다. 사용자 지정 플러그인 중 하나가 Astro가 삽입한 ID에 접근해야 하는 경우, Astro의 제목 ID 플러그인을 가져와 해당 ID에 의존하는 플러그인보다 먼저 배치할 수 있습니다:

Unified
Sätteri

import { defineConfig } from 'astro/config';
import { unified, rehypeHeadingIds } from '@astrojs/markdown-remark';
import { otherPluginThatReliesOnHeadingIDs } from 'some/plugin/source';

export default defineConfig({
  markdown: {
    processor: unified({
      rehypePlugins: [
        rehypeHeadingIds,
        otherPluginThatReliesOnHeadingIDs,
      ],
    }),
  },
});

import { defineConfig } from 'astro/config';
import { satteri, satteriHeadingIdsPlugin } from '@astrojs/markdown-satteri';
import { otherPluginThatReliesOnHeadingIDs } from 'some/plugin/source';

export default defineConfig({
  markdown: {
    processor: satteri({
      hastPlugins: [
        satteriHeadingIdsPlugin(),
        otherPluginThatReliesOnHeadingIDs,
      ],
    }),
  },
});

Markdown 플러그인

Astro는 설정 가능한 Markdown 프로세서를 사용해 Markdown을 렌더링합니다. 기본적으로는 활발한 플러그인 생태계를 갖춘 remark 및 rehype의 unified 파이프라인을 사용합니다.

Astro는 GitHub-Flavored Markdown과 SmartyPants를 자동으로 적용합니다. 이를 통해 텍스트에서 클릭 가능한 링크를 생성하고, 인용 부호 및 em dash(긴 대시)의 서식을 지정하는 등의 편리한 기능을 사용할 수 있습니다.

플러그인을 사용해 Markdown 처리를 확장하거나, 추가 파서 기능을 활성화하거나, 완전히 다른 프로세서로 전환할 수 있습니다. 전체 Markdown 구성 옵션 목록도 확인해 보세요.

Markdown 프로세서 선택하기

markdown.processor 옵션은 .md 및 .mdx 파일을 렌더링할 엔진을 제어합니다. Astro는 두 가지 공식 옵션을 제공합니다.

unified() (기본값): 풍부한 플러그인 생태계를 갖춘 remark 및 rehype 파이프라인입니다.
satteri(): 자체 플러그인 모델을 갖춘 Sätteri 파이프라인입니다. 더 빠른 Markdown 및 MDX 컴파일러로, 별도로 설치해야 하는 @astrojs/markdown-satteri 패키지를 통해 제공됩니다.

remark 및 rehype 플러그인 사용하기

기본 unified() 프로세서는 서드파티 remark 및 rehype 플러그인을 지원합니다. 이러한 플러그인을 사용하면 목차 자동 생성, 접근 가능한 이모지 레이블 적용, Markdown 스타일 적용과 같은 새로운 기능으로 Markdown을 확장할 수 있습니다.

awesome-remark 및 awesome-rehype와 같은 인기 플러그인들을 찾아보시기 바랍니다! 구체적인 설치 지침은 각 플러그인의 자체 README를 참조하세요.

@astrojs/markdown-remark에서 unified를 가져온 뒤, markdown.processor를 통해 플러그인을 전달하세요. 이 예시에서는 Markdown 파일에 remark-toc 및 rehype-accessible-emojis를 적용합니다.

import { defineConfig } from 'astro/config';
import { unified } from '@astrojs/markdown-remark';
import remarkToc from 'remark-toc';
import { rehypeAccessibleEmojis } from 'rehype-accessible-emojis';

export default defineConfig({
  markdown: {
    processor: unified({
      remarkPlugins: [[remarkToc, { heading: 'toc', maxDepth: 3 }]],
      rehypePlugins: [rehypeAccessibleEmojis],
    }),
  },
});

Remark 또는 rehype 플러그인 사용자 정의하기

플러그인을 사용자 정의하려면 중첩 배열에서 플러그인 뒤에 옵션 객체를 제공하세요.

아래 예시에서는 remarkToc 플러그인에 heading 옵션을 추가하여 목차 위치를 변경하고, rehype-autolink-headings 플러그인에 behavior 옵션을 추가하여 제목 텍스트 뒤에 앵커 태그를 추가했습니다.

import { defineConfig } from 'astro/config';
import { unified } from '@astrojs/markdown-remark';
import remarkToc from 'remark-toc';
import rehypeSlug from 'rehype-slug';
import rehypeAutolinkHeadings from 'rehype-autolink-headings';

export default defineConfig({
  markdown: {
    processor: unified({
      remarkPlugins: [[remarkToc, { heading: 'contents' }]],
      rehypePlugins: [rehypeSlug, [rehypeAutolinkHeadings, { behavior: 'append' }]],
    }),
  },
});

Sätteri 프로세서로 전환하기

remark 및 rehype 대신 Sätteri를 사용하려면 @astrojs/markdown-satteri를 설치한 다음 satteri를 가져와 markdown.processor에 전달하세요:

import { defineConfig } from 'astro/config';
import { satteri } from '@astrojs/markdown-satteri';
import { myMdastPlugin } from './my-satteri-plugin.mjs';

export default defineConfig({
  markdown: {
    processor: satteri({
      mdastPlugins: [myMdastPlugin()],
      features: { directive: true, definitionList: true },
    }),
  },
});

Sätteri 프로세서는 mdastPlugins 및 hastPlugins를 통해 자체 플러그인을 사용할 수 있으며, features를 통해 선택적 파서 기능을 활성화하거나 비활성화할 수 있습니다. 사용 가능한 플러그인과 기능에 대해서는 Sätteri 문서를 참조하세요.

프로세서를 전환하면 .md 및 .mdx 파일 모두에서 remark 및 rehype 대신 Sätteri가 사용됩니다. 구성에 포함된 remark 또는 rehype 플러그인은 적용되지 않습니다. Sätteri를 .mdx 파일에만 사용하려면 MDX 통합의 processor 옵션을 설정하세요.

프로그래밍 방식으로 프런트매터 수정하기

remark/rehype 프로세서를 사용하는 경우, remark 또는 rehype 플러그인을 통해 모든 Markdown 및 MDX 파일에 프런트매터 속성을 추가할 수 있습니다.

플러그인의 file 인수에서 data.astro.frontmatter 속성에 customProperty를 추가합니다.
example-remark-plugin.mjs
```
export function exampleRemarkPlugin() {
  // 모든 remark 및 rehype 플러그인은 별도의 함수를 반환합니다.
  return function (tree, file) {
    file.data.astro.frontmatter.customProperty = 'Generated property';
  }
}
```
추가된 버전: astro@2.0.0
data.astro.frontmatter에는 특정 Markdown 또는 MDX 문서의 모든 속성이 포함되어 있습니다. 이를 통해 기존 프런트매터 속성을 수정하거나 기존 프런트매터에서 새 속성을 계산할 수 있습니다.

이 플러그인을 markdown 또는 mdx 통합 구성에 적용하세요.

import { defineConfig } from 'astro/config';
import { unified } from '@astrojs/markdown-remark';
import { exampleRemarkPlugin } from './example-remark-plugin.mjs';

export default defineConfig({
  markdown: {
    processor: unified({ remarkPlugins: [exampleRemarkPlugin] }),
  },
});

또는

import { defineConfig } from 'astro/config';
import mdx from '@astrojs/mdx';
import { unified } from '@astrojs/markdown-remark';
import { exampleRemarkPlugin } from './example-remark-plugin.mjs';

export default defineConfig({
  integrations: [
    mdx({
      processor: unified({ remarkPlugins: [exampleRemarkPlugin] }),
    }),
  ],
});

이제 모든 Markdown 또는 MDX 파일의 프런트매터에 customProperty가 있으므로 Markdown을 가져올 때 레이아웃의 Astro.props.frontmatter 속성에서 사용할 수 있습니다.

관련 레시피: 읽기 시간 추가

MDX에서 Markdown 구성 확장

Astro의 MDX 통합은 기본적으로 프로젝트의 기존 Markdown 구성을 확장하며, 여기에는 Markdown 프로세서도 포함됩니다. 개별 옵션을 재정의하려면 MDX 구성에서 해당 옵션을 지정하면 됩니다.

다음 예시는 .md 파일과 .mdx 파일에 서로 다른 구문 강조 도구와 플러그인 세트를 사용하는 방법을 보여줍니다.

import { defineConfig } from 'astro/config';
import { unified } from '@astrojs/markdown-remark';
import mdx from '@astrojs/mdx';

export default defineConfig({
  markdown: {
    syntaxHighlight: 'prism',
    processor: unified({ remarkPlugins: [remarkPlugin1] }),
  },
  integrations: [
    mdx({
      // `.mdx` 파일에서는 이 옵션이 `markdown.syntaxHighlight`를 재정의합니다.
      syntaxHighlight: 'shiki',

      // `.mdx` 파일에서는 이 옵션이 `markdown.processor`를 다른 remark 플러그인으로 재정의합니다.
      processor: unified({ remarkPlugins: [remarkPlugin2] }),
    })
  ]
});

MDX에서 Markdown 구성을 확장하지 않으려면 extendMarkdownConfig 옵션 (기본적으로 활성화됨)을 false로 설정하세요.

import { defineConfig } from 'astro/config';
import { unified } from '@astrojs/markdown-remark';
import mdx from '@astrojs/mdx';

export default defineConfig({
  markdown: {
    processor: unified({ remarkPlugins: [remarkPlugin] }),
  },
  integrations: [
    mdx({
      // 이제 Markdown 구성이 무시됩니다.
      extendMarkdownConfig: false,
      // 플러그인 없이 기본 `unified()` 프로세서가 사용됩니다.
    })
  ]
});

개별 Markdown 페이지

Astro는 .md 및 기타 Markdown 파일 유형을 포함하여 /src/pages/ 디렉터리 내 지원되는 모든 파일을 페이지로 취급합니다.

이 디렉터리 또는 하위 디렉터리에 파일을 배치하면 파일 경로명을 사용하여 페이지 경로를 자동으로 빌드하고 HTML로 렌더링된 Markdown 콘텐츠가 표시됩니다.

---
title: Hello, World
---

# Hi there!

This Markdown file creates a page at `your-domain.com/page-1/`

It probably isn't styled much, but Markdown does support:
- **bold** and _italics._
- lists
- [links](https://astro.build)
- <p>HTML elements</p>
- and more!

프런트매터 `layout` 속성

개별 Markdown 페이지의 제한된 기능을 보완하기 위해, Astro는 Markdown 레이아웃 컴포넌트에 대한 상대 경로를 가진 특별한 프런트매터 layout 속성을 제공합니다. layout은 콘텐츠 컬렉션을 사용하여 Markdown 콘텐츠를 쿼리하고 렌더링할 때는 특별한 속성이 아니며, 의도된 사용 사례를 벗어나면 지원이 보장되지 않습니다.

만약 Markdown 파일이 src/pages/에 위치해 있다면, 레이아웃 컴포넌트를 생성하고 이를 layout 속성에 추가하여 Markdown 콘텐츠 주위에 페이지 셸을 제공하세요.

---
layout: ../../layouts/BlogPostLayout.astro
title: Astro in brief
author: Himanshu
description: Find out what makes Astro awesome!
---
This is a post written in Markdown.

이 레이아웃 컴포넌트는 Astro 템플릿의 Astro.props를 통해 특정 속성을 자동으로 사용할 수 있는 일반 Astro 컴포넌트입니다. 예를 들어, Astro.props.frontmatter를 통해 Markdown 파일의 프런트매터 속성에 액세스할 수 있습니다:

---
const {frontmatter} = Astro.props;
---
<html>
  <head>
    <!-- ... -->
    <meta charset="utf-8"> // 기본적으로 더 이상 추가되지 않습니다.
  </head>
  <!-- ... -->
  <h1>{frontmatter.title}</h1>
  <h2>Post author: {frontmatter.author}</h2>
  <p>{frontmatter.description}</p>
  <slot /> <!-- Markdown content is injected here -->
  <!-- ... -->
</html>

프런트매터 layout 속성을 사용할 때는 Astro가 더 이상 자동으로 추가하지 않으므로 레이아웃에 <meta charset="utf-8"> 태그를 포함해야 합니다. 이제 레이아웃 컴포넌트에서 Markdown을 스타일링할 수도 있습니다.

Markdown 레이아웃에 대해 더 자세히 알아보세요.

원격 Markdown 가져오기

Astro의 내장 Markdown 프로세서는 원격 Markdown 처리에 사용할 수 없습니다.

콘텐츠 컬렉션에서 사용하기 위해 원격 Markdown을 가져오려면, renderMarkdown() 함수에 접근할 수 있는 사용자 정의 로더를 구축할 수 있습니다.

원격 Markdown을 직접 가져와 HTML로 렌더링하려면 NPM에서 자체 Markdown 파서를 설치 및 구성해야 합니다. 이렇게 하면 사용자가 구성한 Astro의 기본 제공 Markdown 설정이 상속되지 않습니다.

이를 프로젝트에서 구현하기 전에 이러한 제한 사항을 이해하고, 대신 콘텐츠 컬렉션 로더를 사용하여 원격 Markdown을 가져오는 것을 고려하세요.

---
// 예: 원격 API에서 Markdown 가져오기
// 런타임에 HTML로 렌더링합니다.
// "marked" 사용 (https://github.com/markedjs/marked)
import { marked } from 'marked';
const response = await fetch('https://raw.githubusercontent.com/wiki/adam-p/markdown-here/Markdown-Cheatsheet.md');
const markdown = await response.text();
const content = marked.parse(markdown);
---
<article set:html={content} />

기여하기 커뮤니티 후원하기