20251219 Quartz

Quartz Blog Customization Log

오늘 Quartz 블로그를 대폭 정리했다. Claude Code 를 활용해서 작업했는데, 꽤 효율적이었다.

작업 방식: Claude Code + Docs First

이번 작업의 핵심은 ” 문서 먼저 읽기 ” 였다. Claude Code 에게 Quartz 공식 문서와 기존 코드를 먼저 탐색하게 했다. 덕분에:

새 컴포넌트를 만들지 않고 기존 RecentNotes 활용
ConditionalRender, Footer 등 이미 있는 Higher-Order Component 발견
커스텀 플러그인 없이 permalink frontmatter 로 URL 문제 해결

결과적으로 최소한의 코드 변경으로 원하는 기능을 구현할 수 있었다. 프레임워크를 수정하기 전에 문서부터 확인하는 게 얼마나 중요한지 다시 느꼈다.

주요 변경 사항과 의사결정 과정을 기록한다.

Home Page - Articles List

홈 페이지에서 내가 쓴 글 목록을 보여주고 싶었다. Quartz 문서를 찾아보니 RecentNotes 컴포넌트가 이미 존재했다. 새로 만들 필요 없이 기본 제공 컴포넌트를 활용했다.

처음엔 limit: 10 으로 최근 글만 보여주려 했는데, 무한 스크롤로 전체 목록을 보여주는 게 더 나을 것 같았다. Pagination 을 구현해야 하나 고민했지만, 계산해보니:

현재 글 13 개
500 개까지도 ~200KB, 로딩 시간 거의 없음
정적 사이트라 서버 부하도 없음

결론: limit: 9999 로 전체 표시. Pagination 은 over-engineering 이다.

// quartz.layout.ts
Component.ConditionalRender({
  component: Component.RecentNotes({
    title: "Articles",
    limit: 9999,
    showTags: false,
    filter: (f) => f.slug !== "index",
  }),
  condition: (page) => page.fileData.slug === "index",
}),

© {year} Beomsu Koh 로 변경. 연도는 new Date().getFullYear() 로 동적 처리.

Social links 도 추가:

GitHub, LinkedIn, X, Medium, Tistory, Email

Comments (Giscus)

Giscus 로 댓글을 달 수 있게 해뒀는데, reactions(이모지 반응) 은 필요 없다고 느꼈다. 댓글만 유지하고 reactions 는 비활성화.

Component.Comments({
  provider: "giscus",
  options: {
    repo: "Goberomsu/Quartz-CV",
    repoId: "R_kgDOMzvCAQ",
    category: "Announcements",
    categoryId: "DIC_kwDOMzvCAc4Civ7w",
    reactionsEnabled: false,  // reactions 비활성화
  },
}),

URL Strategy - Permalink

가장 중요한 변경. 폴더 구조가 바뀌면 URL 도 바뀌는 문제가 있었다. 예를 들어 InBox/my-article 에서 Articles/my-article 로 옮기면 기존 링크가 깨진다.

두 가지 옵션을 고려했다:

/posts/ 같은 고정 prefix 사용
permalink 로 flat URL 사용

결론: Flat URL이 더 낫다.

berom.net/my-article 이 berom.net/posts/my-article 보다 짧고 깔끔
SEO 에서도 depth 가 낮을수록 유리
서브도메인 (project.berom.net) 으로 사이드 프로젝트 분리하면 충돌 없음

한글 URL 도 고민했는데, UTF-8 인코딩되면 %EC%82%AC%EB%9E%91… 이런 식으로 길어진다. 영문 slug 가 SEO 에 더 좋다.

규칙:

permalink 는 반드시 영어
kebab-case 사용: my-article-title
이미 영어 제목이면 그대로 유지

# 예시
---
title: 사랑은 사랑이라서
permalink: love-is-love
---

Beomsu

Explorer