diff --git a/src/content/docs/ko/guides/markdown-content.mdx b/src/content/docs/ko/guides/markdown-content.mdx index b06dcfd9ccb01..f041100554e10 100644 --- a/src/content/docs/ko/guides/markdown-content.mdx +++ b/src/content/docs/ko/guides/markdown-content.mdx @@ -1,6 +1,6 @@ --- -title: Markdown & MDX -description: Astro에서 Markdown 또는 MDX를 사용하여 콘텐츠를 만드는 방법을 알아보세요. +title: Astro에서 Markdown 사용하기 +description: Astro에서 Markdown을 사용하여 콘텐츠를 만드는 방법을 알아보세요. i18nReady: true --- import Since from '~/components/Since.astro'; @@ -9,220 +9,27 @@ import RecipeLinks from "~/components/RecipeLinks.astro"; import ReadMore from '~/components/ReadMore.astro'; import { Steps } from '@astrojs/starlight/components'; -[Markdown](https://daringfireball.net/projects/markdown/)은 일반적으로 블로그 게시물 및 문서와 같이 텍스트가 많은 콘텐츠를 작성하는 데 사용됩니다. Astro에는 title, description, tags와 같은 사용자 정의 메타데이터를 정의하기 위해 [프런트매터 YAML](https://dev.to/paulasantamaria/introduction-to-yaml-125f)도 포함할 수 있는 표준 Markdown 파일에 대한 기본 지원이 포함되어 있습니다. +[Markdown](https://daringfireball.net/projects/markdown/)은 일반적으로 블로그 게시물 및 문서와 같이 텍스트가 많은 콘텐츠를 작성하는 데 사용됩니다. Astro에는 title, description, tags와 같은 사용자 정의 속성을 정의하기 위해 [프런트매터 YAML](https://dev.to/paulasantamaria/introduction-to-yaml-125f)도 포함할 수 있는 Markdown 파일에 대한 기본 지원이 포함되어 있습니다. -[@astrojs/mdx 통합](/ko/guides/integrations-guide/mdx/)이 설치되면 Astro는 Markdown 콘텐츠의 JavaScript 표현식 및 컴포넌트 지원과 같은 추가 기능을 제공하는 [MDX](https://mdxjs.com/) (`.mdx`) 파일도 지원합니다. +Astro에서는 Markdown으로 콘텐츠를 작성한 다음 `.astro` 컴포넌트에 이를 렌더링할 수 있습니다. 이는 콘텐츠용으로 설계된 친숙한 작성 형식과 Astro의 컴포넌트 구문 및 아키텍처의 유연성을 결합한 것입니다. -Markdown 콘텐츠를 작성하려면 두 가지 유형의 파일 중 하나 또는 두 가지를 모두 사용하세요! +Markdown에 컴포넌트 및 JSX 표현식을 포함하는 등의 추가 기능을 사용하려면 [`@astrojs/mdx` 통합](/ko/guides/integrations-guide/mdx/)을 추가하여 [MDX](https://mdxjs.com/)로 Markdown 콘텐츠를 작성하세요. -## Markdown 및 MDX 페이지 +## Markdown 파일 구성하기 -### 콘텐츠 컬렉션 +로컬 Markdown 파일은 `src/` 디렉터리 내 어디에나 보관할 수 있습니다. 단일 로컬 Markdown 파일은 `import` 문을 사용하여 `.astro` 컴포넌트로 가져올 수 있으며, 여러 파일을 한 번에 쿼리하기 위해서는 Vite의 `import.meta.glob()`을 사용할 수 있습니다. -Astro의 특별한 `src/content/` 폴더에서 Markdown 및 MDX 파일을 관리할 수 있습니다. [콘텐츠 컬렉션](/ko/guides/content-collections/)은 콘텐츠를 구성하고, 프런트매터의 유효성을 검사하고, 콘텐츠 작업 중 자동 TypeScript 타입 안전성을 제공하는 데 도움이 됩니다. +연관된 Markdown 파일 그룹이 있는 경우 [컬렉션으로 정의](/ko/guides/content-collections/)하는 것을 고려해 보세요. 이렇게 하면 파일 시스템의 어느 곳에나 또는 원격으로 Markdown 파일을 저장할 수 있는 등 여러 가지 이점이 있습니다. - -- src/content/ - - **newsletter/** - - week-1.md - - week-2.md - - **authors/** - - grace-hopper.md - - alan-turing.md - +컬렉션을 사용하면 콘텐츠별로 최적화된 API를 사용하여 콘텐츠를 쿼리하고 렌더링할 수도 있습니다. 컬렉션은 블로그 게시물이나 제품 항목과 같이 동일한 구조를 공유하는 데이터 집합을 위한 것입니다. 스키마에서 해당 형태를 정의하면 편집기에서 유효성 검사, 타입 안전, 인텔리센스를 사용할 수 있습니다. -[Astro의 콘텐츠 컬렉션](/ko/guides/content-collections/) 사용에 대해 자세히 알아보세요. +{/* 파일 가져오기 대신 [콘텐츠 컬렉션을 사용하는 경우](/ko/guides/content-collections/#when-to-create-a-collection)에 대해 자세히 알아보세요. */} -### 파일 기반 라우팅 +## 동적 JSX 유사 표현식 -Astro는 `/src/pages/` 디렉터리의 `.md` (또는 대체 지원 확장자) 또는 `.mdx` 파일을 페이지로 처리합니다. +Markdown 파일을 가져오거나 쿼리한 후에는 프런트매터 데이터와 본문 콘텐츠를 포함하는 `.astro` 컴포넌트에 동적 HTML 템플릿을 작성할 수 있습니다. -이 디렉터리나 하위 디렉터리에 파일을 배치하면 파일의 경로 이름을 사용하여 페이지 경로가 자동으로 빌드됩니다. - -```markdown ---- -# Example: src/pages/page-1.md -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) -- and more! -``` - -Astro의 [파일 기반 라우팅](/ko/guides/routing/) 또는 [동적 경로](/ko/guides/routing/#동적-경로) 생성 옵션에 대해 자세히 알아보세요. - -## Markdown 기능 - -Astro는 Markdown 및 MDX 파일을 사용할 때 사용할 수 있는 몇 가지 추가 내장 Markdown 기능을 제공합니다. - -### 프런트매터 `layout` - -Astro는 Astro [레이아웃 컴포넌트](/ko/basics/layouts/#markdown-레이아웃)에 대한 상대 경로 (또는 [별칭](/ko/guides/imports/#별칭))를 지정할 수 있는 특별한 프런트매터 `layout` 속성이 있는 [Markdown 및 MDX 페이지](/ko/basics/astro-pages/#markdownmdx-페이지) (`src/pages/`에 위치하는)를 제공합니다. - -```markdown {3} ---- -# src/pages/posts/post-1.md -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.props`를 통해 [레이아웃 컴포넌트에 특정 속성을 사용할 수 있습니다](/ko/basics/layouts/#markdown-레이아웃-props). 예를 들어 `Astro.props.frontmatter`를 통해 frontmatter 속성에 액세스할 수 있습니다. - -```astro /frontmatter(?:.\w+)?/ ---- -// src/layouts/BlogPostLayout.astro -const {frontmatter} = Astro.props; ---- - - -

{frontmatter.title}

-

Post author: {frontmatter.author}

-

{frontmatter.description}

- - - -``` - -레이아웃 컴포넌트에서 [Markdown 스타일을 지정](/ko/guides/styling/#markdown-스타일링)할 수도 있습니다. - -[Markdown 레이아웃](/ko/basics/layouts/#markdown-레이아웃)에 대해 자세히 알아보세요. - -### 제목 ID - -Markdown 및 MDX의 제목을 사용하면 자동으로 앵커 링크가 제공되므로 페이지의 특정 섹션에 직접 연결할 수 있습니다. - -```markdown title="src/pages/page-1.md" ---- -title: My page of content ---- -## Introduction - -I can link internally to [my conclusion](#conclusion) on the same page when writing Markdown. - -## Conclusion - -I can use the URL `https://example.com/page-1/#introduction` to navigate directly to my Introduction on the page. -``` - -Astro는 `github-slugger`를 기반으로 `id`라는 제목을 생성합니다. [github-slugger 문서](https://github.com/Flet/github-slugger#usage)에서 더 많은 예시를 찾을 수 있습니다. - -### 특수 문자 이스케이프 - -특정 문자는 Markdown 및 MDX에서 특별한 의미를 갖습니다. 표시하려면 다른 구문을 사용해야 할 수도 있습니다. 이렇게 하려면 해당 문자에 대해 [HTML 엔터티](https://developer.mozilla.org/en-US/docs/Glossary/Entity)를 대신 사용할 수 있습니다. - -예를 들어 `<`가 HTML 요소의 시작 부분으로 해석되는 것을 방지하려면 `<`를 작성하세요. 또는 `{`가 MDX에서 JavaScript 표현식의 시작 부분으로 해석되는 것을 방지하려면 `{`를 작성하세요. - -## MDX 전용 기능 - -Astro [MDX 통합](/ko/guides/integrations-guide/mdx/)을 추가하면 JSX 변수, 표현식, 컴포넌트를 사용하여 Markdown 작성이 향상됩니다. - -또한 [MDX의 Markdown 스타일 프런트매터](https://mdxjs.com/guides/frontmatter/)에 대한 지원을 포함하여 표준 MDX에 추가 기능을 추가합니다. 이를 통해 [프런트매터 `layout`](#프런트매터-layout) 속성과 같은 Astro의 내장 Markdown 기능 대부분을 사용할 수 있습니다. - -`.mdx` 파일은 Astro의 HTML과 같은 구문이 아닌 [MDX 구문](https://mdxjs.com/docs/what-is-mdx/#mdx-syntax)으로 작성되어야 합니다. - -### MDX에서 내보낸 변수 사용 - -MDX는 `export` 구문을 사용하여 MDX 콘텐츠에 변수를 추가할 수 있도록 지원합니다. 이러한 변수는 템플릿 자체에서 액세스할 수 있을 뿐만 아니라 [파일을 다른 곳으로 가져올 때](#markdown-가져오기) 명명된 속성으로 액세스할 수 있습니다. - -예를 들어 MDX 페이지 또는 컴포넌트에서 `title` 필드를 내보내 `{JSX 표현식}`의 제목으로 사용할 수 있습니다. - -```mdx title="/src/pages/posts/post-1.mdx" -export const title = 'My first MDX post' - -# {title} -``` - -### MDX에서 프런트매터 변수 사용 - -Astro MDX 통합에는 기본적으로 MDX에서 프런트매터 사용에 대한 지원이 포함되어 있습니다. Markdown 파일에서와 마찬가지로 프런트매터 속성을 추가하면 이러한 변수에 액세스하여 템플릿, [`layout` 컴포넌트](#프런트매터-layout), [파일을 다른 곳으로 가져올 때](#markdown-가져오기) 명명된 속성으로 사용할 수 있습니다. - -```mdx title="/src/pages/posts/post-1.mdx" ---- -layout: '../../layouts/BlogPostLayout.astro' -title: 'My first MDX post' ---- - -# {frontmatter.title} -``` - -### MDX에서 컴포넌트 사용 - -MDX 통합을 설치한 후 다른 Astro 컴포넌트에서 사용하는 것처럼 [Astro 컴포넌트](/ko/basics/astro-components/#컴포넌트-props)와 [UI 프레임워크 컴포넌트](/ko/guides/framework-components/#프레임워크-컴포넌트-사용)를 MDX (`.mdx`) 파일로 가져와 사용할 수 있습니다. - -필요한 경우 UI 프레임워크 컴포넌트에 `client:directive`를 포함하는 것을 잊지 마세요! - -[MDX 문서](https://mdxjs.com/docs/what-is-mdx/#esm)에서 가져오기 및 내보내기 구문 사용에 대한 추가 예시를 참조하세요. - -```mdx title="src/pages/about.mdx" {5-6} /<.+\/>/ ---- -layout: ../layouts/BaseLayout.astro -title: About me ---- -import Button from '../components/Button.astro'; -import ReactCounter from '../components/ReactCounter.jsx'; - -I live on **Mars** but feel free to