렌더링 규칙 상세

최종 업데이트: 2026. 9. 22. / EpoCanvas 공식 아키텍처 사양

이 페이지는 EpoCanvas Docs의 렌더링 규칙을 완전하게 설명합니다. 한 편의 Markdown 파일이 어떤 처리 단계를 거치는지, 각 문법이 어떤 효과로 렌더링되는지, 어떤 문법이 지원되지 않는지 다룹니다. 문서를 쓰기 전에 한 번 훑어 보면 대부분의 레이아웃 문제를 피할 수 있습니다.

렌더링 파이프라인: .md 파일에서 온라인 페이지까지

EpoCanvas Docs Markdown 렌더링 파이프라인 구성도: Markdown 소스 스캔, GFM AST 파싱, 코드 하이라이트, 7개 커스텀 컴포넌트 레이아웃 조립에서 정적 HTML과 Pagefind 인덱스 생성까지의 완전한 5단계 흐름

그림: Markdown 렌더링 파이프라인의 5단계 흐름. 각 단계는 빌드 시점에 순서대로 실행되며, 빌드 산출물은 순수 정적 파일이고 클라이언트에는 런타임 프레임워크 비용이 전혀 없습니다.

한 편의 Markdown 파일이 저장된 뒤 독자에게 보이기까지 다음 다섯 단계를 거칩니다:

콘텐츠 수집: Astro가 시작하거나 빌드할 때 src/content/docs/ 디렉터리를 스캔하여 각 .md / .mdx 파일을 콘텐츠 항목으로 등록하고 Frontmatter를 검증합니다(title이 없으면 바로 오류가 발생합니다).
Markdown 컴파일: 본문은 Markdown 컴파일러(GFM 확장 포함)가 HTML로 변환합니다. 표, 작업 목록, 취소선 같은 확장 문법이 이 단계에서 적용됩니다.
코드 블록 하이라이트: 모든 코드 펜스는 Expressive Code가 처리하여 문법 하이라이트, 제목 표시줄, 행 번호, 복사 버튼이 붙은 코드 블록을 생성합니다.
사이트 레이아웃 적용: 컴파일된 HTML이 Starlight의 페이지 골조에 들어갑니다. 상단 바, 왼쪽 목차, 오른쪽 이 페이지의 목차는 모두 src/components/starlight/ 아래의 커스텀 컴포넌트가 렌더링합니다.
인덱스와 정적 파일 생성: pnpm run build 시 Pagefind가 모든 산출 페이지를 순회하며 전체 텍스트 인덱스를 추출합니다. 최종 dist/ 디렉터리의 순수 HTML은 어떤 정적 서버에도 바로 호스팅할 수 있습니다.

Frontmatter 규칙

title은 필수이며, 누락되면 빌드 시 InvalidInputError 오류가 발생합니다;
description은 채워 넣는 것을 권장하며, 검색 엔진 결과와 공유 카드에 표시됩니다;
Frontmatter는 파일 맨 앞의 유효한 YAML 블록이어야 하며, 세 개의 가로줄이 모두 있어야 합니다.

제목 규칙

규칙	설명
본문에 1단계 제목 `#`을 쓰지 않습니다	Frontmatter의 `title`이 이미 페이지 대제목으로 렌더링되므로 본문에 다시 `#`을 쓰면 대제목이 두 개 나타납니다
2단계 제목 `##`부터 본문 시작	`##`과 `###`는 자동으로 오른쪽 「이 페이지의 목차」에 들어갑니다
`####` 이하는 목차에 들어가지 않습니다	더 깊은 단계는 본문 스타일로만 렌더링됩니다
제목 텍스트는 앵커를 생성합니다	한국어 제목의 앵커는 제목 텍스트 그 자체입니다. 예: `#제목-규칙`

콜아웃 규칙 (Asides)

콜아웃은 Starlight의 삼중 콜론 문법을 사용하며 4가지 유형을 지원합니다:

:::note
보충 설명류의 안내입니다.
:::

:::tip
효율을 높이는 작은 팁입니다.
:::

:::caution
주의가 필요한 위험이나 실수하기 쉬운 조작입니다.
:::

:::danger
데이터 손실이나 되돌릴 수 없는 조작이 관련된 고위험 경고입니다.
:::

유형 뒤에 커스텀 제목을 붙일 수도 있습니다: :::tip[설치 속도 향상].

네 가지 색상 콜아웃의 실제 렌더링 효과

그림: 네 가지 콜아웃을 위 문법대로 썼을 때의 실제 표시 효과로, 콜아웃, 코드 블록 및 다이어그램 예시 페이지에서 발췌했습니다.

코드 블록 규칙

코드 펜스(백틱 세 개)는 Expressive Code가 렌더링하며 다음 표기를 지원합니다(첫 줄 백틱 뒤에 씁니다):

표기 방법	역할	예시
언어 식별자	문법 하이라이트 방식을 결정합니다	```ts
`title="..."`	파일 이름 제목 표시줄을 보여 줍니다	```ts title=“src/config/site.ts”
`{2}` / `{2-4}`	지정한 행을 하이라이트합니다	```ts {2}
`lang="diff"` 또는 `diff`	추가·삭제 행을 빨강/초록 대비로 보여 줍니다	```diff
`bash` / `sh` 등 터미널 언어	터미널 스타일 테두리로 렌더링합니다	```bash

모든 코드 블록에는 한 번의 클릭으로 복사하는 버튼이 자동으로 붙고, 코드 텍스트는 Pagefind의 검색 인덱스에 수록되어 독자가 코드 안의 키워드를 바로 검색할 수 있습니다.

이미지 규칙

이미지는 public/images/canvas/에 통일하여 두고 절대 경로로 참조합니다: ![설명](/images/canvas/ui-docs-reading.png);
아키텍처와 흐름 구성도는 .svg 벡터 형식을, 화면 스크린샷은 압축된 .png를 사용합니다;
설명 텍스트는 반드시 채워야 하며, 이것은 이미지 로딩 실패 시의 대체 텍스트이자 접근성(무장애 열람)의 근거가 됩니다;
현재 버전은 Mermaid 다이어그램 렌더링을 내장하지 않습니다: ```mermaid 펜스는 일반 코드 블록으로 소스가 그대로 표시됩니다. 흐름도가 필요하면 먼저 mermaid.live 같은 도구에서 SVG로 내보낸 뒤 이미지로 삽입하세요.

링크 규칙

사이트 내부 링크: 전체 경로를 사용하고 /로 시작과 끝을 맞춥니다, 예: /canvas/deployment/. 문서 경로를 바꾼 뒤에는 옛 경로를 astro.config.mjs의 redirects 테이블에 등록하여 점프를 유지하세요;
앵커 링크: /canvas/rendering/#코드-블록-규칙처럼 이 페이지의 특정 절로 바로 이동할 수 있습니다;
외부 링크: 완전한 URL만 쓰면 되며 본문에서는 테마 색으로 표시됩니다.

기타 렌더링 동작

문법	렌더링 결과
`굵게`, `기울임`, `~~취소선~~`	대응되는 텍스트 스타일
`행내 코드`	테마 색 고정폭 글꼴 캡슐
`Ctrl`+`K` 표기법	키캡 스타일의 키 식별자
GFM 표	테두리와 호버 하이라이트가 있는 데이터 표
`- [x]` 작업 목록	시각화된 체크박스(비활성 상태)
`[^이름]` 각주	본문 위첨자 번호 + 페이지 하단의 각주 목록, 클릭으로 왕복 이동 지원
Markdown 인용 블록 `>`	왼쪽 테마 색 세로줄 + 옅은 배경색
구분선 `---`	본문 영역을 가로지르는 가는 구분선