[🛠] 검색 결과도 글 목록 카드로 맞추기

✨ GPT-5.5의 요약 　

검색 결과만 JS 문자열로 따로 그리던 구조 때문에 날짜, 카테고리, 조회수가 빠지던 문제를 공통 Liquid 카드와 검색 오버레이 레이아웃 정리로 맞춘 기록.

검색 결과가 너무 낡아 보였다.

홈이나 카테고리 목록에서는 글 카드가 어느 정도 정리되어 있었다. 제목 아래에 날짜가 나오고, 카테고리 배지도 붙고, 조회수도 같은 메타 줄 안에서 보였다.

그런데 검색을 열면 갑자기 다른 구버전 UI가 튀어나왔다.

제목과 요약만 보이고, 언제 쓴 글인지도 바로 안 보였다. 카테고리도 없었다. 조회수도 없었다. 같은 글인데 일반 목록에서는 정보가 있고, 검색 결과에서는 정보가 빠졌다.

원인은 검색 결과만 별도 JS 문자열로 다시 그리고 있던 구조였다.

JS 문자열 렌더링이 검색 결과를 낡게 만들었다

기존 검색은 Lunr가 담당했다.

정적 Jekyll 블로그에서 브라우저 검색을 붙이려면, 빌드 때 검색 store를 만들고 클라이언트 JS가 그걸 찾는 구조가 자연스럽다.

문제는 검색 결과 카드까지 JS가 직접 만들고 있었다는 점이다.

일반 목록은 _includes/archive-single.html이 그리고, 검색 결과는 assets/js/lunr/lunr-en.js가 문자열을 이어 붙여서 만들었다.

대충 이런 구조였다.

일반 목록
-> Liquid include
-> archive__item
-> 날짜, 카테고리, 조회수

검색 결과
-> Lunr JS
-> 직접 만든 HTML 문자열
-> 제목, 요약 정도만 표시

이 구조가 문제였다.

일반 목록에 카테고리 배지를 붙여도 검색 결과는 그대로다. 날짜 표시 규칙을 고쳐도 검색 결과는 그대로다. 조회수 메타를 손봐도 검색 결과는 그대로다.

결국 같은 글 카드를 두 군데에서 따로 유지하는 셈이다.

글 카드 include를 공통 컴포넌트로 분리했다

검색 JS를 더 키우는 대신, HTML을 덜 만들게 했다.

공통 카드 include를 새로 만들었다.

_includes/archive-item-card.html
_includes/archive-item-meta-row.html
_includes/archive-item-categories.html

archive-item-card.html은 글 하나를 받으면 기존 목록과 같은 구조를 만든다.

list__item
archive__item
archive__item-title
archive__item-meta-row
archive__item-excerpt

archive-item-meta-row.html은 날짜, 조회수, 카테고리를 한 줄에 묶는다. 날짜와 조회수는 기존 page__meta.html을 계속 쓰고, 카테고리는 archive-item-categories.html로 뺐다.

그리고 기존 _includes/archive-single.html은 직접 HTML을 들고 있지 않게 했다.

이제는 얇은 wrapper다.

{% include archive-item-card.html document=post type=include.type context="archive" %}

일반 목록도 같은 include를 쓰고, 검색 결과도 같은 include가 만든 HTML을 쓴다.

Lunr store에 완성된 카드 HTML을 넣었다

검색 자체는 여전히 Lunr가 한다.

하지만 검색 결과 HTML은 JS가 만들지 않는다.

Jekyll 빌드 시점에 assets/js/lunr/lunr-store.js에서 각 문서마다 카드 include를 렌더링하고, 그 결과를 html 필드에 넣었다.

title
excerpt
categories
tags
lang
locale
html
url
teaser

검색 JS는 이제 entry.html을 꺼내서 붙이기만 한다.

예전에는 검색 JS 안에 제목 링크, teaser 이미지, excerpt 자르기, HTML 문자열 조립이 섞여 있었다.

var renderSearchResult = function (entry) {
  return entry.html || '';
};

검색 JS가 계속 맡는 일은 검색, locale 필터링, 결과 개수 표시, 결과 삽입 정도다.

검색 결과 조회수는 표시만 하고 집계하지 않는다

검색 결과에 조회수도 보여줄 것인가.

처음에는 뺄 수도 있다고 봤다. 검색 결과가 너무 시끄러워질 수 있고, 동적으로 삽입된 DOM에 조회수를 채우는 타이밍도 따로 봐야 했다.

그런데 일반 목록과 맞춘다면 조회수만 빠지는 것도 이상했다.

그래서 조회수도 검색 결과에 표시하기로 했다. 대신 표시와 집계는 나눴다.

검색 결과 노출은 방문 집계가 아니다.
검색 결과의 조회수는 표시용이다.
실제 방문 집계는 현재 열린 페이지에만 붙는다.

이 블로그의 조회수 요소는 data-page-view-path를 갖는다. 실제 집계 대상은 현재 페이지의 data-page-view-track="true"가 붙은 요소다.

검색 결과 카드는 data-page-view-path만 갖고, data-page-view-track="true"는 갖지 않는다.

즉 검색 결과에 글이 보였다고 그 글의 조회수를 올리지 않는다.

숫자만 보여준다.

동적 검색 결과에도 조회수를 다시 적용한다

검색 결과는 페이지가 처음 로드될 때부터 DOM에 있는 게 아니다.

사용자가 검색어를 입력하면 그때 결과가 삽입된다. 그러면 기존 조회수 스크립트가 페이지 로드 시점에 한 번만 요소를 잡고 끝나는 구조라면, 검색 결과의 조회수는 채워지지 않는다.

그래서 assets/js/custom/visitor-stats.js도 바꿨다.

처음에 document.querySelectorAll("[data-page-view-path]")를 고정해두지 않고, 조회수를 렌더링할 때마다 다시 찾게 했다.

또 analytics payload를 캐시했다.

latestAnalyticsPayload

검색 결과가 다시 렌더링되면 hyuk:search-results-rendered 이벤트를 보낸다.

visitor stats 쪽은 이 이벤트를 듣고, 이미 받아둔 payload가 있으면 그걸로 조회수만 다시 적용한다.

API는 다시 부르지 않게 했다.

검색어를 한 글자 입력할 때마다 조회수 API를 새로 호출하면 구조가 지저분해진다. 검색 결과는 자주 바뀐다. 그때마다 네트워크 요청이 늘어나면 검색 UI가 조회수 시스템을 흔들게 된다.

그래서 흐름은 이렇게 잡았다.

페이지 로드
-> analytics payload 1회 수신
-> 기존 목록/현재 페이지 조회수 렌더링

검색 결과 렌더링
-> 이벤트 발행
-> 캐시된 payload로 새 DOM 조회수만 재적용

이렇게 해두면 검색 결과가 많아져도 카운터를 더럽히지 않는다.

다국어 검색 메타도 locale별로 맞췄다

다국어 블로그 작업 이후로 /en/, /ja/, /zh-Hans/ 같은 locale별 페이지와 collection이 있다. 검색도 locale이 섞이면 안 된다.

검색 store에는 lang과 locale을 넣고, 카드 HTML 자체에도 문서 locale을 기준으로 메타 라벨이 들어가게 했다. 그래서 영어 페이지에서 검색하면 Views, 일본어 페이지에서는 閲覧数처럼 해당 locale 규칙을 따른다.

카테고리도 마찬가지다.

locale prefix 자체가 카테고리 배지로 나오면 안 되므로, archive-item-categories.html에서 locale segment는 건너뛰고 실제 카테고리만 표시한다.

검색 오버레이에 사이드바와 넓은 결과 폭을 복구했다

카드만 맞췄다고 끝이 아니었다.

검색을 열었을 때 결과 폭이 이상하게 좁았다. 일반 목록과 같은 카드 HTML을 쓰는데도, 화면에서는 오른쪽 공간을 제대로 쓰지 못했다.

그리고 더 큰 문제가 있었다. 검색을 열면 사이드 카테고리도 같이 사라졌다.

검색 오버레이는 기존 본문 영역 위에 얹히는 구조가 아니었다. 검색을 열 때 .initial-content를 숨기고, 별도의 #site-search 영역을 보여줬다.

그러니 일반 페이지 안에 있던 sidebar도 같이 사라지는 게 당연했다. 검색 결과 카드만 일반 목록과 맞춰도, 검색 화면의 뼈대가 다르면 결국 또 다른 화면처럼 보인다.

그래서 _includes/search/search_form.html 안에도 sidebar를 넣었다.

<div class="search-content__inner-wrap">
  {% include sidebar.html %}
  <div class="archive search-content__archive">
    ...
  </div>
</div>

결과 영역도 archive search-content__archive로 감쌌다. 검색 결과가 일반 archive 레이아웃 안에서 흐르게 하기 위해서다.

폭을 줄이던 CSS도 따로 풀었다.

Minimal Mistakes의 검색 CSS에는 이런 규칙이 있었다.

.search-content .archive__item {
  @include breakpoint($large) {
    width: 75%;
  }

  @include breakpoint($x-large) {
    width: 50%;
  }
}

검색 결과가 낡아 보였던 이유가 카드 HTML만은 아니었던 셈이다. 큰 화면에서는 결과 카드 자체를 절반 폭으로 줄이고 있었다.

커스텀 SCSS에서 검색 결과 카드는 다시 전체 폭을 쓰게 했다.

.search-content .archive__item {
  width: 100%;
}

그런데 여기서 한 번 더 걸렸다.

일반 archive는 큰 화면에서 오른쪽 sidebar 자리를 비워두려고 padding-inline-end를 갖는다. 검색 오버레이에는 오른쪽 sidebar가 없다. 이 padding을 그대로 두면 검색 결과가 다시 좁아진다.

그래서 검색 오버레이의 archive에만 오른쪽 padding을 껐다.

.search-content .search-content__archive {
  padding-inline-end: 0;
}

카드 렌더링 규칙은 일반 목록과 공유하고, 검색 오버레이의 배치만 검색 화면에 맞게 따로 잡았다.

데스크톱과 모바일 폭까지 맞췄다

먼저 빌드를 돌렸다.

bundle exec jekyll build
node --check _site/assets/js/lunr/lunr-store.js
node --check _site/assets/js/lunr/lunr-en.js
node --check _site/assets/js/custom/visitor-stats.js

생성된 검색 store에는 page__views와 data-page-view-path가 들어갔다.

반대로 검색 카드 HTML 안에는 data-page-view-track="true"가 없었다. 이게 붙으면 검색 결과에 노출된 것만으로 방문 집계가 섞일 수 있다.

그 다음 브라우저에서 한국어 홈, 영어 페이지, 일본어 페이지를 열고 검색을 다시 넣었다.

참고 자료
Keymory
오늘 하루는

결과 카드에는 날짜, 카테고리, 조회수 영역이 일반 목록과 같은 줄에 나왔다. 한국어에서는 조회수, 영어에서는 Views, 일본어에서는 閲覧数 라벨이 보였다.

검색 결과 안에는 data-page-view-track="true"가 없었다. 실제 글 페이지에는 기존처럼 현재 페이지용 tracking element가 하나만 있었다.

검색 오버레이 안에는 sidebar가 다시 들어갔다. 데스크톱 1280px 기준으로 sidebar 항목이 22개 잡혔고, 검색 결과 카드 폭은 약 974px까지 넓어졌다.

모바일 390px에서는 sidebar가 위쪽에 쌓이고, 결과 카드는 345px 폭 안에서 제목, 메타, 요약을 표시했다.

브라우저 콘솔 에러도 없었다.