빠른 비교

자세한 설정은 [배포 가이드](./deploy.md)를 참고하세요.

import SharedWarning from './shared-warning.mdx'

<SharedWarning />

경계

Markdown 자체에는 include 문법이 없다

CommonMark 기준 Markdown은 다른 Markdown 파일의 내용을 현재 파일 안으로 끼워 넣는 표준 문법을 제공하지 않습니다. [문서](./file.md)는 링크일 뿐이고, 파일 내용을 펼쳐 넣지는 않습니다.

[공통 주의사항](./shared-warning.md)

따라서 GitHub README에서 어떤 문서를 자동으로 포함하려면 Markdown 문법만으로는 부족합니다. include가 필요하다면 빌드 도구, 문서 사이트 프레임워크, MDX 컴포넌트 중 하나를 명시적으로 선택해야 합니다.

include는 중복을 줄이지만 문서 경계를 흐릴 수 있다

공통 경고, 제품 제한, 설치 전 요구사항처럼 여러 문서에 반복되는 내용은 include로 관리하고 싶어집니다. 하지만 include가 많아지면 원본 파일만 봐서는 실제 렌더링 결과를 알기 어려워지고, 링크 anchor와 heading 단계가 포함 위치에 따라 달라질 수 있습니다.

include 사용 후보
- 여러 문서에 완전히 동일한 경고 문구
- 버전별로 공유되는 설치 요구사항
- 법적 고지나 라이선스 문구

링크로 남기는 편이 나은 것
- 독립적으로 읽어야 하는 긴 가이드
- 문맥에 따라 설명이 달라지는 절차
- heading 구조가 복잡한 문서

MDX import는 문서가 코드 빌드에 묶인다는 뜻이다

MDX에서는 다른 .mdx 파일이나 컴포넌트를 import해 재사용할 수 있습니다. 이 방식은 문서 시스템을 강력하게 만들지만, 일반 Markdown 렌더러에서는 동작하지 않습니다. GitHub에서 바로 읽히는 문서와 사이트 빌드용 문서를 같은 파일로 유지하려면 MDX 문법 사용을 신중히 제한해야 합니다.

import ApiNotice from '../components/ApiNotice.mdx'

API 사용 전:

<ApiNotice />

MDX include는 문서 작성 규칙이 아니라 애플리케이션 빌드 규칙에 가깝습니다. 컴포넌트 props, import 경로, 번들링 오류까지 문서 검증 범위에 들어옵니다.

선택 기준

주의할 점

공통 조각 안에 상대 링크를 넣으면 포함 위치에 따라 링크 기준 경로가 달라질 수 있습니다. include용 조각은 링크를 최소화하거나, 빌드 시스템이 경로를 어떻게 해석하는지 명확히 확인해야 합니다.