콜아웃, 코드 블록 및 다이어그램 예시

질이 높은 기술 문서를 쓰려면 명확한 글만으로는 부족하고, 눈에 띄는 핵심 강조, 형식이 정돈된 코드 예제, 한눈에 들어오는 구성도도 필요합니다. 이 페이지의 모든 예제는 실제로 적용되는 문법이며, 여러분이 보는 효과가 곧 렌더링 결과입니다. 이 글 자체가 살아 있는 예제 페이지입니다.

---

1. 네 가지 색상 콜아웃

콜아웃은 삼중 콜론 문법을 사용합니다. :::유형으로 시작하고 :::로 끝내며 그 사이에 내용을 씁니다. 이 사이트는 Starlight 기반으로 note, tip, caution, danger 네 가지 유형을 지원합니다.

문법과 실제 효과 대조

노트

note(보충 설명): 배경 지식을 소개하거나 설계 세부 사항을 보완하거나 선행 의존성을 안내할 때 사용합니다.

팁

tip(실용 팁): 조작 효율을 높이는 요령이나 모범 사례를 공유할 때 사용합니다.

주의

caution(주의 경고): 존재할 수 있는 호환성 충돌, 잠재적 오류, 특별히 유의해야 하는 조작을 알릴 때 사용합니다.

위험

danger(고위험 경고): 데이터 손실, 프로덕션 환경 덮어쓰기, 되돌릴 수 없는 조작과 관련된 최고 수준의 경고입니다.

콜아웃 안에는 무엇이든 넣을 수 있습니다

콜아웃 안에서는 목록, 코드 블록, 표 등의 문법을 계속 사용할 수 있습니다:

설치 속도 높이기

pnpm으로 의존성을 설치하면 npm보다 훨씬 빠릅니다:

npm install -g pnpm

주의

흔한 두 가지 잘못된 표기법이니 피하도록 주의하세요:

• GitHub 스타일의 > [!NOTE] 인용 블록 문법은 지원되지 않으며 그대로 평범한 인용 블록으로 표시됩니다;
• :::important와 :::warning은 이 사이트가 지원하는 유형이 아닙니다, 오류는 나지 않지만 조용히 일반 단락으로 렌더링되어 콜아웃 스타일이 전혀 적용되지 않습니다.

GitHub 문서를 옮겨 올 때는 > [!NOTE]를 :::note로, > [!WARNING]를 :::caution으로, > [!CAUTION]를 :::danger로 고쳐 쓰세요.

---

2. 코드 블록 고급 레이아웃

2.1 파일 이름 제목과 지정 행 하이라이트

코드 펜스 첫 줄에 title="파일 경로"를 표기하고 {행 번호}로 핵심 행을 하이라이트합니다:

```typescript title="src/config/site.ts" {2}
export const siteConfig = {
  name: 'EpoCanvas Docs', // 이 행은 하이라이트 배경으로 강조됩니다
  version: '1.2.0',
};
```

렌더링 효과:

src/config/site.ts

export const siteConfig = {
  name: 'EpoCanvas Docs',
  version: '1.2.0',
};

2.2 증분 코드 비교 (diff)

설정 업그레이드나 코드 리팩터링을 보여 줄 때 diff 언어를 사용하면 변경 사항이 한눈에 들어오며, -로 시작하는 행은 삭제, +로 시작하는 행은 추가로 표시됩니다:

```diff
  export default defineConfig({
-   site: 'http://localhost:3000',
+   site: 'https://docs.epocanvas.com',
  });
```

렌더링 효과:

export default defineConfig({
  site: 'http://localhost:3000',
  site: 'https://docs.epocanvas.com',
});

2.3 터미널 명령어

bash, sh, powershell 등 터미널 언어는 터미널 스타일의 어두운 테두리로 렌더링됩니다:

pnpm run build

---

3. 다이어그램은 어떻게 삽입하나요?

현재 버전은 Mermaid 같은 텍스트 다이어그램 렌더링을 내장하지 않습니다. ```mermaid 펜스를 직접 쓰면 일반 코드 블록으로 소스만 표시되고 그래프가 생성되지 않습니다.

권장하는 방법은 mermaid.live 같은 도구에서 작성하여 SVG 벡터 이미지로 내보내고, public/images/canvas/에 저장한 뒤 이미지 문법으로 삽입하는 것입니다. 이 사이트의 아키텍처 구성도, 언어 전환 흐름도가 모두 이런 방식으로 만들어졌습니다:

그림: SVG 이미지 형태로 삽입된 아키텍처 구성도로, 아무리 확대해도 흐려지지 않습니다.

Mermaid 소스가 정말로 직접 그래프로 렌더링되도록 하려면 프로젝트에 추가 렌더링 플러그인(예: rehype-mermaid)을 도입해야 하며, 이는 2차 개발 범위에 속하므로 유지 관리 비용을 평가한 뒤에 도입하세요.

---

4. 기타 실용적인 레이아웃

• 행내 코드: pnpm run dev, 테마 색 고정폭 글꼴로 렌더링됩니다;
• 키보드 키: Ctrl + K, 키캡 스타일로 렌더링됩니다;
• 작업 목록:

- [x] 문법 하이라이트 지원
- [x] 한 번 클릭 복사 지원
- [ ] 내장 Mermaid 렌더링(계획 중)

체크 상태가 표시된 목록 항목으로 렌더링됩니다.

4.1 각주

자료 출처나 보충 설명을 표시해야 할 때는 GFM 각주 문법을 사용할 수 있습니다:

정적 인덱스는 빌드 시점에 Pagefind가 생성합니다[^pagefind].

[^pagefind]: [Pagefind 공식 문서](https://pagefind.app/) — 정적 사이트용 로컬 검색 라이브러리.

렌더링 효과: 본문 끝에 번호가 붙은 위첨자 이동 표식¹이 나타나며, 클릭하면 페이지 하단의 각주 목록으로 부드럽게 이동합니다.

콜아웃, 코드 표기, 구성도를 적절히 활용하면 기술 문서의 읽기 편안함과 전문성을 크게 높일 수 있습니다. 완전한 문법 규약은 **렌더링 규칙 상세**를 읽어 보세요.

각주

1. 이것이 바로 이 페이지 하단에 렌더링된 각주 본체입니다. ↩