Next.js에서 Markdown → HTML 변환 파이프라인

Next.js에서 markdown을 렌더링할 때는 unified 생태계를 사용한다.

변환 흐름

markdown 텍스트
  → (remark)  → AST (추상 구문 트리)
  → (rehype)  → HTML AST
  → (rehype)  → HTML 문자열

단순히 텍스트를 치환하는 게 아니라, 문서 전체를 트리(AST) 구조로 파싱한 뒤 노드 단위로 변환한다. obsidian-wikilink|Wikilink 플러그인은 트리를 순회하다가 [[...]] 패턴 노드를 발견하면 <a> 노드로 교체한다.

.use(remarkWikiLink, {
  pageResolver: (name) => [name.toLowerCase().replace(/ /g, '-')],
  hrefTemplate: (permalink) => `/learn/${permalink}`
})

장단점

장점

• 플러그인 조합으로 확장 가능 — wikilink 변환, 코드 하이라이팅, 수식 렌더링 등을 파이프라인에 추가
• AST 기반이라 정규식 치환보다 엣지 케이스 처리가 안정적
• Next.js SSG와 궁합이 좋음 — 빌드 타임에 변환이 완료되어 런타임 비용 없음

단점

• published: false 노트로의 링크처럼 vault 상태를 알아야 하는 변환은 플러그인만으로 해결 안 됨. 빌드 전에 공개 노트 목록을 만들고 플러그인이 이를 참조하는 방식으로 빌드 파이프라인 전체를 설계해야 함
• Wikilink가 Obsidian 전용 문법이라 표준 remark 생태계에서 기본 지원이 없어 커스터마이징 필요
• 노트가 많을수록 빌드 시간 증가 (Next.js ISR로 완화 가능)

관련 개념

• obsidian-wikilink — 변환 대상 문법
• what-is-cms|sinabrolog CMS 구조 — 이 파이프라인이 필요한 이유