마크다운 가이드

Postlark는 GitHub Flavored Markdown (GFM) 에 11가지 확장 기능을 더해 풍부한 콘텐츠 작성을 지원합니다. 마크다운으로 작성한 모든 내용은 발행 시점에 정적 HTML로 변환되며, 클라이언트 사이드 JavaScript 없이 동작합니다 (KaTeX, Mermaid, highlight.js는 CDN에서 선택적으로 로드).

기본 마크다운 (GFM)

다음 표준 GFM 기능이 기본으로 지원됩니다.

제목

# 제목 1
## 제목 2
### 제목 3
#### 제목 4

텍스트 서식

**굵게** *기울임* ~~취소선~~

링크와 이미지

[링크 텍스트](https://example.com)
![대체 텍스트](https://example.com/image.png)

이미지

블로그 미디어 저장소에 이미지를 업로드한 후 마크다운에서 참조합니다:

![사진 설명](https://media.postlark.ai/blog-id/uuid.jpg)

업로드 방법:

방법	사용법
대시보드	에디터에 이미지 드래그 — URL이 자동 삽입됩니다
CLI	`postlark upload photo.jpg` — URL과 마크다운 문법 출력
API	`POST /v1/upload`에 파일 전송 — `{ url: "..." }` 반환
MCP	`upload_image` 도구에 base64 데이터 — URL 반환

지원 형식: JPEG, PNG, GIF, WebP. 최대 5MB. 외부 URL도 사용 가능합니다.

- 순서 없는 항목
- 다른 항목

1. 순서 있는 항목
2. 다른 항목

표

| 기능      | 상태      |
|-----------|-----------|
| GFM       | 지원됨    |
| 정렬      | 지원됨    |

인용문

> 이것은 표준 인용문입니다.

인라인 코드

텍스트를 백틱으로 감싸면 인라인 코드가 됩니다: `console.log()`

수평선

---

확장 기능

Postlark는 표준 GFM에 11가지 기능을 추가합니다. 모든 확장은 발행 시 서버 사이드에서 렌더링되며 별도의 설정이 필요하지 않습니다.

1. 제목 ID와 앵커 링크

모든 제목에 URL 친화적인 id 속성과 클릭 가능한 # 앵커 링크가 자동으로 생성됩니다. 이를 통해 글의 특정 섹션에 직접 링크를 걸 수 있습니다.

문법:

## 시작하기
### API 인증
## Getting Started

결과:

## 시작하기는 <h2 id="시작하기">로 변환되며 앵커 링크가 포함됩니다
### API 인증은 <h3 id="api-인증">으로 변환됩니다
영문도 지원됩니다: ## Getting Started는 <h2 id="getting-started">

#heading-id를 사용해 글 내 어디서든 제목으로 링크할 수 있습니다:

[시작하기](#시작하기) 섹션을 참고하세요.

마우스를 올리면 앵커 # 기호가 나타나 독자가 쉽게 링크를 복사할 수 있습니다.

2. 목차 (Table of Contents)

[TOC]를 별도의 줄에 작성하면 글의 모든 제목을 나열하는 탐색 목록이 자동 생성됩니다.

문법:

[TOC]

## 소개
### 배경
## 본문
### 세부 사항
## 결론

결과: [TOC] 자리에 모든 제목으로의 링크가 포함된 스타일링된 <nav> 요소가 삽입됩니다. 하위 제목은 단계별로 들여쓰기됩니다 (2단계, 3단계 오프셋). 목차는 테두리가 있는 박스 형태로 블로그 강조 색상에 맞춰 스타일링됩니다.

소문자 [toc]도 사용할 수 있습니다.

3. 각주

[^id]를 본문에 인라인으로 넣고, 문서 어디에서든 [^id]: 텍스트로 정의합니다. 모든 각주 정의는 수집되어 글 하단에 번호 매긴 섹션으로 렌더링됩니다.

문법:

Postlark는 마크다운 렌더링에 marked 라이브러리를 사용합니다[^1].
모든 GFM 기능을 지원합니다[^2].

[^1]: marked는 JavaScript로 작성된 고속 마크다운 파서입니다.
[^2]: GitHub Flavored Markdown은 표, 작업 목록 등을 추가합니다.

결과: 본문에 윗첨자 참조 번호 (예: [1])가 표시되며, 하단의 해당 각주로 링크됩니다. 각 각주에는 본문 참조 위치로 돌아가는 화살표 링크가 포함됩니다.

4. 수식 (KaTeX)

LaTeX 문법으로 수학 표현식을 작성할 수 있습니다. 인라인 수식은 달러 기호 하나, 블록 수식은 달러 기호 두 개를 사용합니다. 수식은 CDN에서 로드되는 KaTeX로 클라이언트 사이드에서 렌더링됩니다.

인라인 수식:

이차방정식의 근의 공식은 $x = \frac{-b \pm \sqrt{b^2 - 4ac}}{2a}$ 입니다.

블록 수식:

$$
E = mc^2
$$

펜스드 코드 블록에 언어를 math 또는 latex로 지정해도 됩니다:

```math
\int_{0}^{\infty} e^{-x^2} dx = \frac{\sqrt{\pi}}{2}
```

결과: 인라인 수식은 텍스트 흐름 안에서 렌더링됩니다. 블록 수식은 가운데 정렬되며 더 큰 크기로 표시됩니다. KaTeX CSS와 JS는 cdn.jsdelivr.net에서 로드됩니다.

5. Mermaid 다이어그램

mermaid 언어를 지정한 펜스드 코드 블록 안에 Mermaid 문법으로 다이어그램을 작성합니다. 다이어그램은 CDN에서 로드되는 Mermaid.js로 클라이언트 사이드에서 렌더링되며, 다크모드에 자동으로 적응합니다.

문법:

```mermaid
graph LR
    A[마크다운 작성] --> B[API로 발행]
    B --> C[블로그 HTML 렌더링]
    C --> D[CDN 캐시 저장]
```

결과: 코드 블록이 SVG 다이어그램으로 대체됩니다. Mermaid는 플로우차트, 시퀀스 다이어그램, 간트 차트, 클래스 다이어그램 등을 지원합니다. 전체 문법은 Mermaid 문서를 참고하세요.

6. 콜아웃

인용문 안에서 GitHub 스타일의 콜아웃 문법을 사용합니다. NOTE, TIP, IMPORTANT, WARNING, CAUTION의 5가지 유형이 있으며, 각각 고유한 색상과 아이콘을 가집니다.

문법:

> [!NOTE]
> 참고할 만한 유용한 정보입니다.

> [!TIP]
> 권장하는 모범 사례입니다.

> [!IMPORTANT]
> 놓치지 말아야 할 중요한 정보입니다.

> [!WARNING]
> 잠재적인 문제에 대한 경고입니다.

> [!CAUTION]
> 위험한 작업에 대한 주의 사항입니다.

결과: 각 콜아웃은 왼쪽 테두리, 아이콘, 라벨이 있는 색상 박스로 렌더링됩니다:

유형	아이콘	색상
`[!NOTE]`	정보	파란색
`[!TIP]`	전구	초록색
`[!IMPORTANT]`	느낌표	보라색
`[!WARNING]`	경고	노란색
`[!CAUTION]`	원형	빨간색

콜아웃은 다크모드에서 배경색이 자동으로 조정됩니다.

7. 이모지 단축 코드

콜론 사이에 이모지 단축 코드를 입력하면 렌더링 시 유니코드 이모지 문자로 변환됩니다.

문법:

출시일이다! :rocket: :tada: :sparkles:
잘했어요 :thumbsup: — 개선 필요 :thumbsdown:

결과: :rocket:은 로켓 이모지로, :tada:는 파티 이모지로 변환됩니다.

사용 가능한 단축 코드:

단축 코드	이모지	단축 코드	이모지	단축 코드	이모지
`:smile:`	웃음	`:laugh:`	크게 웃음	`:wink:`	윙크
`:heart:`	하트	`:thumbsup:`	좋아요	`:thumbsdown:`	싫어요
`:clap:`	박수	`:fire:`	불	`:rocket:`	로켓
`:star:`	별	`:check:`	체크	`:x:`	X 표시
`:warning:`	경고	`:info:`	정보	`:bulb:`	전구
`:memo:`	메모	`:link:`	링크	`:key:`	열쇠
`:lock:`	잠금	`:unlock:`	잠금 해제	`:bug:`	벌레
`:wrench:`	렌치	`:gear:`	톱니바퀴	`:package:`	패키지
`:tada:`	파티	`:sparkles:`	반짝이	`:zap:`	번개
`:boom:`	폭발	`:eyes:`	눈	`:thinking:`	생각
`:100:`	100점	`:wave:`	손 흔들기	`:pray:`	기도
`:muscle:`	근육	`:coffee:`	커피	`:beer:`	맥주
`:pin:`	핀	`:bell:`	종	`:calendar:`	달력
`:chart:`	차트	`:globe:`	지구본	`:cloud:`	구름
`:sun:`	해	`:moon:`	달	`:rainbow:`	무지개
`:umbrella:`	우산	`:snowflake:`	눈꽃
`:arrow_right:`	오른쪽 화살표	`:arrow_left:`	왼쪽 화살표	`:arrow_up:`	위쪽 화살표
`:arrow_down:`	아래쪽 화살표

8. 작업 목록

GFM 작업 목록 문법으로 체크박스 목록을 만들 수 있습니다. 체크박스는 읽기 전용 스타일 요소로 렌더링됩니다.

문법:

- [x] API 설계 완료
- [x] Worker 구현 완료
- [ ] 문서 작성
- [ ] 프로덕션 배포

결과: 각 항목에 스타일링된 체크박스가 표시됩니다. 완료된 항목은 체크마크가 있는 파란색 채워진 체크박스로, 미완료 항목은 빈 테두리 박스로 표시됩니다. 체크박스는 읽기 전용입니다 (상호작용 불가).

9. 향상된 코드 블록

펜스드 코드 블록에 파일 제목 헤더, 줄 번호, diff 하이라이팅의 세 가지 추가 기능을 사용할 수 있습니다.

파일 제목:

언어 식별자 뒤에 title="파일명"을 추가하면 코드 블록 위에 파일명 헤더가 표시됩니다.

```typescript title="src/index.ts"
export default {
  async fetch(request: Request): Promise<Response> {
    return new Response('Hello, Postlark!')
  },
}
```

줄 번호:

언어 뒤에 showLineNumbers를 추가하면 줄 번호가 거터에 표시됩니다.

```python showLineNumbers
def hello():
    print("Hello, world!")
    return True
```

Diff 하이라이팅:

diff 언어를 사용하면 추가/삭제된 줄이 하이라이팅됩니다. +로 시작하는 줄은 초록색, -로 시작하는 줄은 빨간색으로 표시됩니다.

```diff
- const old = 'before'
+ const new = 'after'
  const unchanged = true
```

기능을 조합하여 사용할 수 있습니다:

```typescript title="config.ts" showLineNumbers
const config = {
  name: 'my-blog',
  theme: 'default',
}
```

10. 구문 하이라이팅

언어 식별자가 있는 코드 블록은 highlight.js (CDN에서 로드)를 사용해 구문이 하이라이팅됩니다. 코드 블록 오른쪽 상단에 언어 라벨이 표시되며, 마우스를 올리면 복사 버튼이 나타납니다.

문법:

```javascript
function greet(name) {
  return `Hello, ${name}!`
}
```

```sql
SELECT title, slug FROM posts
WHERE status = 'published'
ORDER BY created_at DESC;
```

highlight.js가 지원하는 모든 언어를 사용할 수 있습니다: JavaScript, TypeScript, Python, Go, Rust, SQL, HTML, CSS, Bash, JSON, YAML 등.

11. YouTube 임베드

YouTube URL을 별도의 줄에 붙여넣으면 반응형 동영상 플레이어가 자동으로 삽입됩니다:

https://www.youtube.com/watch?v=dQw4w9WgXcQ

지원하는 URL 형식:

https://www.youtube.com/watch?v=VIDEO_ID
https://youtu.be/VIDEO_ID
https://www.youtube.com/embed/VIDEO_ID

개인정보 보호를 위해 youtube-nocookie.com 도메인으로 임베드됩니다. URL이 텍스트와 같은 줄에 있으면 임베드되지 않으며, 반드시 별도의 줄에 있어야 합니다.

콘텐츠 제한

최대 콘텐츠 크기: 1 MB
태그: 포스트당 최대 10개, 각 최대 50자
슬러그: 제목에서 자동 생성되며, 유니코드 지원 (한국어, 일본어 등)

보안

모든 렌더링된 HTML은 XSS 방지를 위해 자동으로 살균 처리됩니다. 다음 항목이 자동으로 제거됩니다:

<script>, <object>, <embed>, <form>, <style> 태그
<iframe> 태그 (플랫폼이 생성한 YouTube 임베드 제외)
on* 이벤트 핸들러 속성 (예: onclick, onerror)
href 및 src 속성의 javascript: URL