
## 들어가며

블로그에 마크다운을 쓰다 보니 표준 문법만으로는 해결되지 않는 것들이 쌓였다. 이미지 캡션, 수식 렌더링, 한국어 볼드 깨짐까지 성격이 제각각이었다. remark/rehype 파이프라인에 플러그인을 끼워 넣어 이 문제들을 하나씩 해결했다.

## remark/rehype

마크다운을 HTML로 변환하는 라이브러리는 `marked`, `markdown-it` 등 여러 가지가 있다. 이 블로그에서는 `remark`/`rehype` 조합을 사용했다.

블로그에 이미지를 넣다 보니 이미지 아래에 캡션을 달고 싶었다.

![이미지 캡션 예시](/images/posts/blog-dev-5-markdown-pipeline/01-caption-example.webp)

_이미지 아래에 이런 캡션을 자동으로 붙이고 싶었다_

그런데 마크다운에는 표준 캡션 문법이 없다. 그래서 이미지 바로 다음 줄에 이탤릭(`_캡션_`)이 단독으로 오면 캡션으로 인식하는 규칙을 정했다. 이탤릭은 본문에서도 쓰이지만, 이미지 바로 뒤에 단독으로 오는 경우는 거의 캡션 용도뿐이라 충돌할 일이 없었다.

문제는 이 규칙을 어떻게 구현하느냐였다. 마크다운은 문자열이다. 문자열 상태에서 "이미지 뒤에 이탤릭이 오면 캡션으로 감싸라" 같은 조작을 하려면 정규식으로 패턴을 찾아야 한다. 그런데 마크다운에서는 이미지를 링크로 감쌀 수도 있고(`[![alt](img.png)](url)`), 코드 블록 안에 이미지 문법을 그대로 적을 수도 있다.

코드 블록 안의 `![alt](url)`은 이미지가 아니라 설명을 위한 텍스트인데, 정규식은 이 둘을 구분하지 못한다. 이탤릭도 마찬가지다. 캡션용 이탤릭인지, 본문에서 강조하려고 쓴 이탤릭인지 정규식만으로는 문맥을 알 수 없다. 예외 케이스가 늘어날수록 정규식은 점점 복잡해지고 깨지기 쉬워진다.

결국 문자열 상태에서는 문맥을 알 수 없다는 게 근본적인 문제였다. 그래서 마크다운을 문자열이 아니라 트리 구조로 바꿔서 다루는 방법을 찾았다.

![AST Explorer에서 마크다운을 파싱한 결과](/images/posts/blog-dev-5-markdown-pipeline/02-ast-explorer.webp)

_AST Explorer에서 마크다운을 파싱한 결과. 이미지와 캡션이 각각 별도의 paragraph 노드로 분리되어 있다_

파서가 마크다운을 파싱하면서 "이건 이미지 노드", "이건 이탤릭 노드", "이건 코드 블록 안이니까 문법이 아니라 텍스트"를 미리 구분해둔다. 코드 블록 안의 `![alt](url)`은 이미지 노드가 아니라 텍스트 노드로 파싱되어 있으니까 애초에 걸리지 않는다. "이미지 노드를 찾아서 다음 노드가 이탤릭이면 figure로 감싸라"고만 하면 된다.

remark/rehype는 이 변환을 세 단계로 나눈다.

- **remark**: 마크다운 텍스트를 mdast(마크다운 트리)로 파싱한다. remark 플러그인들이 이 트리를 변환한다.
- **remark-rehype**: mdast를 hast(HTML 트리)로 변환하는 플러그인이다. mdast의 마크다운 개념을 HTML 개념으로 매핑한다. `heading` + `depth: 2`는 `h2`가 되고, `emphasis`는 `em`이 되는 식이다.
- **rehype**: hast를 받아 HTML 단계에서 추가 처리를 한다. rehype 플러그인들이 이 단계에서 동작한다.

두 단계로 나누는 이유는, 어떤 문제는 마크다운 단계에서 잡는 게 자연스럽고 어떤 문제는 HTML 단계에서 처리하는 게 자연스럽기 때문이다. CJK(중국어·일본어·한국어 문자) 볼드 보정은 마크다운 트리에서 텍스트 노드를 찾아 변환하는 게 맞고, 수식을 KaTeX HTML로 렌더링하는 건 HTML 트리에서 하는 게 맞다. 각 단계에 플러그인을 끼워넣을 수 있어서, 이런 문제들을 독립된 플러그인으로 분리할 수 있었다.

```mermaid
sequenceDiagram
    participant MD as 마크다운 텍스트
    participant mdast as 마크다운 AST
    participant hast as HTML AST
    participant HTML as HTML 문자열

    MD->>mdast: remark-parse
    mdast->>mdast: remark 플러그인들
    mdast->>hast: remark-rehype
    hast->>hast: rehype 플러그인들
    hast->>HTML: rehype-stringify
```

마크다운 텍스트가 파싱되어 AST가 되고, remark 플러그인들이 그 트리를 변환한 뒤 HTML AST로 넘어간다. rehype 플러그인들이 HTML 단계에서 추가 처리를 하고 최종 HTML 문자열로 직렬화된다.

이 파이프라인을 React에서 쓸 때는 `react-markdown`을 사용한다. 이 라이브러리가 내부적으로 remark/rehype 파이프라인을 돌리면서, 결과물을 React 컴포넌트로 렌더링해 준다. 현재 블로그의 플러그인 구성은 이렇다.

```typescript
<ReactMarkdown
  remarkPlugins={[remarkGfm, remarkMath, remarkMediaCaption, remarkCjkBold]}
  rehypePlugins={[rehypeRaw, rehypeSlug, rehypeKatex]}
  components={{ /* 커스텀 컴포넌트 */ }}
>
  {postData.content}
</ReactMarkdown>
```

각 플러그인이 어떤 문제를 해결하는지 하나씩 살펴보자.

## remark, rehype의 플러그인

### GFM

표준 마크다운(CommonMark, 마크다운 표준 스펙)은 생각보다 지원하는 문법이 적다. 테이블, 취소선, 체크박스 같은 것들은 표준에 없다. `remarkGfm`은 GFM(GitHub Flavored Markdown, GitHub에서 확장한 마크다운 스펙)을 추가해서 이런 문법들을 사용할 수 있게 한다.

| 문법      | 마크다운              | 결과             |
| --------- | --------------------- | ---------------- |
| 테이블    | `\| A \| B \|`        | 표 렌더링        |
| 취소선    | `~~텍스트~~`          | ~~텍스트~~       |
| 작업 목록 | `- [x] 완료`          | 체크박스         |
| 자동 링크 | `https://example.com` | 클릭 가능한 링크 |

GFM 없이는 이런 것들을 전부 raw HTML로 작성해야 한다.

### KaTeX 수식

기술 노트를 쓰다 보면 수학 수식이 필요할 때가 있다. 알고리즘의 시간 복잡도를 $O(n \log n)$으로 표기하거나, 공식을 블록으로 보여주고 싶은 경우다. 처음에는 LaTeX를 떠올렸는데, LaTeX는 논문 조판용 시스템이라 웹에서 쓰기엔 너무 무겁다. KaTeX는 LaTeX 수식 문법을 브라우저에서 빠르게 렌더링하기 위해 만들어진 경량 라이브러리다. 문법은 거의 같으면서 훨씬 가볍다.

`remarkMath`가 `$inline$`과 `$$block$$` 문법을 인식해서 AST 노드로 변환하고, `rehypeKatex`가 그 노드를 KaTeX로 렌더링한다.

```mermaid
sequenceDiagram
    participant MD as $O(n \log n)$
    participant remark as remarkMath
    participant rehype as rehypeKatex
    participant HTML as 렌더링 결과

    MD->>remark: $ 문법 인식
    remark->>remark: math 노드로 변환
    remark->>rehype: mdast → hast
    rehype->>rehype: KaTeX HTML 생성
    rehype->>HTML: 수식 렌더링
```

두 플러그인이 remark 단계와 rehype 단계에서 각각 역할을 나눠 처리하는 구조다.

### 헤딩 ID와 Raw HTML

`rehypeSlug`는 `## 제목`을 `<h2 id="제목">제목</h2>`으로 변환해서 목차(TOC) 클릭 시 해당 헤딩으로 스크롤할 수 있게 해준다. `rehypeRaw`는 마크다운 안에 `<div class="callout">` 같은 raw HTML을 직접 쓸 수 있게 통과시켜 준다. 이 플러그인이 없으면 HTML 태그가 텍스트로 이스케이프되어 그대로 노출된다.

## 이미지 캡션 플러그인 (remarkMediaCaption)

앞서 설명한 이미지 캡션 규칙을 직접 구현한 플러그인이다. 이미지 뒤에 이탤릭이 단독으로 오면 `<figure>` + `<figcaption>`으로 자동 변환한다. 기존 오픈소스 플러그인에는 원하는 동작과 맞는 게 없어서 다른 플러그인과는 다르게 직접 만들게 되었다.

### AST 변환 로직

remark 플러그인은 AST를 입력받아 AST를 반환하는 함수다. 마크다운이 파싱되면 각 요소가 노드로 표현된 트리 구조가 만들어지는데, 이 트리를 순회하면서 원하는 패턴을 찾아 변환하는 것이 플러그인의 역할이다.

```typescript
const remarkMediaCaption: Plugin<[], Root> = () => {
  return (tree: Root) => {
    // 1. AST의 최상위 노드들 순회
    for (let i = 0; i < tree.children.length; i++) {
      const node = tree.children[i];

      // 2. 이미지를 포함한 paragraph 탐색
      if (!isImageParagraph(node)) continue;

      // 3. 바로 다음 노드가 이탤릭(캡션)인지 확인
      const nextNode = tree.children[i + 1];
      const caption = isCaptionParagraph(nextNode);

      // 4. 이미지 + 캡션을 <figure> HTML로 교체
      const html = createFigureHtml(node, caption);
      tree.children.splice(i, caption ? 2 : 1, { type: "html", value: html });
    }
  };
};
```

가독성을 위해 간략하게 작성했지만, 실제 코드는 연속 이미지 그리드나 비디오 처리도 포함한다.

`tree.children`은 AST의 최상위 노드 목록이다. 문단, 헤딩, 코드 블록 등이 이 배열에 하나씩 들어있다. 이 노드들을 순서대로 돌면서 이미지 paragraph를 찾고, 바로 다음 노드가 이탤릭이면 캡션으로 간주한다. 이미지와 캡션을 합쳐서 `<figure>` HTML로 교체하면 변환이 완료된다.

### 이미지 그리드

이미지를 두 장 넣어야 할 때가 있다. 세로로 나열하면 스크롤이 길어지고 비교가 어려운데, 한 행에 나란히 놓으면 훨씬 자연스럽다. 그래서 연속된 이미지가 2개 이상이면 자동으로 그리드 레이아웃으로 묶는 기능도 추가했다.

![excalidraw: 그리드 예시 이미지 1](/images/posts/blog-dev-5-markdown-pipeline/03-grid-1.webp)

![excalidraw: 그리드 예시 이미지 2](/images/posts/blog-dev-5-markdown-pipeline/04-grid-2.webp)

_연속된 이미지가 자동으로 한 행에 나란히 배치된다_

`image-grid-2` 클래스에 CSS Grid를 적용하면 2열 레이아웃이 되고, 이미지가 3개면 `image-grid-3`이 붙어서 3열이 된다. 마크다운에서 이미지를 연속으로 나열하기만 하면 나머지는 자동이다.

## CJK 볼드 보정 플러그인 (remarkCjkBold)

한국어 노트를 작성하다 보면 `**볼드**` 처리가 안 되는 경우가 있었다. 모든 볼드가 깨지는 게 아니라 특정 패턴에서만 발생했다. `**Observable**이라는`은 잘 되는데 `**연산자(operator)**를`은 안 된다. 괄호 뒤에 한국어가 바로 오는 경우에만 깨지는 것 같았는데, 그 당시에는 정확한 원인을 모르고 넘겼었다.

### CommonMark의 flanking delimiter 규칙

원인은 CommonMark 스펙에 있었다. CommonMark는 마크다운의 표준 스펙이고, remark의 파서도 이 스펙을 따른다. CommonMark 파서는 `**`를 볼드로 인식할 때 앞뒤 문자를 검사하는데, 이 검사 규칙을 [flanking delimiter rule](https://spec.commonmark.org/0.31.2/#left-flanking-delimiter-run)이라고 한다.

간단하게 말해서 여는 `**`는 왼쪽에, 닫는 `**`는 오른쪽에 인접한 문자가 특정 조건을 만족해야 한다. 닫는 `**`의 조건은 이렇다.

> 닫는 `**` 바로 앞이 `)` 같은 구두점이면, `**` 바로 뒤에 공백이나 구두점이 와야 한다.

영어에서는 단어 뒤에 공백이 자연스럽게 오기 때문에 이 조건에 걸릴 일이 거의 없다. 하지만 한국어에서는 조사가 바로 붙는다. `**연산자(operator)**를`처럼 닫는 `**` 뒤에 "를", "을", "라고" 같은 조사가 공백 없이 오면 파서가 이걸 볼드의 끝으로 인식하지 못한다.

```markdown
**연산자(operator)**를 제공한다. → )**를 → 볼드 실패
**Observable**이라는 단일 추상화 → e**이 → 볼드 성공 (앞이 알파벳)
**않는** 문제가 발생한다. → 는\*\* → 볼드 성공 (뒤에 공백)
```

결국 닫는 `**` 앞이 `)` + 뒤에 한글이 바로 오는 조합이 문제였다. `**FOUC(Flash of Unstyled Content)**라고`, `**지각적 균일성(perceptual uniformity)**을` 같은 패턴이 전부 해당된다.

### AST 레벨에서 확인

실제로 파서가 `**연산자(operator)**를`을 어떻게 처리하는지 AST로 찍어봤다.

![excalidraw: CJK 볼드가 파싱되지 않은 AST](/images/posts/blog-dev-5-markdown-pipeline/05-cjk-bold-ast.webp)

_볼드 마커가 strong 노드로 분리되지 않고 text 노드의 value 안에 리터럴로 남아있다_

볼드가 제대로 인식되었다면 이렇게 되어야 한다.

```json
{
  "type": "paragraph",
  "children": [
    { "type": "text", "value": "...조합하는 " },
    {
      "type": "strong",
      "children": [{ "type": "text", "value": "연산자(operator)" }]
    },
    { "type": "text", "value": "를 제공한다." }
  ]
}
```

`**`가 strong 노드로 분리되지 않고 텍스트 노드 안에 리터럴 문자열로 남아있었다. 파서 단계에서 이미 "이건 볼드가 아니다"라고 판단한 거라, 파서 자체를 고칠 수는 없었다. 대신 파서 이후 단계에서 후처리하는 방법을 찾아야 했다.

### remarkCjkBold 플러그인 구현

파서 자체를 수정할 수는 없으니, 파서 이후 단계에서 후처리하는 방식을 찾았다. 텍스트 노드를 순회하면서 리터럴로 남아있는 `**...**` 패턴을 찾아 strong 노드로 변환하는 remark 플러그인을 만들었다.

```typescript
const remarkCjkBold: Plugin<[], Root> = () => {
  return (tree: Root) => {
    visit(tree, "text", (node: Text, index, parent) => {
      if (!parent || index === undefined) return;

      // 텍스트 노드에 남아있는 **...** 패턴 탐색
      const regex = /\*\*([^\s*](?:[^*]*[^\s*])?)\*\*/g;
      const matches = [...node.value.matchAll(regex)];

      if (matches.length === 0) return;

      // 텍스트 노드를 분할해서 strong 노드 삽입
      const newChildren: PhrasingContent[] = [];
      let lastIndex = 0;

      for (const match of matches) {
        const startIdx = match.index!;

        if (startIdx > lastIndex) {
          newChildren.push({ type: "text", value: node.value.slice(lastIndex, startIdx) });
        }

        newChildren.push({
          type: "strong",
          children: [{ type: "text", value: match[1] }],
        });

        lastIndex = startIdx + match[0].length;
      }

      if (lastIndex < node.value.length) {
        newChildren.push({ type: "text", value: node.value.slice(lastIndex) });
      }

      parent.children.splice(index, 1, ...newChildren);
    });
  };
};
```

앞서 만든 `remarkMediaCaption`과 같은 패턴이다. AST를 순회하면서 원하는 노드를 찾고, 새로운 노드로 교체한다. 커스텀 플러그인을 만드는 것이 거창해 보일 수 있지만, 결국 "트리에서 패턴 찾기 → 변환"이라는 동일한 구조의 반복이다.

기존 동작을 망가뜨리지 않을까 걱정했는데, 확인해보니 괜찮았다. 정상적으로 파싱된 볼드는 이미 strong 노드가 되어 있어서 텍스트 노드 안에 `**`가 남아있지 않다. 이 플러그인은 파서가 놓친 케이스, 즉 텍스트 노드 안에 리터럴로 남은 `**...**`만 잡아준다.

이 문제를 해결하다 보니 오픈소스로 플러그인을 배포하면 어떨까 싶었다. 내가 겪은 문제라면 분명 다른 사람도 겪었을 것 같아서 찾아보니 역시 [remark-cjk-friendly](https://www.npmjs.com/package/remark-cjk-friendly)라는 플러그인이 이미 있었다. [CommonMark 이슈 #650](https://talk.commonmark.org/t/cjk-and-bold-tags-possibly-complex-issue/4034)에서 7년 넘게 논의되고 있는 문제이기도 하다.

remark-cjk-friendly는 파서 레벨에서 토크나이저 규칙 자체를 수정하는 방식이라, 내 플러그인처럼 후처리로 잡는 것보다 근본적인 해결이다. 내가 직접 만든 플러그인은 블로그에서 마주친 케이스는 잘 잡아주고 있지만, 모든 경우의 수를 커버하지는 못할 수 있다는 약간의 아쉬움이 들었다.

## 커스텀 컴포넌트

지금까지는 마크다운이 HTML로 변환되는 과정에 개입하는 플러그인을 살펴봤다. 하지만 변환된 HTML이 React 컴포넌트로 렌더링되는 마지막 단계에서도 커스터마이징할 수 있다. `react-markdown`의 `components` prop을 사용하면, 특정 HTML 요소를 기본 태그 대신 커스텀 React 컴포넌트로 대체할 수 있다.

### 이미지 모달

블로그 글에 포함된 스크린샷이나 다이어그램은 원본 크기로 보고 싶을 때가 있다. 이미지를 클릭하면 확대된 모달이 열리도록 `img` 태그를 커스텀 컴포넌트로 교체했다.

```typescript
components={{
  img: ({ src, alt, ...props }) => (
    <img
      src={src}
      alt={alt || ""}
      className="cursor-pointer transition-transform hover:scale-[1.02]"
      onClick={() => handleImageClick(src || "", alt || "")}
    />
  ),
}}
```

마크다운에서 `![alt](/src.png)`로 이미지를 삽입하면, 기본 `<img>` 태그 대신 클릭 이벤트가 달린 컴포넌트가 렌더링된다. 호버 시 살짝 커지는 효과를 넣어서 클릭 가능하다는 힌트를 준다.

### 테이블 래퍼

GFM으로 테이블을 쓸 수 있게 됐지만, 열이 많은 테이블은 모바일에서 화면을 넘친다. 테이블 자체는 건드리지 않고, 감싸는 `div`를 추가해서 가로 스크롤을 적용했다.

```typescript
table: ({ children, ...props }) => (
  <div className="table-wrapper">
    <table {...props}>{children}</table>
  </div>
),
```

`table-wrapper`에 `overflow-x: auto`를 적용하면 테이블이 넘칠 때만 스크롤바가 나타난다. 페이지 전체가 흔들리지 않고 테이블 영역만 스크롤된다.

### 외부 링크 처리

블로그 글에는 참고 자료나 공식 문서 링크를 자주 달게 된다. 외부 링크를 클릭했을 때 현재 탭에서 이동해버리면 읽던 글을 잃게 되니까, 외부 링크는 새 탭에서 열리도록 했다. 동시에 보안을 위해 `rel="noopener noreferrer"`도 자동으로 추가했다.

```typescript
a: ({ href, children, ...props }) => {
  const isExternal = href?.startsWith("http") && !href?.includes(SITE_URL);
  return (
    <a
      href={href}
      {...props}
      {...(isExternal ? {
        target: "_blank",
        rel: "noopener noreferrer"
      } : {})}
    >
      {children}
    </a>
  );
},
```

내부 링크(`/posts/...`)는 기존대로 같은 탭에서 이동하고, 외부 링크만 새 탭으로 열린다. 마크다운을 쓸 때 매번 `target="_blank"`를 수동으로 붙일 필요가 없다.

## 정리

처음에는 "이미지 캡션 하나 넣으려는데 이렇게까지 해야 하나" 싶었다. 하지만 문제가 하나씩 추가될 때마다 플러그인 구조의 가치를 체감했다. CJK 볼드 문제가 터졌을 때도 기존 파이프라인을 건드리지 않고 플러그인 하나를 추가하는 것만으로 해결할 수 있었다.

현재 파이프라인에 올라가 있는 플러그인들이다.

- GFM 확장 문법 지원
- 수학 수식 렌더링 (KaTeX)
- 이미지 캡션/그리드 자동 처리
- CJK 볼드 보정
- 헤딩 자동 id 부여 (TOC 연동)
- 코드 블록 Shiki 하이라이팅 (다음 편에서 다룸)


이미지 캡션, 수식, CJK 볼드 처리하기

remark/rehype 플러그인으로 마크다운의 한계 넘기


## 들어가며

기술 블로그에서 코드 하이라이팅이 깨지면 독자의 시선이 내용보다 먼저 오류에 걸린다. TypeScript 제네릭이나 데코레이터 같은 복잡한 문법을 정확하게 표현하는 것이 중요해서 라이브러리 선택에 신경을 썼다. 이 글에서는 VS Code와 동일한 토크나이저를 사용하는 Shiki를 빌드 타임에 적용한 과정을 정리한다.

## Shiki를 선택한 이유

코드 하이라이팅 라이브러리는 크게 두 종류다.

**Prism/highlight.js**: 정규식 기반이다. 가볍고 빠르다. 이 블로그도 처음엔 Prism을 썼는데, TypeScript 코드가 부정확하게 하이라이팅되는 경우를 몇 번 겪었다. 원인이 궁금해서 Prism 레포를 보니 2020년부터 열려 있는 이슈가 있었다.

https://github.com/PrismJS/prism/issues/2594

제네릭과 JSX 태그의 문법이 충돌해서 특정 패턴의 코드를 만나면 그 뒤의 하이라이팅이 풀리는 버그였다. 2020년에 임시 우회 PR이 머지됐지만 제목부터 "Temporary workaround"가 붙어 있고, 이슈는 머지 후에도 의도적으로 열린 채 남아 있다. 메인테이너도 코멘트에서 "정규식 기반 접근으로는 완벽히 고치기 어렵다"고 인정했다. Prism v1은 v2 개발 때문에 유지보수 모드로 돌아가 보안 패치만 받고 있어서, 근본 수정도 기대하기 어려운 상황이었다. 그래서 Shiki로 갈아탔다.

**Shiki**: TextMate 문법 기반이다. TextMate는 2004년에 나온 macOS 텍스트 에디터인데, 이 에디터가 만든 XML 기반 문법 정의 포맷이 이후 VS Code에 채택되면서 사실상 업계 표준이 됐다. Shiki는 VS Code와 동일한 grammar 파일을 써서 토큰화 결과가 동일하다. 정확도가 높고, VS Code 테마도 그대로 쓸 수 있다.

## 빌드 타임 하이라이팅

1. Shiki는 정확하지만 약 1MB의 WASM 엔진과 언어별 grammar·테마를 전부 로드해야 해서 런타임에 돌리면 무겁다.
2. 블로그 글은 내용이 빌드 시점에 고정되므로 매번 색칠할 필요가 없다.
3. 빌드 타임에 색칠을 끝내고 독자에겐 결과 HTML만 내려주면 된다.

Next.js에서 이걸 구현하는 건 세 조각으로 나뉜다. **`getStaticProps`** 가 진입점으로 "언제" 할지(빌드 타임에)를 정하고, **`extractAndHighlightCodeBlocks`** 함수가 "무엇을 어떻게" 색칠할지(코드 블록 찾고 Shiki 호출)를 담당하고, **페이지 컴포넌트**가 결과를 DOM에 주입한다.

`getStaticProps`는 Next.js가 빌드할 때 딱 한 번 실행하는 함수다. 여기서 색칠까지 끝내두면 그 결과가 정적 HTML에 담긴 채로 독자에게 전달된다.

```typescript
export const getStaticProps: GetStaticProps = async ({ params }) => {
  const postData = await getPostData(params.id);
  const codeBlocks = await extractAndHighlightCodeBlocks(postData.content);
  return { props: { postData, codeBlocks } };
};
```

실제 추출/하이라이팅 로직은 `extractAndHighlightCodeBlocks` 함수로 분리했다. 이 함수는 마크다운 원문을 스캔해서 각 코드 블록을 찾고, 각각 `highlightCode`를 호출한 결과를 `block-${index}` 키로 저장한 맵을 반환한다. 페이지 컴포넌트는 이 맵을 받아서 `dangerouslySetInnerHTML`로 렌더링한다. 단, Mermaid 다이어그램은 빌드 타임 처리 대상에서 빼고 클라이언트에서 별도 컴포넌트로 렌더링한다.

## 다크모드 대응

Shiki는 테마를 한 번에 하나만 적용할 수 있다. 다크모드를 지원하려면 두 가지 방법이 있다.

1. CSS 변수로 색상 오버라이드
2. 라이트/다크 HTML을 둘 다 생성

Shiki 테마의 색상 체계를 CSS 변수로 바꾸는 건 번거롭고 테마를 바꿀 때마다 같은 작업을 반복해야 한다. 반면 라이트/다크 HTML을 빌드 타임에 둘 다 생성해두면 Tailwind `dark:` 접두사로 간단히 토글할 수 있어서 2번을 선택했다.

```typescript
function isValidLanguage(lang: string): boolean {
  return /^[a-zA-Z0-9#+-]+$/.test(lang);
}

export async function highlightCode(code: string, language?: string): Promise<string> {
  // 유효하지 않은 언어명은 "text"로 fallback
  const safeLang = language && isValidLanguage(language) ? language : "text";

  const lightHtml = await codeToHtml(code, {
    lang: safeLang,
    theme: "github-light",
  });

  const darkHtml = await codeToHtml(code, {
    lang: safeLang,
    theme: "github-dark",
  });

  return `
    <div class="light-theme block dark:hidden">${lightHtml}</div>
    <div class="dark-theme hidden dark:block">${darkHtml}</div>
  `;
}
```

`isValidLanguage`는 언어명에 알파벳·숫자·`-`·`#`·`+`만 허용하는 1차 방어선이다. 이상한 값이 들어오면 `"text"`로 fallback해서 Shiki가 에러를 던지기 전에 막는다. HTML이 두 배가 되지만 빌드 타임에 생성되므로 런타임 비용은 없다.

## 커스텀 CodeBlock 컴포넌트

하이라이팅된 HTML을 감싸는 래퍼 컴포넌트다. 상단 바에 언어명과 복사 버튼을 붙였다.

```typescript
import { useState } from "react";
import { Check, Copy } from "lucide-react";

export default function CodeBlock({ language, children, html }: CodeBlockProps) {
  const [copied, setCopied] = useState(false);

  const handleCopy = async () => {
    await navigator.clipboard.writeText(children);
    setCopied(true);
    setTimeout(() => setCopied(false), 2000);
  };

  return (
    <div>
      <div>
        <span>{language || "text"}</span>
        <button onClick={handleCopy}>
          {copied ? <><Check size={16} /> Copied!</> : <><Copy size={16} /> Copy</>}
        </button>
      </div>
      <div dangerouslySetInnerHTML={{ __html: html || "" }} />
    </div>
  );
}
```

`children`에는 원본 코드 문자열이, `html`에는 빌드 타임에 만들어둔 하이라이팅 HTML이 들어있다. 복사 버튼을 누르면 하이라이팅 HTML이 아니라 원본 코드(`children`)를 클립보드에 넣는다.

## react-markdown 연동

`react-markdown`의 `components` prop에서 `code` 요소를 커스터마이징한다. 마크다운 파서가 발견한 코드 블록마다 이 컴포넌트가 호출되는데, 여기서 미리 만들어둔 `codeBlocks` 맵에서 해당 블록의 HTML을 꺼내 `CodeBlock`에 넘긴다.

```typescript
components={{
  pre: ({ children }) => <>{children}</>,
  code: ({ inline, className, children }) => {
    const match = /language-(\w+)/.exec(className || "");

    if (!inline && match) {
      const code = String(children).replace(/\n$/, "");
      const language = match[1];

      // Mermaid는 클라이언트에서 렌더링
      if (language === "mermaid") {
        return <MermaidBlock chart={code} />;
      }

      const blockKey = `block-${codeBlockIndex++}`;
      const html = codeBlocks[blockKey] || "";

      return (
        <CodeBlock language={language} html={html}>
          {code}
        </CodeBlock>
      );
    }

    return <code className={className}>{children}</code>;
  },
}}
```

`pre` 태그는 그냥 children을 반환한다. `react-markdown`이 `pre > code` 구조로 렌더링하는데, `pre`를 없애고 `code`만 커스터마이징하면 된다. 인라인 코드는 기본 스타일을 유지하고, 코드 블록만 `CodeBlock` 컴포넌트로 대체한다.

Mermaid는 빌드 타임에 스킵했기 때문에 여기서도 별도 분기가 필요하다. `extractAndHighlightCodeBlocks`에서 스킵한 것과 이 분기가 한 쌍으로 동작한다. 한쪽만 있으면 Mermaid 블록이 엉뚱하게 렌더링된다.

## 정리

- Shiki는 TextMate 문법 기반으로 VS Code와 동일한 토크나이저를 사용해 복잡한 TypeScript 문법도 정확하게 하이라이팅한다
- WASM 번들이 무거워서 런타임에 돌리기 부담스럽다. `extractAndHighlightCodeBlocks` 함수로 빌드 타임에 미리 처리하고 `getStaticProps`에서 호출한다
- 언어명 정규화, Mermaid 스킵, try/catch fallback을 한 함수 안에 묶어서 빌드가 깨지지 않도록 방어한다
- 다크모드는 라이트/다크 HTML을 둘 다 생성해두고 Tailwind `dark:` 접두사로 토글한다
- `react-markdown`의 `code` 컴포넌트를 커스터마이징해 미리 만들어둔 HTML을 `dangerouslySetInnerHTML`로 주입한다. Mermaid는 별도 분기로 클라이언트에서 렌더링한다


빌드 타임 하이라이팅으로 런타임 부담 없애기

Shiki로 빌드 타임 코드 하이라이팅 구현하기


## 들어가며

지금은 Obsidian으로 글을 쓰지만, 한동안 Notion을 SSoT로 두고 마크다운으로 동기화하는 구조로 블로그를 운영했다. SSoT(Single Source of Truth, 단일 진실 공급원)는 원본 데이터가 한 곳에만 존재하고 나머지는 거기서 파생된다는 개념인데, Notion에 글을 쓰면 그게 원본이고 레포의 마크다운 파일은 동기화된 복사본이었다.

그때 가장 골치 아팠던 부분은 이미지였다. Notion 이미지 URL은 만료 시간이 있어서 그대로 두면 글이 깨졌다. 여러 선택지를 두고 고민한 끝에, 동기화 시점에 이미지를 다운로드해서 최적화하고 영구적인 URL로 재업로드하는 파이프라인을 만드는 쪽으로 결정했다.

지금은 레거시가 된 코드지만 그때 고민했던 것들은 지금도 유효하다고 생각해서 정리하게 되었다. 어떤 라이브러리를 쓸지, 이미지를 어디에 저장할지, 같은 글을 여러 번 동기화해도 안전하게 만들려면 무엇이 필요한지 등이다.

## Notion 이미지 URL 문제

Notion 이미지 URL은 이렇게 생겼다.

```text
https://prod-files-secure.s3.us-west-2.amazonaws.com/...?X-Amz-Expires=3600...
```

이 링크에는 두 가지 문제가 있다.

1. 만료 시간이 있다. URL에 서명이 포함되어 있어서 일정 시간이 지나면 접근할 수 없다.
2. 원본 크기 그대로다. 4K 스크린샷을 올리면 4K 그대로 로드된다.

## 어떤 선택지가 있었나

만료되는 URL을 다루는 방법은 여러 가지였다.

1. **빌드 타임에 매번 새 URL 받기**: Notion API는 페이지를 fetch할 때마다 새 signed URL을 발급한다. 이론적으로는 빌드할 때마다 다시 받으면 만료 문제가 사라진다. 하지만 빌드 시간이 글 수에 비례해서 늘어나고, Notion API에 장애가 생기면 빌드 자체가 깨진다. 무엇보다 원본 크기 문제는 그대로 남는다.
2. **이미지 프록시 서비스(Cloudinary 등)에 올리기**: 원본 URL을 던지면 캐시·최적화·CDN까지 알아서 처리해준다. 가장 빠른 길이지만 외부 서비스 비용과 의존성이 추가되고, 만료 URL을 프록시가 어떻게 다루는지에 따라 안정성이 달라진다.
3. **다운로드해서 영구 저장소에 올리기**: 동기화 시점에 한 번만 처리하면 그 후로는 신경 쓸 게 없다. 동기화 스크립트가 좀 복잡해진다는 점을 감수하면, 빌드도 빠르고 외부 의존성도 최소화된다.

선택지를 찾아보고 정답은 없다는 생각이 들었다. 하지만 블로그라는 특성상 글을 한 번 쓰고 거의 안 고치는 식으로 가기 때문에 3번 방식이 가장 잘 맞을 것 같았다. 빌드 시간을 늘리고 싶지 않았고, 외부 서비스에 의존하지 않아서 개인적으로 만족스러웠다.

## sharp로 이미지 처리

Node.js에서 이미지 처리는 `sharp`가 주로 사용된다. 내부적으로 libvips라는 C로 작성된 이미지 처리 라이브러리를 사용한다. ImageMagick 같은 전통적인 이미지 처리 라이브러리는 이미지 전체를 메모리에 올린 뒤 작업하지만, libvips는 픽셀 데이터를 작은 청크 단위로 흘려보내며 처리한다.

여기서 중요한 건 단순히 "나눠서 처리한다"가 아니라 "한 청크를 처리한 직후 즉시 메모리에서 버린다"는 점이다. 어느 순간에도 메모리에는 지금 처리 중인 한 조각만 존재한다. 이게 가능한 이유는 리사이즈나 컬러 필터 같은 연산이 출력 픽셀 하나를 계산할 때 입력의 작은 이웃 픽셀들만 필요로 하기 때문이다. 이미지 전체를 동시에 들고 있을 필요가 없다.

![excalidraw: ImageMagick vs libvips 메모리 사용 패턴 비교](/images/posts/blog-dev-3-image-optimization/01-libvips-streaming.png)

4K 이미지(3840 × 2160 × 4바이트)는 약 33MB를 차지하는데, ImageMagick은 원본과 출력을 둘 다 들고 있어야 해서 60MB 이상을 쓰는 반면, libvips는 청크 한 조각만 들고 있어서 보통 1-2MB 수준에 머무른다. 같은 작업에서 ImageMagick보다 4배 이상 빠르고 메모리는 훨씬 적게 쓴다고 알려져 있다.

API도 메서드 체이닝으로 처리 단계를 자연어처럼 이어 쓸 수 있다. 아래 코드처럼 '버퍼를 받아 1200px로 리사이즈하고, WebP로 변환한 뒤, 다시 버퍼로 돌려준다'는 흐름을 그대로 메서드 호출 순서로 표현할 수 있다.

```typescript
import sharp from "sharp";

const optimizedBuffer = await sharp(Buffer.from(buffer))
  .resize(1200, null, {
    withoutEnlargement: true,
    fit: "inside",
  })
  .webp({
    quality: 85,
    effort: 6,
  })
  .toBuffer();
```

최대 너비를 1200px로 제한하고, WebP 포맷으로 변환한 결과를 버퍼로 반환한다.

### 리사이징 전략

`maxWidth: 1200`으로 큰 변 기준 최대 너비를 제한한다. 본문 폭은 768px 정도지만 고밀도 디스플레이(HiDPI)에서 흐릿하지 않으려면 본문보다 큰 원본이 필요해서 1200으로 두었다. `withoutEnlargement: true`는 원본보다 크게 확대하지 않는다는 뜻이고, 작은 이미지를 1200px로 늘리면 픽셀이 깨지기 때문에 넣었다.

### WebP 변환

모든 이미지를 WebP로 변환한다. JPEG보다 같은 화질에서 25-35% 작고, PNG처럼 투명도도 지원하고, 주요 브라우저에서 모두 동작한다. 압축률·투명도·호환성 세 가지를 모두 챙길 수 있는 포맷이라 골랐다.

`effort: 6`은 압축 효율과 속도를 조정하는 옵션이다. 총 0-6 범위이고, 높을수록 압축률이 좋지만 느리다. 빌드 시 한 번만 실행하므로 6으로 설정했다.

## Vercel Blob Storage

최적화된 이미지를 어디에 저장할지 고민했다. Git 저장소에 넣으면 용량이 커지고, 외부 서비스(Cloudinary, S3)는 별도 설정이 필요하다.

Vercel Blob은 Vercel 프로젝트와 통합이 잘 되어 있어서 선택했다.

```typescript
import { put } from "@vercel/blob";

const { url } = await put(webpFileName, optimizedBuffer, {
  access: "public",
  contentType: "image/webp",
});
```

반환된 URL은 영구적이고, CDN으로 서빙된다.

## 마크다운 내 이미지 자동 처리

글 동기화 시 마크다운을 스캔해서 Notion 이미지를 찾고, 최적화 후 URL을 교체한다.

```typescript
async processImagesInMarkdown(markdown: string, postSlug: string) {
  const imageRegex = /!\[([^\]]*)\]$([^)]+)$/g;
  let processedMarkdown = markdown;

  // 모든 이미지 매치 수집
  const matches: RegExpExecArray[] = [];
  let match;
  while ((match = imageRegex.exec(markdown)) !== null) {
    matches.push(match);
  }

  for (const match of matches) {
    const [fullMatch, altText, imageUrl] = match;

    // 이미 처리된 이미지는 스킵
    if (this.isVercelBlobUrl(imageUrl)) continue;

    // Notion 이미지만 처리
    if (this.isNotionImageUrl(imageUrl)) {
      const result = await this.optimizeAndUploadImage(imageUrl, fileName, postSlug);
      processedMarkdown = processedMarkdown.replace(
        fullMatch,
        `![${altText}](${result.url})`
      );
    }
  }

  return processedMarkdown;
}
```

정규식으로 마크다운 이미지 문법을 찾고, Notion URL인 경우에만 최적화 및 업로드를 수행한 뒤 URL을 교체한다.

### 멱등성 보장

같은 글을 여러 번 동기화해도 이미지가 중복 업로드되지 않는다.

```typescript
private isVercelBlobUrl(url: string): boolean {
  return url.includes('blob.vercel-storage.com');
}
```

이미 Vercel Blob URL이면 스킵한다. 한 번 처리된 이미지는 다시 처리하지 않는다.

## 하지만..

Obsidian으로 옮긴 이후로는 이미지 관리가 훨씬 단순해졌다. 이미지를 붙여넣으면 Custom Attachment Location 플러그인이 `public/images/posts/{slug}/` 경로에 자동 저장하고, Next.js가 정적 파일로 서빙하므로 별도 파이프라인이 필요 없다. 기존 글의 Vercel Blob URL은 그대로 유지된다.

파이프라인 코드는 레거시가 됐지만 삭제하지 않고 남겨뒀다. Notion 연동이 필요한 다른 프로젝트에서 그대로 떼어다 쓸 수 있는 형태이기도 하고, 같은 문제를 다시 만났을 때 참고하기 위해서다.

## 정리

- Notion 이미지 URL은 서명 기반 만료 방식이라 동기화 시점에 로컬로 내려받아야 한다
- `sharp`로 1200px 리사이즈 + WebP 변환을 적용하면 파일 크기를 크게 줄일 수 있다
- Vercel Blob에 업로드하면 영구 URL과 CDN 서빙을 동시에 확보한다
- 이미 처리된 URL은 건너뛰는 조건을 두어 멱등성을 보장한다
- Obsidian으로 전환한 이후에는 `public/images/` 로컬 저장 방식으로 대체되어 파이프라인은 레거시가 됐다


Notion 이미지 URL 만료 문제 해결과 sharp 기반 최적화

만료되는 Notion 이미지를 Sharp로 영구 저장하기


## 왜 SSG인가

블로그를 만들 때 가장 먼저 결정해야 하는 건 렌더링 방식이다. Next.js는 SSR, SSG, ISR을 지원하는데, 블로그에는 SSG가 가장 적합했다.

블로그 글은 한 번 작성하면 자주 바뀌지 않는다. 매 요청마다 서버에서 렌더링할 필요가 없다. 빌드 타임에 모든 페이지를 미리 생성해두면 CDN에서 정적 파일로 서빙할 수 있다. 서버 비용이 거의 들지 않고, 응답 속도도 빠르다.

ISR은 "주기적으로 재생성"이라는 개념이 블로그와 맞지 않았다. 글을 수정하면 즉시 반영되어야 하는데, ISR의 revalidation 주기 동안 구버전이 보일 수 있다. 차라리 수정할 때마다 빌드를 새로 돌리는 게 명확하다.

## 핵심 구조

Next.js Page Router에서 SSG를 구현하는 핵심은 두 함수다.

### getStaticPaths

빌드 타임에 어떤 페이지들을 생성할지 알려준다.

```typescript
export const getStaticPaths: GetStaticPaths = async () => {
  const posts = getSortedPostsData();
  const paths = posts.map((post) => ({
    params: { id: post.id },
  }));

  return {
    paths,
    fallback: false,
  };
};
```

`fallback: false`는 정의되지 않은 경로로 접근하면 404를 반환한다는 의미다. 블로그는 빌드 시점에 모든 글이 확정되므로 이 설정이 적합하다. `fallback: true`나 `'blocking'`은 동적으로 새 페이지를 생성할 때 쓴다.

### getStaticProps

각 페이지에 필요한 데이터를 빌드 타임에 가져온다.

```typescript
export const getStaticProps: GetStaticProps = async ({ params }) => {
  const id = params?.id as string;
  const postData = await getPostData(id);
  const headings = extractHeadings(postData.content);
  const adjacentPosts = getAdjacentPosts(id);
  const relatedPosts = getRelatedPosts(id, postData.tags);
  const readingTime = calculateReadingTime(postData.content);

  return {
    props: {
      postData: { ...postData, headings },
      adjacentPosts,
      relatedPosts,
      readingTime,
    },
  };
};
```

여기서 반환하는 props가 페이지 컴포넌트의 props로 전달된다. 빌드 타임에 실행되므로 파일 시스템 접근, 데이터베이스 쿼리 등 서버 사이드 작업이 가능하다.

## 데이터 레이어 설계

마크다운 파일에서 데이터를 추출하는 로직은 `src/lib/posts.ts`에 모아뒀다.

### 파일 시스템 기반 CMS

```typescript
const postsDirectory = path.join(process.cwd(), "posts");

export function getPostsList(): PostListItem[] {
  const fileNames = fs.readdirSync(postsDirectory);
  const allPostsData = fileNames
    .filter((fileName) => fileName.endsWith(".md"))
    .flatMap((fileName) => {
      const id = fileName.replace(/\.md$/, "");
      const fullPath = path.join(postsDirectory, fileName);
      const fileContents = fs.readFileSync(fullPath, "utf8");
      const matterResult = matter(fileContents);
      const data = matterResult.data as PostFrontmatter;

      if (data.published !== true) return [];

      return [
        {
          id,
          title: data.title,
          created: toDateString(data.created),
          tags: data.tags || [],
          excerpt: generateExcerpt(matterResult.content),
        },
      ];
    });

  return allPostsData.sort((a, b) => (a.created < b.created ? 1 : -1));
}
```

`fs.readdirSync`로 posts 폴더의 파일 목록을 읽고, 각 파일을 파싱해서 데이터를 추출한다. `gray-matter` 라이브러리가 frontmatter와 본문을 분리해준다.

`published !== true`인 글은 `flatMap`에서 빈 배열을 반환해 필터링한다. `filter` + `map` 조합보다 한 번에 처리할 수 있어서 간결하다.

### Frontmatter 타입 정의

```typescript
export interface PostFrontmatter {
  title: string;
  created: string | Date;
  updated?: string | Date;
  published?: boolean;
  tags?: string[];
}
```

`gray-matter`는 날짜 문자열을 자동으로 Date 객체로 파싱한다. `"2025-01-15"` 형식을 Date로 변환해주는데, 문제는 UTC로 파싱한다는 것이다. 한국 시간대에서 작성한 날짜가 하루 전으로 표시될 수 있다.

```typescript
function toDateString(value: string | Date): string {
  if (value instanceof Date) {
    // gray-matter가 UTC로 파싱하므로 UTC 메서드 사용
    const year = value.getUTCFullYear();
    const month = String(value.getUTCMonth() + 1).padStart(2, "0");
    const day = String(value.getUTCDate()).padStart(2, "0");
    return `${year}-${month}-${day}`;
  }
  return value;
}
```

`getUTCFullYear()`, `getUTCDate()` 등 UTC 메서드를 사용해서 파싱된 그대로의 날짜를 문자열로 변환한다. 로컬 시간대 메서드(`getFullYear()`)를 쓰면 시간대 변환이 일어나서 날짜가 어긋날 수 있다.

## 빌드 타임 최적화

SSG에서 중요한 건 빌드 타임이다. 글이 많아질수록 빌드 시간이 길어지는데, 몇 가지 최적화를 적용했다.

### 코드 하이라이팅 캐싱

코드 블록 하이라이팅은 비용이 크다. 매 빌드마다 모든 코드 블록을 하이라이팅하면 시간이 오래 걸린다.

```typescript
export const getStaticProps: GetStaticProps = async ({ params }) => {
  // ...
  const codeBlockRegex = /```([^\n\r]*)\r?\n([\s\S]*?)```/g;
  const codeBlocks: { [key: string]: string } = {};
  let match;
  let blockIndex = 0;

  while ((match = codeBlockRegex.exec(postData.content)) !== null) {
    const language = match[1]?.trim() || "text";
    const code = match[2];
    const blockKey = `block-${blockIndex++}`;
    codeBlocks[blockKey] = await highlightCode(code, language);
  }
  // ...
};
```

`getStaticProps`에서 코드 블록을 미리 하이라이팅해서 props로 전달한다. 클라이언트에서 하이라이팅하지 않으므로 번들 크기도 줄고, 사용자가 보는 시점에는 이미 처리가 끝나 있다.

### 날짜순 정렬 한 번만

```typescript
return allPostsData.sort((a, b) => (a.created < b.created ? 1 : -1));
```

정렬은 `getPostsList` 함수 내에서 한 번만 수행한다. 호출하는 쪽에서 매번 정렬하지 않아도 된다. 최신 글이 먼저 오도록 내림차순 정렬한다.

## 실제 빌드 결과

현재 블로그는 빌드 시 약 120개 페이지를 생성한다. Vercel에서 빌드 시간은 1분 내외다.

```text
Route (pages)                              Size     First Load JS
├ ● /                                      5.2 kB        89.4 kB
├ ● /posts/[id]                            12.1 kB       96.3 kB
├ ● /notes/[...slug]                       8.7 kB        92.9 kB
└ ... (120 more routes)
```

SSG의 장점은 배포 후 비용이 거의 없다는 것이다. Vercel 무료 티어로 충분하다. 서버리스 함수 호출이 없으니 사용량 걱정도 없다.


blog-dev

2025

remark/rehype 플러그인으로 마크다운의 한계 넘기

Shiki로 빌드 타임 코드 하이라이팅 구현하기

만료되는 Notion 이미지를 Sharp로 영구 저장하기

2024

블로그 개발기 (1): Next.js SSG로 블로그 만들기