withastro · yanthomasdev · Oct 24, 2025 · Oct 24, 2025 · Oct 24, 2025 · Oct 24, 2025
diff --git a/src/content/docs/ko/guides/content-collections.mdx b/src/content/docs/ko/guides/content-collections.mdx
@@ -418,6 +418,8 @@ const { Content, headings } = await render(entry);
 <Content />
 ```
 
+<ReadMore>MDX 항목을 다룰 때, [사용자 정의 컴포넌트를 `<Content />`에 전달](/ko/guides/integrations-guide/mdx/#components를-mdx-콘텐츠로-전달하기)하여 HTML 요소를 사용자 정의 대안으로 대체할 수도 있습니다.</ReadMore>
+
 #### 콘텐츠를 props로 전달
 
 컴포넌트는 컬렉션 항목 전체를 prop으로 전달할 수도 있습니다.

diff --git a/src/content/docs/ko/guides/integrations-guide/mdx.mdx b/src/content/docs/ko/guides/integrations-guide/mdx.mdx
@@ -88,7 +88,7 @@ export default defineConfig({
 
 표준 MDX 기능 사용에 대해 알아보려면 [MDX 문서](https://mdxjs.com/docs/what-is-mdx/)를 참조하세요.
 
-## Astro의 MDX
+## Astro에서 MDX 사용하기
 
 MDX 통합을 추가하면 JSX 변수, 표현식, 컴포넌트로 Markdown을 작성하는 기능이 향상됩니다.
 
@@ -150,13 +150,12 @@ const posts = Object.values(matches);
 - **`<Content />`** - 파일의 렌더링된 전체 콘텐츠를 반환하는 컴포넌트입니다.
 - **(모든 `export` 값)** - MDX 파일은 `export` 문을 사용하여 데이터를 내보낼 수도 있습니다.
 
-### MDX에서 프런트매터 변수 사용
+### MDX에서 프런트매터 변수 사용하기
 
 기본적으로 Astro MDX 통합은 MDX에서 프런트매터를 사용하는 것을 지원합니다. Markdown 파일과 마찬가지로 프런트매터 속성을 추가하면 이러한 변수를 템플릿에서 사용할 수 있으며, 다른 곳에서 파일을 가져올 때 명명된 속성으로도 사용할 수 있습니다.
 
 ```mdx title="/src/blog/posts/post-1.mdx"
 ---
-layout: '../../layouts/BlogPostLayout.astro'
 title: 'My first MDX post'
 author: 'Houston'
 ---
@@ -166,7 +165,7 @@ author: 'Houston'
 Written by: {frontmatter.author}
 ```
 
-### MDX에서 컴포넌트 사용
+### MDX에서 컴포넌트 사용하기
 
 MDX 통합을 설치한 후에는 다른 Astro 컴포넌트에서 사용하는 것과 마찬가지로 MDX (`.mdx`) 파일에서 [Astro 컴포넌트](/ko/basics/astro-components/)와 [UI 프레임워크 컴포넌트](/ko/guides/framework-components/#프레임워크-컴포넌트-사용) 모두를 가져와서 사용할 수 있습니다.
 
@@ -183,51 +182,70 @@ import ReactCounter from '../components/ReactCounter.jsx';
 I just started my new Astro blog!
 
 Here is my counter component, working in MDX:
-
 <ReactCounter client:load />
 ```
 
-#### 가져온 MDX를 사용하는 사용자 정의 컴포넌트
+#### HTML 요소에 사용자 정의 컴포넌트 할당하기
+
+MDX를 사용하면 표준 HTML 요소 대신 Markdown 구문을 사용자 정의 컴포넌트에 매핑할 수 있습니다. 이렇게 하면 표준 Markdown 구문으로 작성하되 선택한 요소에 특별한 컴포넌트 스타일을 적용할 수 있습니다.
 
-가져온 MDX 콘텐츠를 렌더링할 때 [사용자 정의 컴포넌트](#html-요소에-사용자-정의-컴포넌트-할당)는 `components` 속성을 통해 전달될 수 있습니다.
+예를 들어, `<blockquote>` 콘텐츠에 사용자 정의 스타일을 제공하는 `Blockquote.astro` 컴포넌트를 만들 수 있습니다.
 
-```astro title="src/pages/page.astro" "components={{...components, h1: Heading }}"
+```astro title="src/components/Blockquote.astro"
 ---
-import { Content, components } from '../content.mdx';
-import Heading from '../Heading.astro';
+const props = Astro.props;
 ---
-<!-- # 구문에 대한 사용자 정의 <h1>을 생성합니다. _그리고_ `content.mdx`에 정의된 모든 사용자 정의 컴포넌트에 적용합니다. -->
-<Content components={{...components, h1: Heading }} />
+<blockquote {...props} class="bg-blue-50 p-4">
+  <span class="text-4xl text-blue-600 mb-2">“</span>
+  <slot /> <!-- 하위 콘텐츠를 위해 `<slot/>`을 추가해야 합니다! -->
+</blockquote>
+```
+
+사용자 정의 컴포넌트를 `.mdx` 파일로 가져온 다음 표준 HTML 요소를 사용자 정의 컴포넌트에 매핑하는 `components` 객체를 내보냅니다.
+
+```mdx title="src/blog/posts/post-1.mdx"
+import Blockquote from '../components/Blockquote.astro';
+export const components = {blockquote: Blockquote}
+
+> This quote will be a custom Blockquote
 ```
 
+사용자 정의 컴포넌트로 덮어쓸 수 있는 HTML 요소의 전체 목록은 [MDX 웹사이트](https://mdxjs.com/table-of-components/)를 참조하세요.
+
 :::note
 MDX 파일에서 정의되어 내보내진 사용자 정의 컴포넌트는 가져온 다음 `components` 속성을 통해 `<Content />` 컴포넌트로 다시 전달되어야 합니다.
 :::
 
-#### HTML 요소에 사용자 정의 컴포넌트 할당
+#### `components`를 MDX 콘텐츠로 전달하기
 
-MDX를 사용하면 표준 HTML 요소 대신 Markdown 구문을 사용자 정의 컴포넌트에 매핑할 수 있습니다. 이렇게 하면 표준 Markdown 구문으로 작성하되 선택한 요소에 특별한 컴포넌트 스타일을 적용할 수 있습니다.
+가져온 MDX 콘텐츠를 `<Content />` 컴포넌트를 사용하여 렌더링할 때 (콘텐츠 컬렉션을 사용한 MDX 항목 렌더링 포함), `components` prop을 통해 사용자 정의 컴포넌트를 전달할 수 있습니다. 이러한 컴포넌트는 `<Content />` 컴포넌트에서 사용할 수 있도록 먼저 가져와야 합니다.
 
-사용자 정의 컴포넌트를 `.mdx` 파일로 가져온 다음 표준 HTML 요소를 사용자 정의 컴포넌트에 매핑하는 `components` 객체를 내보냅니다:
+`components` 객체는 HTML 요소 이름(`h1`, `h2`, `blockquote` 등)을 사용자 정의 컴포넌트에 매핑합니다. 또한 스프레드 연산자(`...`)를 사용하여 [MDX 파일 자체에서 내보낸 모든 컴포넌트](#html-요소에-사용자-정의-컴포넌트-할당하기)를 포함할 수 있으며, 이 또한 MDX 파일에서 `components`로 가져와야 합니다.
 
-```mdx title="src/blog/posts/post-1.mdx"
-import Blockquote from '../components/Blockquote.astro';
-export const components = {blockquote: Blockquote}
+Astro 컴포넌트에서 사용하기 위해 단일 파일에서 MDX를 직접 가져오는 경우, `Content` 컴포넌트와 MDX 파일에서 내보낸 모든 컴포넌트를 모두 가져와야 합니다.
 
-> This quote will be a custom Blockquote
+```astro title="src/pages/page.astro" "components={{...components, h1: Heading }}" {2}
+---
+import { Content, components } from '../content.mdx';
+import Heading from '../Heading.astro';
+---
+<!-- '#' 구문에서 사용할 사용자 정의 <h1>을 생성하고, `content.mdx`에 정의된 사용자 정의 컴포넌트를 적용합니다. -->
+<Content components={{...components, h1: Heading }} />
 ```
 
+MDX 파일이 콘텐츠 컬렉션 항목인 경우, `astro:content`의 `render()` 함수를 사용하여 `<Content />` 컴포넌트에 접근하세요.
 
-```astro title="src/components/Blockquote.astro"
+다음은 `<h1>` HTML 요소 대신 사용될 사용자 정의 제목을 `components` prop을 통해 `<Content />` 컴포넌트에 전달하는 예시입니다.
+
+```astro title="src/pages/blog/post-1.astro" ins="components={{ h1: CustomHeading }}"
 ---
-const props = Astro.props;
+import { getEntry, render } from 'astro:content';
+import CustomHeading from '../../components/CustomHeading.astro';
+const entry = await getEntry('blog', 'post-1');
+const { Content } = await render(entry);
 ---
-<blockquote {...props} class="bg-blue-50 p-4">
-  <span class="text-4xl text-blue-600 mb-2">“</span>
-  <slot /> <!-- 하위 콘텐츠를 위해 `<slot/>`을 추가해야 합니다! -->
-</blockquote>
+<Content components={{ h1: CustomHeading }} />
 ```
-사용자 정의 컴포넌트로 덮어쓸 수 있는 HTML 요소의 전체 목록은 [MDX 웹사이트](https://mdxjs.com/table-of-components/)를 참조하세요.
 
 ## 구성
 
@@ -380,7 +398,7 @@ export default defineConfig({
 
 이전에는 `customComponentNames`로 알려졌습니다.
 
-MDX 최적화 프로그램이 [컴포넌트 prop을 통해 가져온 MDX 콘텐츠에 전달된 사용자 정의 컴포넌트](/ko/guides/integrations-guide/mdx/#가져온-mdx를-사용하는-사용자-정의-컴포넌트)와 같은 특정 요소 이름을 처리하지 못하도록 방지하는 `optimize`의 선택적 속성입니다.
+MDX 최적화 프로그램이 [컴포넌트 prop을 통해 가져온 MDX 콘텐츠에 전달된 사용자 정의 컴포넌트](#components를-mdx-콘텐츠로-전달하기)와 같은 특정 요소 이름을 처리하지 못하도록 방지하는 `optimize`의 선택적 속성입니다.
 
 최적화 프로그램이 콘텐츠를 정적 문자열로 변환하므로 동적으로 렌더링해야 하는 사용자 정의 컴포넌트가 중단되기 때문에 최적화에서 이러한 컴포넌트를 제외해야 합니다.
 
@@ -414,9 +432,9 @@ export default defineConfig({
 });
 ```
 
-MDX 파일이 [`export const components = { ... }`를 사용하여 사용자 정의 컴포넌트를 구성](/ko/guides/integrations-guide/mdx/#html-요소에-사용자-정의-컴포넌트-할당)하는 경우, 이 옵션을 수동으로 구성할 필요가 없습니다. 최적화 프로그램은 이를 자동으로 감지합니다.
+MDX 파일이 [`export const components = { ... }`를 사용하여 사용자 정의 컴포넌트를 구성](/ko/guides/integrations-guide/mdx/#html-요소에-사용자-정의-컴포넌트-할당하기)하는 경우, 이 옵션을 수동으로 구성할 필요가 없습니다. 최적화 프로그램은 이를 자동으로 감지합니다.
 
-## 예
+## 예시
 
 [Astro MDX 시작 템플릿](https://github.com/withastro/astro/tree/latest/examples/with-mdx)은 Astro 프로젝트에서 MDX 파일을 사용하는 방법을 보여줍니다.
 

diff --git a/src/content/docs/ko/guides/troubleshooting.mdx b/src/content/docs/ko/guides/troubleshooting.mdx
@@ -115,7 +115,7 @@ Astro 컴포넌트는 서버에서 실행되므로 프런트매터에서 이러
 
 ### 내 컴포넌트가 렌더링되지 않습니다.
 
-먼저, [`.astro` 컴포넌트 스크립트](/ko/basics/astro-components/#컴포넌트-스크립트) 또는 [`.mdx` 파일](/ko/guides/integrations-guide/mdx/#mdx에서-컴포넌트-사용)에서 **컴포넌트를 가져왔**는지 확인하세요.
+먼저, [`.astro` 컴포넌트 스크립트](/ko/basics/astro-components/#컴포넌트-스크립트) 또는 [`.mdx` 파일](/ko/guides/integrations-guide/mdx/#mdx에서-컴포넌트-사용하기)에서 **컴포넌트를 가져왔**는지 확인하세요.
 
 그런 다음 가져오기 (import) 문을 확인하세요.
 

diff --git a/src/content/docs/ko/reference/directives-reference.mdx b/src/content/docs/ko/reference/directives-reference.mdx
@@ -114,7 +114,7 @@ import api from '../db/api.js';
 
 기본적으로 UI 프레임워크 컴포넌트는 클라이언트에서 수화되지 않습니다. `client:*` 지시어가 제공되지 않으면 HTML이 JavaScript 없이 페이지에 렌더링됩니다.
 
-클라이언트 지시어는 `.astro` 컴포넌트로 직접 가져온 UI 프레임워크 컴포넌트에서만 사용할 수 있습니다. [동적 태그](/ko/reference/astro-syntax/#동적-태그)와 [`components` prop을 통해 전달된 사용자 정의 컴포넌트](/ko/guides/integrations-guide/mdx/#가져온-mdx를-사용하는-사용자-정의-컴포넌트)를 사용할 때는 수화 지시어가 지원되지 않습니다.
+클라이언트 지시어는 `.astro` 컴포넌트로 직접 가져온 UI 프레임워크 컴포넌트에서만 사용할 수 있습니다. [동적 태그](/ko/reference/astro-syntax/#동적-태그)와 [`components` prop을 통해 전달된 사용자 정의 컴포넌트](/ko/guides/integrations-guide/mdx/#components를-mdx-콘텐츠로-전달하기)를 사용할 때는 수화 지시어가 지원되지 않습니다.
 
 ### `client:load`