Markdown 작성 및 서식 가이드

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

EpoCanvas Docs에서 문서를 추가하거나 편집하는 일은 매우 간단합니다. 모든 본문 내용은 표준 Markdown 문법으로 작성하므로, Markdown을 쓸 줄 안다면 바로 문서 작성과 유지 관리에 참여할 수 있습니다.

이 페이지는 사이트 전체 형식 지원의 완전한 목록입니다. 3절에서 기본 Markdown 형식을 항목별로 다루고, 4절에서 이 사이트가 추가로 지원하는 확장 문법을 다룹니다. 각 항목마다 “어떻게 쓰는지”와 “렌더링하면 어떻게 보이는지”를 나란히 보여 주며, 지금 보고 있는 결과가 실제 렌더링 결과입니다.

1. 문서 파일은 어디에 두나?

모든 문서 파일은 프로젝트의 src/content/docs/ 디렉터리에 저장합니다:

src/content/docs/
├── index.mdx          # 사이트의 랜딩 첫 페이지
├── canvas/            # 핵심 문서 장 (간체 중국어, 기본 언어)
│   ├── index.md       # 제품 소개
│   ├── deployment.md  # 빠른 시작
│   ├── layout.md      # 페이지 레이아웃
│   ├── ...            # 기타 문서
└── en/ ja/ ...        # 나머지 9개 언어의 번역, 디렉터리 구조는 중국어판과 완전히 대응

파일 이름 요구 사항: 소문자 영어와 하이픈(-)을 사용하고(예: quickstart-guide.md), 한글이나 공백을 넣지 마세요. 파일 이름이 접근 경로를 결정합니다: canvas/deployment.md는 /canvas/deployment/에 해당합니다.
확장자: 보통 일반 텍스트 .md 파일이면 충분합니다. 글 안에 인터랙티브 컴포넌트(예: 첫 페이지의 카드 그리드)를 넣어야 한다면 .mdx 형식을 사용합니다.
사이드바 등록: 새 파일을 만든 뒤에는 astro.config.mjs의 sidebar 배열에 등록해야 하며, 그렇지 않으면 왼쪽 목차에 나타나지 않습니다.
다국어 번역: 다른 언어의 번역은 src/content/docs/<언어>/ 디렉터리에 두며, 하위 디렉터리 구조는 중국어판과 같습니다(예: en/canvas/deployment.md는 영어판 빠른 시작에 해당). 아직 번역이 제공되지 않는 페이지는 자동으로 폴백되어 중국어를 표시합니다.

2. 머리 메타데이터(Frontmatter)는 어떻게 쓰나?

모든 Markdown 문서의 맨 위에는 하이픈 세 개 ---로 감싼 YAML 메타데이터 블록이 반드시 포함되어야 합니다:

---
title: 빠른 시작 (3분 만에 실행)
description: EpoCanvas Docs 로컬 환경 준비, 의존성 설치와 서버 시작 가이드.
---

필드 설명

필드 이름	필수 여부	역할 설명
`title`	필수	글의 주 제목. 페이지 상단의 큰 제목으로 렌더링되며 브라우저 탭 제목으로도 사용됩니다.
`description`	작성 권장	글의 짧은 요약. 브라우저 검색 결과, 소셜 플랫폼 공유 카드의 설명 텍스트로 사용됩니다.
`template`	첫 페이지 전용	`splash`로 설정하면 사이드바 없는 랜딩 페이지 템플릿을 사용합니다.

3. 기본 Markdown 형식 전체 보기

이 사이트는 GFM 확장이 포함된 표준 Markdown으로 렌더링하며, 아래 형식을 모두 지원합니다. 먼저 전체 목록을 보고, 항목별로 작성 방법과 렌더링 결과 대조를 확인하세요:

형식	빠른 작성법	용도
제목	`## 소절 제목`	장 구조를 정리하고 오른쪽 이 페이지의 목차에 자동 수록
단락과 줄바꿈	빈 줄로 단락 구분	본문의 기본 단위
굵게 / 기울임 / 취소선	`굵게` `기울임` `~~취소선~~`	핵심 문장 강조
인라인 코드	`명령어`	명령어, 파일 이름, 단축키 표시
키보드 키	`<kbd>Ctrl</kbd>`	키캡 스타일의 키 표시
비순서 / 순서 목록	`- 항목` / `1. 항목`	나열하거나 단계별인 내용 정리
작업 목록	`- [x] 완료됨`	체크박스가 있는 확인 목록
인용 블록	`> 인용문`	원문 인용, 곁가지 설명 보충
코드 블록	백틱 세 개로 감쌈	여러 줄 코드, 하이라이트와 복사 버튼 포함
표	세로줄로 열 구분	파라미터 대조, 데이터 나열
링크	`[텍스트](주소)`	사이트 내 다른 페이지나 외부 사이트로 이동
이미지	`![설명](경로)`	스크린샷, 아키텍처 다이어그램 삽입
구분선	`---`	큰 단락 구분

3.1 제목 단계

본문에서는 1단계 제목(#)을 쓰지 마세요. Frontmatter의 title이 이미 페이지 큰 제목으로 자동 렌더링되므로, 본문에 #을 하나 더 쓰면 페이지에 큰 제목이 두 개 생깁니다. 각 소절은 2단계 제목(##)부터 시작합니다:

## 2단계 큰 제목 (장)

### 3단계 하위 제목 (소절)

렌더링 결과: 지금 읽고 있는 이 페이지가 바로 좋은 예입니다. “3. 기본 Markdown 형식 전체 보기”가 2단계 제목이고 이 소절 “3.1 제목 단계”가 3단계 제목이며, 둘 다 오른쪽 “이 페이지의 목차”에 나타납니다. 4단계 제목(####)은 본문 스타일만 적용되고 목차에는 더 이상 들어가지 않으므로, 목차에 넣고 싶지 않은 잘게 나뉜 소절에 적합합니다.

3.2 단락과 줄바꿈

Markdown은 빈 줄로 단락을 구분합니다. 초보자가 가장 많이 실수하는 부분입니다:

이것은 첫 번째 단락으로, 두 문장 사이에서 Enter를 한 번만 눌렀기
때문에 렌더링 후에도 같은 단락에 머뭅니다.

이 줄은 위 문장과 빈 줄 하나를 사이에 두고 있어, 렌더링하면 새 단락으로 나뉩니다.

이 줄의 끝에는 백슬래시가 하나 있고\
그 아래 줄은 실제로 새 줄에서 시작합니다.

렌더링 결과:

이것은 첫 번째 단락으로, 두 문장 사이에서 Enter를 한 번만 눌렀기 때문에 렌더링 후에도 같은 단락에 머뭅니다.

이 줄은 위 문장과 빈 줄 하나를 사이에 두고 있어, 렌더링하면 새 단락으로 나뉩니다.

이 줄의 끝에는 백슬래시가 하나 있고
그 아래 줄은 실제로 새 줄에서 시작합니다.

규칙 요약: Enter 한 번 = 소스 코드에서는 줄이 바뀌어도 같은 단락. 새 단락을 시작하려면 빈 줄을 넣고, 단락 안에서 강제로 줄을 바꾸려면 줄 끝에 백슬래시나 공백 두 개를 사용합니다.

3.3 문장 강조와 인라인 스타일

이것은**굵게**, 이것은*기울임*, 이것은***굵은 기울임***, 이것은~~취소선~~입니다.

명령어와 파일 이름은 인라인 코드로 표시합니다: `pnpm run dev`를 실행하면 개발 서버가 열립니다.

키보드 키는 HTML 태그로: <kbd>Ctrl</kbd> + <kbd>K</kbd>를 누르면 사이트 전체 검색이 열립니다.

렌더링 결과:

이것은굵게, 이것은기울임, 이것은굵은 기울임, 이것은~~취소선~~입니다.

명령어와 파일 이름은 인라인 코드로 표시합니다: pnpm run dev를 실행하면 개발 서버가 열립니다.

키보드 키는 HTML 태그로: Ctrl + K를 누르면 사이트 전체 검색이 열립니다.

3.4 목록과 작업 목록

비순서 목록, 하위 항목은 공백 두 개로 들여쓰기:
- 핵심 기능 하나
- 핵심 기능 둘
  - 둘의 하위 기능
  - 둘의 또 다른 하위 기능

순서 목록:
1. 1단계: Node.js 설치
2. 2단계: 코드 저장소 복제
3. 3단계: 개발 서버 시작

작업 목록:
- [x] 문법 하이라이트 지원
- [x] 한 번에 복사 지원
- [ ] 해야 할 일

렌더링 결과:

비순서 목록, 하위 항목은 공백 두 개로 들여쓰기:

핵심 기능 하나
핵심 기능 둘
- 둘의 하위 기능
- 둘의 또 다른 하위 기능

순서 목록:

1단계: Node.js 설치
2단계: 코드 저장소 복제
3단계: 개발 서버 시작

작업 목록:

문법 하이라이트 지원
한 번에 복사 지원
해야 할 일

3.5 인용 블록

> 이것은 인용문입니다. 원문 발췌, 배경 설명, 곁가지 노트에 적합합니다.
> 여러 줄을 연속으로 같은 인용 블록 안에 씁니다.

> > 인용 안에 인용을 다시 중첩할 수도 있습니다.

> 인용 안에도 목록을 넣을 수 있습니다:
>
> - 첫 번째 항목
> - 두 번째 항목

렌더링 결과:

이것은 인용문입니다. 원문 발췌, 배경 설명, 곁가지 노트에 적합합니다. 여러 줄을 연속으로 같은 인용 블록 안에 씁니다.

인용 안에 인용을 다시 중첩할 수도 있습니다.

인용 안에도 목록을 넣을 수 있습니다:

첫 번째 항목

두 번째 항목

3.6 코드 블록

백틱 세 개로 감싸고 첫 줄 백틱 뒤에 언어를 표기하면 문법 하이라이트가 적용됩니다. 각 코드 블록 오른쪽에는 한 번에 복사하는 버튼이 기본으로 붙습니다:

```js
export function formatBytes(bytes) {
  return `${(bytes / 1024).toFixed(1)} KB`;
}
```

렌더링 결과:

export function formatBytes(bytes) {
  return `${(bytes / 1024).toFixed(1)} KB`;
}

언어 식별자가 하이라이트 방식을 결정하며, 자주 쓰는 js, ts, bash, json, yaml, html, css, python 등을 모두 지원합니다. bash 같은 터미널 언어는 터미널 스타일의 어두운 테두리로 렌더링됩니다:

pnpm run build

코드 블록의 파일 이름 제목, 지정 줄 하이라이트 등 고급 사용법은 4.2절을 참고하세요.

3.7 표

표 머리글 아래 줄의 콜론으로 정렬 방식을 지정합니다(콜론이 왼쪽이면 왼쪽 정렬, 양쪽에 있으면 가운데 정렬, 오른쪽이면 오른쪽 정렬):

| 명령어 | 파라미터 | 설명 |
| :--- | :---: | ---: |
| `astro dev` | `--host` | 왼쪽 정렬 예시 |
| `astro build` | 없음 | 가운데 정렬 예시 |
| `astro preview` | `--port` | 오른쪽 정렬 예시 |

렌더링 결과:

명령어	파라미터	설명
`astro dev`	`--host`	왼쪽 정렬 예시
`astro build`	없음	가운데 정렬 예시
`astro preview`	`--port`	오른쪽 정렬 예시

3.8 링크

사이트 내 링크: [빠른 시작](/canvas/deployment/)

외부 링크: [Astro 공식 사이트](https://astro.build)

이 페이지 앵커: ["표" 소절로 이동](#37-표)

자동 링크: <https://github.com/shijianus/epocanvas-docs>

렌더링 결과:

사이트 내 링크: 빠른 시작

외부 링크: Astro 공식 사이트

이 페이지 앵커: “표” 소절로 이동

자동 링크: https://github.com/shijianus/epocanvas-docs

작성 규칙:

사이트 내 링크는 전체 경로를 쓰고 /로 시작하고 끝냅니다(예: /canvas/deployment/). 상대 경로는 쓰지 마세요.
앵커는 제목 텍스트를 변환한 ID입니다. 한국어 제목의 앵커는 그 텍스트 그대로입니다(문장 부호는 제거하고 공백은 하이픈으로 바꿈). 브라우저 주소 표시줄의 주소를 복사하면 앵커가 붙은 링크를 얻을 수 있습니다.
링크 텍스트는 목적지를 분명히 쓰고 “여기를 클릭”처럼 쓰지 마세요.

3.9 이미지와 그림 설명

문서에 필요한 이미지 자산은 public/images/canvas/ 디렉터리에 모아 두고, 참조할 때는 /로 시작하는 절대 경로를 사용합니다:

![로컬 개발 서버에서 렌더링된 빠른 시작 페이지의 실제 모습](/images/canvas/ui-quickstart.png)

*그림: 바로 아랫줄의 기울임 문구는 그림 설명으로 표시됩니다.*

렌더링 결과:

로컬 개발 서버에서 렌더링된 빠른 시작 페이지의 실제 모습

그림: 빠른 시작 페이지의 실제 렌더링 결과이며, 여기서는 시연용입니다.

이미지 규칙:

아키텍처 다이어그램과 순서도: .svg 벡터 이미지로 저장하면 모바일과 고해상도 화면에서 확대해도 흐려지지 않습니다. 이 사이트의 아키텍처 다이어그램은 모두 public/images/canvas/docs-*.svg에 있습니다.
UI 스크린샷: 압축한 .png로 저장하고 너비는 1440픽셀 정도면 충분합니다. 수십 MB짜리 원본을 그대로 올리지 마세요.
설명 텍스트 필수: ![ ] 안의 텍스트는 이미지의 대체 텍스트로 렌더링되므로, 이미지 내용을 성실히 설명하고 비워 두지 마세요.

이미지를 넣은 뒤에는 반드시 브라우저에서 실제 렌더링 결과를 확인하고, 경로가 올바르고 이미지가 정상적으로 표시되는지 확인한 후 커밋하세요.

3.10 구분선

짧은 대시 세 개 이상이 한 줄을 차지하면 구분선으로 렌더링되며, 큰 단락을 나누는 데 사용합니다:

위의 내용은 여기까지입니다.

---

아래에서 새 주제를 시작합니다.

렌더링 결과:

위의 내용은 여기까지입니다.

아래에서 새 주제를 시작합니다.

4. 확장 형식: 이 사이트의 강화 문법

아래 형식은 이 사이트가 표준 Markdown 위에 추가로 지원하는 확장 문법으로, 렌더링 엔진(Starlight 콜아웃과 Expressive Code)이 제공합니다.

4.1 네 가지 색상 콜아웃

콜아웃은 콜론 세 개 문법을 사용합니다. :::타입으로 시작하고 한 줄에 :::만 있는 줄로 끝나며, 네 가지 타입이 있고 색상과 아이콘이 각각 다릅니다:

타입 뒤에 대괄호를 붙이면 제목을 직접 정할 수 있습니다:

:::tip[설치 속도 높이기]
pnpm으로 의존성을 설치하면 npm보다 훨씬 빠릅니다:

```bash
npm install -g pnpm
```
:::

렌더링 결과:

콜아웃 안에서는 목록, 코드 블록, 표 등 어떤 조판이든 계속 사용할 수 있습니다. 더 많은 예시는 콜아웃, 코드 블록 및 다이어그램 예시를 참고하세요.

4.2 코드 블록 파일 이름 제목과 줄 하이라이트

코드 펜스 첫 줄에 title="파일 경로"를 표기하면 제목 표시줄이 나타나고, {줄 번호}로 중요한 줄을 하이라이트하며, 여러 줄 번호는 쉼표로 구분합니다:

```typescript title="src/config/site.ts" {2,4}
export const siteConfig = {
  name: 'EpoCanvas Docs', // ← 하이라이트 줄
  version: '1.0.0',
  locale: 'zh-CN',        // ← 하이라이트 줄
};
```

렌더링 결과:

export const siteConfig = {
  name: 'EpoCanvas Docs',
  version: '1.0.0',
  locale: 'zh-CN',
};

4.3 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',
});

4.4 각주

자료 출처를 밝히거나 보충 설명을 달 때는 GFM 각주 문법을 사용합니다:

사이트 전체 검색 인덱스는 Pagefind가 빌드 시점에 생성합니다[^pf].

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

렌더링 결과: 본문에 번호가 붙은 윗첨자 이동 표시¹가 나타나고, 클릭하면 페이지 맨 아래의 해당 각주 항목으로 부드럽게 이동합니다.

4.5 지원하지 않는 문법과 실수하기 쉬운 표기 빠른 참조

아래 표기법은 다른 플랫폼에서 흔하지만 이 사이트에서는 동작하지 않거나 기대와 다르게 표현되므로, 문서를 쓸 때는 처음부터 피하세요:

실수하기 쉬운 표기법	실제 동작	올바른 대체
```mermaid 펜스	일반 코드 블록처럼 소스가 그대로 표시되며 도형이 생성되지 않음	mermaid.live에서 SVG로 내보낸 뒤 이미지로 삽입
`> [!NOTE]` GitHub 알림 문법	일반 인용 블록으로 렌더링됨	`:::note`로 다시 씀
`:::warning` / `:::important`	알림 없이 조용히 일반 단락으로 렌더링되어 콜아웃 스타일이 없음	`:::caution`으로 다시 씀
본문에 1단계 제목 `#` 쓰기	페이지에 큰 제목이 두 개 생김	`#`을 지우고 본문은 `##`부터 시작
Enter 한 번으로 줄바꿈	두 줄이 한 줄로 합쳐짐	빈 줄로 단락을 나누거나 줄 끝에 백슬래시 추가

5. 더 나아가기

Markdown이 파일에서 페이지까지 렌더링되는 전체 파이프라인과 모든 규칙이 궁금하다면 **렌더링 규칙 상세**를 읽어 주세요.
콜아웃, 코드 블록, 각주 등 문법을 하나의 “살아 있는 예시 페이지”에서 모아 보고 싶다면 **콜아웃, 코드 블록 및 다이어그램 예시**를 읽어 주세요.

바로 이것이 이 페이지 맨 아래에 렌더링된 각주 본체입니다. 각주 내용은 본문 어디에 쓰든 페이지 맨 아래로 모두 모입니다. ↩