@astrojs/ markdoc
이 Astro 통합 을 통해 Markdoc을 사용하여 컴포넌트, 페이지 및 콘텐츠 컬렉션 항목을 생성할 수 있습니다.
왜 Markdoc인가?
섹션 제목: 왜 Markdoc인가?Markdoc을 사용하면 Astro 컴포넌트를 사용하여 Markdown을 향상할 수 있습니다. Markdoc에서 작성된 기존 콘텐츠가 있는 경우 이 통합을 통해 콘텐츠 컬렉션을 사용하여 해당 파일을 Astro 프로젝트로 가져올 수 있습니다.
Astro에는 공식 통합 설정을 자동화하는 astro add
명령이 포함되어 있습니다. 원하는 경우 대신 통합을 수동으로 설치할 수 있습니다.
새 터미널 창에서 다음 명령 중 하나를 실행합니다.
문제가 발생하면 GitHub에 언제든지 보고하고 아래 수동 설치 단계를 시도해 보세요.
수동 설치
섹션 제목: 수동 설치먼저 @astrojs/markdoc
패키지를 설치하세요.
그런 다음 integrations
속성을 사용하여 astro.config.*
파일에 통합을 적용합니다.
VS Code 편집기 통합
섹션 제목: VS Code 편집기 통합VS Code를 사용하는 경우 구성된 태그에 대한 구문 강조 및 자동 완성을 포함하는 공식 Markdoc 언어 확장이 있습니다. 자세한 내용은 GitHub에서 언어 서버를 참조하세요.
확장 기능을 설정하려면 다음 내용으로 프로젝트 루트에 markdoc.config.json
파일을 생성하세요.
schema
객체를 사용하여 markdoc.config.mjs
파일을 구성 파일로 설정하고 path
속성을 사용하여 Markdoc 파일이 저장되는 위치를 정의합니다. Markdoc은 콘텐츠 컬렉션에만 적용되므로 src/content
를 사용할 수 있습니다.
사용하기
섹션 제목: 사용하기Markdoc 파일은 콘텐츠 컬렉션에서만 사용할 수 있습니다. .mdoc
확장자를 사용하여 콘텐츠 컬렉션에 항목을 추가합니다.
디렉터리src/
디렉터리content/
디렉터리docs/
- why-markdoc.mdoc
- quick-start.mdoc
그런 다음 콘텐츠 컬렉션 API를 사용하여 컬렉션을 쿼리하세요.
Markdoc 변수 전달
섹션 제목: Markdoc 변수 전달콘텐츠에 변수를 전달해야 할 수도 있습니다. 이는 A/B 테스트와 같은 SSR 매개변수를 전달할 때 유용합니다.
변수는 Content
컴포넌트를 통해 props로 전달될 수 있습니다.
이제 abTestGroup
을 docs/why-markdoc.mdoc
에서 변수로 사용할 수 있습니다.
모든 Markdoc 파일에 전역 변수를 생성하기 위해 markdoc.config.mjs|ts
파일에서 variables
속성을 사용할 수 있습니다.
Markdoc 콘텐츠에서 프론트매터에 액세스
섹션 제목: Markdoc 콘텐츠에서 프론트매터에 액세스entry 객체의 data
속성을 콘텐츠를 렌더링하기 위한 변수로 전달하여 프론트매터에 액세스할 수 있습니다.
이제 Markdoc에서 $frontmatter
로 액세스할 수 있습니다.
컴포넌트 렌더링
섹션 제목: 컴포넌트 렌더링@astrojs/markdoc
은 Markdoc의 모든 기능을 사용하여 UI 컴포넌트를 콘텐츠에 연결하는 구성 옵션을 제공합니다.
Astro 컴포넌트를 Markdoc 태그로 사용
섹션 제목: Astro 컴포넌트를 Markdoc 태그로 사용.astro
컴포넌트에 매핑되는 Markdoc 태그를 구성할 수 있습니다. 프로젝트 루트에 markdoc.config.mjs|ts
파일을 생성하고 tag
속성을 구성하여 새 태그를 추가할 수 있습니다.
이 예시는 Aside
컴포넌트를 렌더링하고 type
prop이 문자열로 전달되도록 허용합니다.
이제 이 컴포넌트는 Markdoc 파일에서 {% along %}
태그를 통해 사용할 수 있습니다. 하위 항목은 컴포넌트의 기본 슬롯으로 전달됩니다.
클라이언트 측 UI 컴포넌트 사용
섹션 제목: 클라이언트 측 UI 컴포넌트 사용태그와 노드는 .astro
파일로 제한됩니다. Markdoc에 클라이언트 측 UI 컴포넌트를 포함하려면 원하는 client:
지시어와 함께 프레임워크 컴포넌트를 렌더링하는 래퍼 .astro
컴포넌트를 사용하세요.
이 예시는 React Aside.tsx
컴포넌트를 ClientAside.astro
컴포넌트로 래핑합니다.
이제 이 Astro 컴포넌트는 구성의 모든 태그 또는 노드에 대한 render
prop에 전달될 수 있습니다.
npm 패키지 및 TypeScript 파일의 Astro 컴포넌트 사용
섹션 제목: npm 패키지 및 TypeScript 파일의 Astro 컴포넌트 사용TypeScript 또는 JavaScript 파일에서 명명된 내보내기로 노출된 Astro 컴포넌트를 사용해야 할 수도 있습니다. 이는 npm 패키지와 디자인 시스템을 사용할 때 일반적입니다.
가져오기 이름을 component()
함수의 두 번째 인수로 전달할 수 있습니다.
그러면 내부적으로 다음 import 문이 생성됩니다.
Markdoc Partials
섹션 제목: Markdoc Partials{% partial %}
태그를 사용하면 Markdoc 콘텐츠에서 다른 .mdoc
파일을 렌더링할 수 있습니다.
이는 여러 문서에서 콘텐츠를 재사용하는 데 유용하며, 컬렉션 스키마를 따르지 않는 .mdoc
콘텐츠 파일을 가질 수 있습니다.
partial 파일이나 디렉터리에는 밑줄 _
접두사를 사용합니다. 이는 콘텐츠 컬렉션 쿼리에서 partial 파일을 제외합니다.
이 예시는 블로그 컬렉션 항목에서 사용되는 바닥글의 Markdoc partial을 보여줍니다.
블로그 게시물 항목 하단에 바닥글을 렌더링하려면 {% partial %}
태그를 사용합니다. 상대 경로 또는 가져오기 별칭을 사용하여 file
속성에 파일의 경로를 적용합니다.
구문 강조
섹션 제목: 구문 강조@astrojs/markdoc
은 코드 블록을 강조 표시하는 Shiki 및 Prism 확장 프로그램을 제공합니다.
Shiki
섹션 제목: Shikiextends
속성을 사용하여 Markdoc 구성에 shiki()
확장을 적용합니다. 선택적으로 shiki 구성 객체를 전달할 수 있습니다:
Prism
섹션 제목: Prismextends
속성을 사용하여 Markdoc 구성에 prism()
확장을 적용합니다.
사용자 정의 Markdoc 노드 / 요소
섹션 제목: 사용자 정의 Markdoc 노드 / 요소단락 및 굵은 텍스트와 같은 표준 Markdown 요소를 Astro 컴포넌트로 렌더링할 수 있습니다. 이를 위해 Markdoc 노드를 구성할 수 있습니다. 특정 노드가 속성을 받으면 해당 속성을 컴포넌트 props로 사용할 수 있습니다.
이 예시는 사용자 정의 Quote.astro
컴포넌트를 사용하여 인용문을 렌더링합니다.
사용자 정의 제목
섹션 제목: 사용자 정의 제목@astrojs/markdoc
는 제목에 앵커 링크를 자동으로 추가하고 콘텐츠 컬렉션 API를 통해 headings
목록을 생성합니다. 제목을 렌더링하는 방법을 추가로 사용자 정의하려면 Astro 컴포넌트를 Markdoc 노드로 적용하세요.
이 예시에서는 render
속성을 사용하여 Heading.astro
컴포넌트를 렌더링합니다.
모든 Markdown 제목은 Heading.astro
컴포넌트를 렌더링하고 다음 속성
을 컴포넌트 props로 전달합니다.
level: number
레벨 1 - 6의 제목id: string
제목의 텍스트 콘텐츠에서 생성된id
입니다. 이는 콘텐츠render()
함수에 의해 생성된slug
에 해당합니다.
예를 들어 ### Level 3 heading!
라는 제목은 level: 3
및 id: 'level-3-heading'
을 컴포넌트 props로 전달합니다.
사용자 정의 이미지 컴포넌트
섹션 제목: 사용자 정의 이미지 컴포넌트Astro의 <Image />
컴포넌트는 Markdoc에서 직접 사용할 수 없습니다. 그러나 기본 ![]()
이미지 구문이 사용될 때마다 기본 이미지 노드를 재정의하도록 Astro 컴포넌트를 구성하거나 추가 이미지 속성을 지정할 수 있도록 사용자 정의 Markdoc 태그로 구성할 수 있습니다.
Markdoc의 기본 이미지 노드 재정의
섹션 제목: Markdoc의 기본 이미지 노드 재정의기본 이미지 노드를 재정의하려면 표준 <img>
대신 렌더링되도록 .astro
컴포넌트를 구성할 수 있습니다.
-
사용자 정의
MarkdocImage.astro
컴포넌트를 구축하여 이미지의 필수src
및alt
속성을<Image />
컴포넌트에 전달합니다. -
<Image />
컴포넌트에는![]()
구문을 사용하여 제공할 수 없는 원격 이미지에 대한width
및height
가 필요합니다. 원격 이미지를 사용할 때 오류를 방지하려면 원격 URLsrc
를 발견했을 때 표준 HTML<img>
태그를 렌더링하도록 컴포넌트를 업데이트하세요. -
기본 이미지 노드를 재정의하고
MarkdocImage.astro
를 렌더링하도록 Markdoc을 구성합니다. -
모든
.mdoc
파일의 기본 이미지 구문은 이제<Image />
컴포넌트를 사용하여 로컬 이미지를 최적화합니다. 원격 이미지는 계속 사용할 수 있지만 Astro의<Image />
컴포넌트에 의해 렌더링되지는 않습니다.
사용자 정의 Markdoc 이미지 태그 생성
섹션 제목: 사용자 정의 Markdoc 이미지 태그 생성Markdoc image
태그를 사용하면 ![]()
구문으로는 불가능한 이미지의 추가 속성을 설정할 수 있습니다. 예를 들어 사용자 정의 이미지 태그를 사용하면 width
및 height
가 필요한 원격 이미지에 Astro의 <Image />
컴포넌트를 사용할 수 있습니다.
다음 단계에서는 이미지를 최적화하기 위해 Astro <Image />
컴포넌트를 사용하여 캡션이 있는 <figure>
요소를 표시하는 사용자 정의 Markdoc 이미지 태그를 생성합니다.
-
필요한 props을 받아 캡션이 포함된 이미지를 렌더링하려면
MarkdocFigure.astro
컴포넌트를 생성합니다. -
Astro 컴포넌트를 렌더링하도록 사용자 정의 이미지 태그를 구성합니다.
-
Markdoc 파일의
image
태그를 사용하여 캡션이 있는 그림을 표시하고 컴포넌트에 필요한 모든 속성을 제공합니다.
markdoc.config.mjs|ts
파일은 태그 및 함수를 포함한 모든 Markdoc 구성 옵션을 허용합니다.
markdoc.config.mjs|ts
파일의 기본 내보내기에서 다음 옵션을 전달할 수 있습니다.
이제 모든 Markdoc 콘텐츠 항목에서 이 함수를 호출할 수 있습니다.
루트 HTML 요소 설정
섹션 제목: 루트 HTML 요소 설정Markdoc은 기본적으로 <article>
태그로 문서를 래핑합니다. 이는 document
Markdoc 노드에서 변경할 수 있습니다. 래퍼 요소를 제거하려는 경우 HTML 요소 이름 또는 null
을 허용합니다.
통합 구성 옵션
섹션 제목: 통합 구성 옵션Astro Markdoc 통합은 markdoc.config.js
파일을 통해 사용할 수 없는 Markdoc 옵션 및 기능 구성을 처리합니다.
allowHTML
섹션 제목: allowHTMLMarkdoc 태그 및 노드와 함께 HTML 마크업 작성을 활성화합니다.
기본적으로 Markdoc은 HTML 마크업을 의미 있는 콘텐츠로 인식하지 않습니다.
콘텐츠와 함께 HTML 요소를 포함할 수 있는 Markdown과 유사한 경험을 얻으려면 markdoc
통합 옵션으로 allowHTML:true
를 설정하세요. 이렇게 하면 Markdoc 마크업에서 HTML 구문 분석이 활성화됩니다.
allowHTML
이 활성화되면 Markdoc 문서의 HTML 마크업이 실제 HTML 요소 (<script>
포함)로 렌더링되어 XSS와 같은 공격 벡터가 가능해집니다. 모든 HTML 마크업이 신뢰할 수 있는 소스에서 나온 것인지 확인하세요.
ignoreIndentation
섹션 제목: ignoreIndentation기본적으로 공백 4개로 들여쓰기된 모든 콘텐츠는 코드 블록으로 처리됩니다. 불행하게도 이 동작은 복잡한 구조를 가진 문서의 가독성을 향상시키기 위해 임의 수준의 들여쓰기를 사용하기 어렵게 만듭니다.
Markdoc에서 중첩 태그를 사용할 때 깊이 수준이 명확하도록 태그 내부의 내용을 들여쓰는 것이 도움이 될 수 있습니다. 임의 들여쓰기를 지원하려면 들여쓰기 기반 코드 블록을 비활성화하고 들여쓰기 기반 코드 블록을 설명하는 몇 가지 다른 markdown-it 구문 분석 규칙을 수정해야 합니다. 이러한 변경 사항은 ignoreIndentation 옵션을 활성화하여 적용할 수 있습니다.
- Astro Markdoc 시작 템플릿은 Astro 프로젝트에서 Markdoc 파일을 사용하는 방법을 보여줍니다.