Custom Tag Article List - 태그 기반 필터링 아티클 리스트

배경

Quartz v4의 기본 태그 시스템은 /tags/[tagname] 경로에서 해당 태그를 가진 글 목록을 보여주는 단순한 구조다. 글이 적을 때는 충분하지만, 태그가 수십 개로 늘어나면 문제가 생긴다.

태그 간 계층 관계를 표현할 수 없다. cs/operating-system과 cs/programming-language는 모두 cs 카테고리에 속하지만, 기본 태그 페이지에서는 이 관계가 드러나지 않는다.
특정 분야의 글만 빠르게 훑어보려면 태그 페이지를 하나씩 돌아다녀야 한다.
한 페이지에서 태그를 선택하고, 필터링된 결과를 즉시 확인하는 인터랙션이 없다.

목표는 명확했다. 계층적 태그 필터링이 가능한 인터랙티브 아티클 리스트를 만드는 것. Primary tag를 선택하면 하위 sub-tag가 노출되고, 아티클 목록이 실시간으로 필터링되는 구조다. 우아한형제들 기술 블로그의 태그 필터링 UI를 레퍼런스로 참고했다.

코드 블록 트리거 방식

Quartz는 마크다운을 HAST(HTML Abstract Syntax Tree)로 변환한 뒤 JSX 컴포넌트로 렌더링한다. 여기서 핵심 아이디어는 코드 블록의 language identifier를 트리거로 사용하는 것이다.

마크다운에 다음과 같은 코드 블록을 삽입하면 컴포넌트가 활성화된다:

```article-list
```

Quartz의 Rehype Pretty Code 플러그인이 이 코드 블록을 <pre data-language="article-list">로 변환하고, hasArticleListBlock() 함수가 HAST 트리를 순회하며 이 노드를 탐지한다.

quartz/components/l88_CustomTagArticleList.tsx

function hasArticleListBlock(tree: Root): boolean {
  let found = false
  visit(tree, "element", (node: Element) => {
    if (
      node.tagName === "pre" &&
      node.properties?.dataLanguage === "article-list" // [!code highlight]
    ) {
      found = true
    }
  })
  return found
}

이 함수가 true를 반환해야만 컴포넌트가 렌더링된다. false면 null을 반환하여 아무것도 출력하지 않는다.

이 방식의 장점은 별도의 설정 파일이나 frontmatter 옵션 없이, 마크다운 본문에 코드 블록 하나를 삽입하는 것만으로 동적 컴포넌트를 활성화할 수 있다는 것이다. 마크다운의 선언적 특성을 그대로 유지하면서 확장 가능한 패턴이다.

계층적 태그 구조

슬래시 네임스페이스

태그 계층은 슬래시(/)로 구분된 네임스페이스 규칙을 따른다.

cs/operating-system - primary tag는 cs, sub-tag는 cs/operating-system
dev/blog-customization - primary tag는 dev, sub-tag는 dev/blog-customization
unity - sub-tag 없이 primary tag만 존재

태그 계산 로직

빌드 시점에서 모든 페이지의 태그를 순회하며 세 가지 Map을 구축한다.

quartz/components/l88_CustomTagArticleList.tsx

// 1. 전체 태그별 글 개수
const tagCounts = new Map<string, number>()
// 2. Primary tag(첫 번째 세그먼트)별 글 개수
const primaryTagCounts = new Map<string, number>()
 
pages.forEach((page) => {
  const tags = page.frontmatter?.tags ?? []
  const seenPrimary = new Set<string>()
  tags.forEach((tag) => {
    tagCounts.set(tag, (tagCounts.get(tag) || 0) + 1)
    const primary = tag.split("/")[0]
    if (!seenPrimary.has(primary)) {
      seenPrimary.add(primary)
      primaryTagCounts.set(primary, (primaryTagCounts.get(primary) || 0) + 1)
    }
  })
})
 
// 3. Primary tag별 하위 sub-tag 목록
const subTagsByPrimary = new Map<string, string[]>()
primaryTags.forEach((primary) => {
  const subs = [...tagCounts.keys()]
    .filter((tag) => tag.startsWith(primary + "/"))
    .sort((a, b) => (tagCounts.get(b) || 0) - (tagCounts.get(a) || 0))
  if (subs.length > 0) {
    subTagsByPrimary.set(primary, subs)
  }
})

seenPrimary Set은 한 페이지가 cs/operating-system과 cs/programming-language 태그를 동시에 가질 때 cs의 카운트가 중복으로 올라가는 것을 방지한다.

표시 태그 필터링

한 페이지에 cs와 cs/operating-system이 모두 태그되어 있다면, 아티클 카드에 cs를 표시할 필요는 없다. 자식 태그가 존재하면 부모 태그를 숨기는 getDisplayTags() 함수가 이를 처리한다.

quartz/components/l88_CustomTagArticleList.tsx

const getDisplayTags = (tags: string[]) =>
  tags.filter(
    (tag) => !tags.some((t) => t !== tag && t.startsWith(tag + "/")) // [!code highlight]
  )

tag + "/" 접두사를 가진 다른 태그가 존재하면 해당 태그는 필터링된다. 단순하지만 계층 구조에서 중복 표시를 효과적으로 제거한다.

SSG + 클라이언트 사이드 하이드레이션

SSG: Hidden div 렌더링

SSG(Static Site Generation) 단계에서는 모든 태그 버튼, sub-tag 그룹, 아티클 카드를 display: none 상태의 컨테이너에 렌더링한다.

quartz/components/l88_CustomTagArticleList.tsx

<div id="customTagArticleList-data" style="display:none" data-items-per-page={opts.itemsPerPage}>
  <div class="tagList">
    <span class="tag-select-button all selected" data-tag="all">
      All ({pages.length})
    </span>
    {primaryTags.map((tag) => (
      <span class="tag-select-button" data-tag={tag}>
        {tag} ({primaryTagCounts.get(tag)})
      </span>
    ))}
  </div>
  {/* sub-tag groups, article cards, see more button */}
</div>

HTML은 빌드 타임에 완전한 형태로 렌더링되므로 검색 엔진 크롤러가 모든 아티클 링크에 접근할 수 있다. SEO와 인터랙티브 UI를 동시에 확보하는 구조다.