Unified API 참조

Astro는 @astrojs/markdown-remark 패키지를 통해 인기 있는 Markdown 생태계인 unified에 대한 선택적 지원을 제공합니다. 이를 통해 remark와 rehype 플러그인을 사용하여 렌더링 과정을 사용자 지정하고 확장할 수 있습니다. 또한 통합이나 플러그인을 빌드할 때 유용한 도우미와 타입 집합을 제공합니다.

기능과 사용 예시는 Markdown 가이드의 Markdown 프로세서를 참조하세요.

@astrojs/markdown-remark에서 가져오기

다음 도우미는 @astrojs/markdown-remark에서 가져옵니다:

import {
  createMarkdownProcessor,
  isUnifiedProcessor,
  parseFrontmatter,
  rehypeHeadingIds,
  unified,
} from "@astrojs/markdown-remark";

createMarkdownProcessor()

타입: (opts?: AstroMarkdownOptions) => Promise<MarkdownRenderer>

추가된 버전: @astrojs/markdown-remark@3.2.0

독립 실행형 unified 기반 Markdown 렌더러를 생성합니다. 프로젝트에 구성된 markdown.processor와 독립적으로 Markdown을 렌더링해야 할 때 유용합니다.

src/utils/markdown.ts

import { createMarkdownProcessor } from "@astrojs/markdown-remark";

const processor = await createMarkdownProcessor();
const { code, metadata } = await processor.render("# Hello world");

isUnifiedProcessor()

타입: (p: { name: string; }) => boolean

추가된 버전: @astrojs/markdown-remark@7.2.0

지정된 Markdown 프로세서가 unified인지 확인합니다. unified 전용 로직을 적용하기 전에 프로세서의 타입을 확인해야 할 때 유용합니다.

다음 예시는 통합 내에서 구성된 Markdown 프로세서가 unified인지 확인합니다:

src/integrations/my-integration.ts

import { isUnifiedProcessor } from "@astrojs/markdown-remark";
import type { AstroIntegration } from "astro";

export default function myIntegration(): AstroIntegration {
  return {
    name: "my-integration",
    hooks: {
      "astro:config:done": ({ config }) => {
        if (isUnifiedProcessor(config.markdown.processor)) {
          // 여기에 unified 전용 로직을 적용합니다
        }
      },
    },
  };
}

rehypeHeadingIds()

타입: RehypePlugin

추가된 버전: @astrojs/markdown-remark@1.2.0

Markdown 콘텐츠의 모든 제목에 대한 제목 ID를 생성하고 수집합니다. 이를 통해 Markdown 콘텐츠를 가져오거나 렌더링할 때 사용할 수 있습니다.

사용 예시는 Markdown 가이드의 제목 ID와 플러그인을 참조하세요.

unified()

타입: (options?: UnifiedProcessorOptions) => MarkdownProcessor

추가된 버전: @astrojs/markdown-remark@7.2.0

.md와 .mdx 파일을 렌더링하기 위한 unified 기반 프로세서를 생성합니다. unified를 기본 Markdown 프로세서로 사용하려면 markdown.processor에 전달하세요.

예시와 함께 Markdown 프로세서 설정하기와 remark 및 rehype 플러그인 사용하기에 대해 자세히 알아보세요.

옵션

타입: UnifiedProcessorOptions

다음 옵션을 사용하여 unified 프로세서 동작을 사용자 지정할 수 있습니다.

options.remarkPlugins

타입: RemarkPlugins
기본값: []

remark 플러그인을 전달하여 Markdown이 빌드되는 방식을 사용자 지정합니다. 플러그인 함수를 가져와 적용하거나(권장), 플러그인 이름을 문자열로 전달할 수 있습니다.

다음 예시는 사용자 지정 heading 옵션과 함께 remark-toc 플러그인을 unified 프로세서에 전달합니다:

astro.config.mjs

import { defineConfig } from "astro/config";
import { unified } from "@astrojs/markdown-remark";
import remarkToc from "remark-toc";

export default defineConfig({
  markdown: {
    processor: unified({
      remarkPlugins: [[remarkToc, { heading: "contents" }]],
    }),
  },
});

options.rehypePlugins

타입: RehypePlugins
기본값: []

rehype 플러그인을 전달하여 Markdown 콘텐츠에서 생성되는 HTML을 사용자 지정합니다. 플러그인 함수를 가져와 적용하거나(권장), 플러그인 이름을 문자열로 전달할 수 있습니다.

다음 예시는 rehype-accessible-emojis 플러그인을 unified 프로세서에 전달합니다:

astro.config.mjs

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

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

options.remarkRehype

타입: RemarkRehype

remark-rehype 플러그인에 옵션을 전달하여 Markdown이 HTML로 변환되는 방식을 제어합니다.

다음 예시는 각주 레이블을 사용자 지정합니다:

astro.config.mjs

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

export default defineConfig({
  markdown: {
    processor: unified({
      remarkRehype: {
        footnoteLabel: "Footnotes",
        footnoteBackLabel: "Back to reference 1",
      },
    }),
  },
});

options.recmaPlugins

타입: PluggableList
기본값: []

recma 플러그인을 전달하여 MDX 파일의 estree 출력을 사용자 지정합니다. 이는 JavaScript 변수를 수정하거나 주입할 때 유용합니다.

astro.config.mjs

import { defineConfig } from "astro/config";
import { unified } from "@astrojs/markdown-remark";
import myRecmaPlugin from "./my-recma-plugin.mjs";

export default defineConfig({
  markdown: {
    processor: unified({
      recmaPlugins: [myRecmaPlugin],
    }),
  },
});

AST Explorer를 사용하여 estree 출력을 실험해 볼 수 있으며, JavaScript 노드를 검색하려면 estree-util-visit을 사용해 보세요.

options.gfm

타입: boolean
기본값: true

GitHub-Flavored Markdown(GFM) 지원을 활성화할지 비활성화할지 여부입니다.

이를 비활성화하려면 gfm 옵션을 false로 설정하세요:

astro.config.mjs

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

export default defineConfig({
  markdown: {
    processor: unified({
      gfm: false,
    }),
  },
});

Astro에서 GitHub-Flavored Markdown 사용하기에 대해 자세히 알아보세요.

options.smartypants

타입: boolean | Smartypants
기본값: true

SmartyPants 포매터를 사용하여 곧은따옴표를 둥근따옴표로, 대시를 en/em 대시로, 점 세 개를 줄임표로 변환할지 여부입니다.

비활성화하거나 retext-smartypants에서 지원하는 속성을 담은 구성 객체를 제공하여 동작을 사용자 지정할 수 있습니다.

다음 예시는 스마트 구두점 지원을 비활성화합니다:

astro.config.mjs

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

export default defineConfig({
  markdown: {
    processor: unified({
      smartypants: false,
    }),
  },
});

Markdown 가이드에서 스마트 구두점 구성하기에 대해 자세히 알아보세요.

@astrojs/markdown-remark 타입

다음 타입은 @astrojs/markdown-remark에서 가져옵니다:

import type {
  AstroMarkdownOptions,
  MarkdownHeading,
  MarkdownProcessor,
  MarkdownRenderOptions,
  MarkdownRenderResult,
  MarkdownRenderer,
  RehypePlugin,
  RehypePlugins,
  RemarkPlugin,
  RemarkPlugins,
  RemarkRehype,
  ShikiConfig,
  Smartypants,
  SyntaxHighlightConfig,
  SyntaxHighlightConfigType,
} from "@astrojs/markdown-remark";

AstroMarkdownOptions

타입: { syntaxHighlight?: SyntaxHighlightConfig | SyntaxHighlightConfigType | false; shikiConfig?: ShikiConfig; image?: { domains?: string[]; remotePatterns?: RemotePattern[]; }; }

추가된 버전: @astrojs/markdown-remark@7.2.0

Markdown 프로세서 구성을 설명합니다. 다음 내용과 함께 모든 markdown 옵션을 포함합니다.

AstroMarkdownOptions.image

타입: { domains?: string[]; remotePatterns?: RemotePattern[]; }

Markdown 프로세서에 대한 이미지 구성을 지정합니다.

AstroMarkdownOptions.image.domains

타입: string[]

구성 참조에서 image.domains를 참조하세요.

AstroMarkdownOptions.image.remotePatterns

타입: RemotePattern[]

구성 참조에서 image.remotePatterns를 참조하세요.

MarkdownHeading

타입: { depth: number; slug: string; text: string; }

추가된 버전: @astrojs/markdown-remark@7.2.0

Markdown 또는 MDX 문서의 제목을 나타냅니다.

MarkdownHeading.depth

타입: number

1(<h1>)부터 6(<h6>)까지의 제목 수준입니다.

MarkdownHeading.slug

타입: string

앵커 링크의 id 속성으로 사용되는 생성된 슬러그를 지정합니다.

MarkdownHeading.text

타입: string

제목의 렌더링된 텍스트 콘텐츠를 포함합니다.

MarkdownProcessor

타입: object

추가된 버전: @astrojs/markdown-remark@7.2.0

구성된 markdown.processor를 설명합니다. 변수가 내장 Markdown 프로세서 중 하나를 허용함을 나타내려는 경우에 유용합니다.

MarkdownRenderOptions

타입: { fileURL?: URL; frontmatter?: Record<string, any>; }

추가된 버전: @astrojs/markdown-remark@7.2.0

Markdown 콘텐츠를 렌더링할 때 사용할 수 있는 옵션을 설명합니다.

MarkdownRenderOptions.fileURL

타입: URL

렌더링 중인 Markdown 파일의 URL을 지정합니다.

MarkdownRenderOptions.frontmatter

타입: Record<string, any>

Markdown 콘텐츠에 대한 프런트매터 데이터를 제공합니다.

MarkdownRenderResult

타입: { code: string; metadata: { headings: MarkdownHeading[]; localImagePaths: string[]; remoteImagePaths: string[]; frontmatter: Record<string, any>; }; }

추가된 버전: @astrojs/markdown-remark@7.2.0

렌더링된 Markdown 파일을 설명합니다.

MarkdownRenderResult.code

타입: string

렌더링된 HTML 코드를 포함합니다.

MarkdownRenderResult.metadata

타입: { headings: MarkdownHeading[]; localImagePaths: string[]; remoteImagePaths: string[]; frontmatter: Record<string, any>; }

렌더링된 콘텐츠와 관련된 메타데이터를 설명합니다.

MarkdownRenderResult.metadata.headings

타입: MarkdownHeading[]

추출된 제목 목록입니다.

MarkdownRenderResult.metadata.localImagePaths

타입: string[]

렌더링된 콘텐츠에서 참조된 로컬 이미지 경로 배열입니다.

MarkdownRenderResult.metadata.remoteImagePaths

타입: string[]

렌더링된 콘텐츠에서 참조된 원격 이미지 경로 배열입니다.

MarkdownRenderResult.metadata.frontmatter

타입: Record<string, any>

렌더러에 전달된 프런트매터입니다.

MarkdownRenderer

타입: { render: (content: string, opts?: MarkdownRenderOptions) => Promise<MarkdownRenderResult>; }

추가된 버전: @astrojs/markdown-remark@7.2.0

독립 실행형 Markdown 프로세서에서 구현하는 인터페이스를 지정합니다.

MarkdownRenderer.render()

타입: (content: string, opts?: MarkdownRenderOptions) => Promise<MarkdownRenderResult>

지정된 Markdown 콘텐츠에 대한 렌더링된 HTML과 메타데이터를 생성합니다. 두 번째 인자로 옵션을 사용하여 렌더링 과정을 사용자 지정할 수 있습니다.

RehypePlugin

타입: Plugin<PluginParameters, HastRoot>

추가된 버전: @astrojs/markdown-remark@7.2.0

unified 생태계에서 rehype 플러그인을 정의합니다.

RehypePlugins

타입: (string | [string, any] | RehypePlugin | [RehypePlugin, any])[]

추가된 버전: @astrojs/markdown-remark@7.2.0

Markdown 콘텐츠에서 생성된 HTML 출력을 사용자 지정하기 위한 rehype 플러그인 목록입니다. 각 항목은 가져온 플러그인이거나 Astro가 자동으로 가져와야 하는 패키지 이름입니다.

RemarkPlugin

타입: Plugin<PluginParameters, MdastRoot>

추가된 버전: @astrojs/markdown-remark@7.2.0

unified 생태계에서 remark 플러그인을 정의합니다.

RemarkPlugins

타입: (string | [string, any] | RemarkPlugin | [RemarkPlugin, any])[]

추가된 버전: @astrojs/markdown-remark@7.2.0

Markdown 처리를 사용자 지정하기 위한 remark 플러그인 목록입니다. 각 항목은 가져온 플러그인이거나 Astro가 자동으로 가져와야 하는 패키지 이름입니다.

RemarkRehype

타입: Record<string, unknown>

추가된 버전: @astrojs/markdown-remark@7.2.0

remark-rehype 플러그인에 전달되는 옵션을 지정합니다.

ShikiConfig

타입: object

추가된 버전: @astrojs/markdown-remark@7.2.0

Shiki 구문 강조기를 구성하기 위한 옵션을 설명합니다.

사용 예시와 함께 구문 강조에 대해 자세히 알아보세요.

ShikiConfig.langs

타입: LanguageRegistration[]

구문 강조기에서 활성화할 Shiki 언어 목록입니다.

ShikiConfig.langAlias

타입: Record<string, string>

Shiki 언어 ID에 매핑할 사용자 지정 별칭을 정의합니다.

Shiki 언어 별칭에 대한 자세한 내용은 Shiki 문서를 참조하세요.

ShikiConfig.theme

타입: ThemePresets | ThemeRegistration | ThemeRegistrationRaw

구문 강조를 위한 기본 테마를 지정합니다. Shiki 번들 테마 또는 사용자 지정 Shiki 테마일 수 있습니다.

사용 예시와 함께 Shiki의 기본 테마 설정에 대해 자세히 알아보세요.

ShikiConfig.themes

타입: Record<string, ThemePresets | ThemeRegistration | ThemeRegistrationRaw>

테마 이름을 해당 Shiki 테마 구성에 매핑하는 객체입니다.

사용 예시와 함께 라이트 및 다크 모드 테마 설정 방법을 알아보세요.

ShikiConfig.defaultColor

타입: 'light' | 'dark' | string | false

[ShikiConfig.themes]가 정의되었을 때 사용할 기본 테마를 지정합니다.

ShikiConfig.wrap

타입: boolean | null

긴 줄을 줄바꿈하여 가로 스크롤을 방지할지 여부입니다.

ShikiConfig.transformers

타입: ShikiTransformer[]

생성된 HTML을 사용자 지정하기 위한 Shiki 트랜스포머 목록입니다.

특정 코드 블록에만 필요한 경우 <Code />에 transformers 적용하기 방법을 알아보세요.

Smartypants

타입: object

추가된 버전: @astrojs/markdown-remark@7.2.0

retext-smartypants에 대한 구성 옵션을 설명합니다.

Astro에서 스마트 구두점 사용하기에 대해 자세히 알아보세요.

SyntaxHighlightConfig

타입: { type: SyntaxHighlightConfigType; excludeLangs?: string[]; }

추가된 버전: @astrojs/markdown-remark@7.2.0

구성된 구문 강조기와 강조 표시에서 제외할 언어를 지정합니다.

사용 예시와 함께 구문 강조에 대해 자세히 알아보세요.

SyntaxHighlightConfigType

타입: 'shiki' | 'prism'

추가된 버전: @astrojs/markdown-remark@7.2.0

Astro에서 지원하는 구문 강조기의 유니언입니다.