14 KiB
의사결정 이력
2026-04-16 v0.1.43
포스트 상세의 Read next가 최신 글만 노출되면 홈 목록과 중복되어 탐색 가치가 낮아진다는 요구에 맞춰, 우선순위를 primary_tag 관련 글로 전환했다. 태그 기반 결과가 없을 때만 현재 글 제외 최신 글을 fallback으로 노출하도록 구성해, 관련성 우선과 빈 상태 회피를 함께 만족시키는 방식으로 정리했다.
2026-04-16 v0.1.42
랜딩 용도 페이지는 별도 템플릿 분기보다 콘텐츠 태그(#LD)로 제어하는 쪽이 운영이 단순하다는 요구에 맞춰, tag-hash-ld 조건에서 레이아웃을 단일 컬럼으로 강제했다. 이 모드에서는 좌우 사이드바를 숨기고 .site-shell 최대 폭을 720px로 제한하며, post-header를 숨겨 본문 중심 구성으로 고정했다.
2026-04-16 v0.1.42
사이드바 카테고리는 단순 limit만 걸어두면 Ghost 기본 순서나 게시물 수 기준만으로 잘려서, 운영자가 원하는 태그를 항상 노출하기 어려웠다. 수동 우선순위와 자동 정렬을 함께 만족시키기 위해, 템플릿에서는 태그를 게시물 수 기준으로 넉넉히 가져오고 프런트에서 지정한 slug 목록만 앞쪽으로 재배치한 뒤 최종 노출 개수를 제한하는 방식으로 정리했다. 이렇게 하면 우선 노출 태그는 코드에서 명시적으로 관리할 수 있고, 나머지 슬롯은 여전히 게시물 수 많은 순서로 자연스럽게 채워진다.
2026-04-16 v0.1.41
Ghost Portal Recommendations 모달의 제목/설명은 렌더링 시점이 일정하지 않고, 경우에 따라 iframe 문서 내부에서 생성되어 기존 문서 단일 선택자 접근으로는 치환이 실패했다. 또한 이전 구현은 전역 MutationObserver를 상시 감시로 두고 있어 페이지 체감 지연 가능성이 있었다. 그래서 클릭 시점에 한정해 메인 문서와 접근 가능한 iframe 문서를 함께 탐색하고, 짧은 재시도 구간에서만 텍스트를 치환하는 방식으로 변경했다. 이 방식은 치환 성공률을 높이면서도 상시 관찰 비용을 제거해 안정성을 높인다.
2026-04-16 v0.1.40
홈 메인에서 4개 탭을 유지하면 원본 화면과 다르게 상단 컨트롤이 과해지고, 실제 요구사항인 Featured 강조 흐름이 약해진다. 그래서 탭형 전환 UI를 홈 진입 구조에서 제거하고, Featured가 있을 때만 수평 슬라이드로 노출한 뒤 Latest 리스트를 바로 이어 붙이는 구성으로 정리했다. 이 방식은 원본의 정보 우선순위(Featured -> Latest)를 그대로 따르면서 Ghost featured:true 데이터도 자연스럽게 재사용할 수 있다.
2026-04-16 v0.1.40
최근 수정이 누적되면서 update/spec/map/deploy/history 문서의 버전 표기가 서로 어긋났고, 커밋 메시지도 기존 저장소 패턴과 달라져 추적성이 떨어졌다. 그래서 이번에는 기능 자체를 더 넓게 바꾸기보다, 이미 진행한 홈 히어로/탭 피드/태그 카드 보정 작업을 기준으로 문서 버전 체계를 v0.1.40으로 맞추고 기록 형식을 기존 흐름에 맞춰 정리했다. 이렇게 해야 다음 작업자가 문서와 커밋 히스토리만 보고도 현재 상태를 빠르게 파악할 수 있다.
2026-04-14 v0.1.38
업로드용 zip을 매번 수동 명령으로 만들면 작업 마무리 단계에서 반복 비용이 계속 생긴다. 그래서 현재 package.json 버전을 그대로 파일명에 반영하는 npm run zip:version 스크립트를 추가해, 사용자가 별도 옵션 없이도 바로 업로드용 압축 파일을 만들 수 있게 정리했다. 이 방식이면 버전 표기와 파일명이 자연스럽게 맞춰지고, 이후 반복 작업도 훨씬 단순해진다.
2026-04-14 v0.1.37
참고 사이트의 목록 UX는 페이지 이동보다 하단 버튼으로 다음 목록을 이어 붙이는 방식이었고, 현재 Ghost 기본 {{pagination}} 링크 UI는 그 경험과 다르게 느껴졌다. 그래서 서버 쪽 데이터 구조를 바꾸지 않고, Ghost가 렌더링한 다음 페이지 HTML을 그대로 가져와 목록 부분만 파싱해 append 하는 방식을 선택했다. 이 방식은 기존 템플릿 구조를 크게 해치지 않으면서도, 다음 페이지가 없으면 버튼이 자동으로 사라지는 동작까지 비교적 안전하게 구현할 수 있다.
2026-04-14 v0.1.36
tag.hbs는 개별 태그 아카이브용인데, 사용자가 기대한 화면은 /tags/ 태그 목록 인덱스였다. 확인 결과 테마 안의 링크와 템플릿은 이미 준비돼 있었지만, 로컬 Ghost가 실제로 읽는 .docker/ghost/content/settings/routes.yaml에는 /tags/, /authors/ 라우트가 빠져 있었다. 그래서 테마 템플릿을 더 손대기보다, 로컬 Ghost 설정 라우트를 예시 파일과 맞추는 쪽이 문제 원인과 해결책이 가장 명확하다고 판단했다.
2026-04-14 v0.1.35
Ghost의 tag.hbs는 이미 태그 컨텍스트와 페이지네이션 컨텍스트를 함께 제공하는데, 여기에 다시 {{#tag}} 블록을 감싸면 내부 partial에서 {{pagination}}이 현재 페이징 스코프를 잃을 수 있다. 그래서 태그 템플릿은 블록 헬퍼 없이 현재 컨텍스트를 바로 쓰도록 정리했다. 작성자 템플릿의 아바타는 데이터가 없어서가 아니라 크기 유틸리티가 빠져 실질적으로 보이지 않던 상태였기 때문에, 이미지와 fallback 모두 명시적인 크기를 부여해 화면에 안정적으로 표시되도록 수정했다.
2026-04-14 v0.1.34
우측 사이드바는 레이아웃 복구 과정에서 CSS 구조 중심 마크업으로 너무 많이 되돌아가면서, 사용자가 앞서 적용해둔 Tailwind 기반 정리 흐름이 사실상 사라졌다. 그래서 이번에는 우측 사이드바도 좌측/헤더와 같은 기준으로, sidebar--right와 기존 블록 클래스는 유지하되 실제 배치와 간격은 Tailwind 유틸리티로 다시 표현하는 방식으로 재정리했다. 이렇게 하면 기존 폭 계산과 스타일 훅은 보존하면서도, 사용자가 직접 이어서 수정하기 쉬운 구조를 다시 확보할 수 있다.
2026-04-14 v0.1.33
좌측 사이드바 닫힘 애니메이션이 사라진 직접적인 원인은 데스크톱 접힘 상태에서 .sidebar--left를 display: none으로 처리한 데 있었다. 이 방식은 레이아웃 정리는 쉽지만 전환 프레임이 모두 사라지기 때문에, 이번에는 그리드 첫 열을 0으로 줄이면서 사이드바와 내부 콘텐츠에 opacity와 transform 전환을 주는 방식으로 바꿨다. 이렇게 하면 기존 셸 폭 계산은 유지하면서도 사용자가 기대하는 열리고 닫히는 움직임을 다시 복원할 수 있다.
2026-04-14 v0.1.32
최근 레이아웃 붕괴는 Tailwind 마크업을 유지하려는 수정과, 기존 screen.css 및 theme.js가 기대하는 구조 클래스가 어긋난 것이 함께 겹치면서 발생했다. 그래서 이번에는 원래 셸 구조를 단순 복원하는 대신, site-shell, topbar__inner, sidebar--left, sidebar--right처럼 폭 계산과 토글 동작에 직접 연결된 훅은 유지하고 그 위에만 Tailwind 유틸리티를 다시 얹는 하이브리드 방식으로 정리했다. 이렇게 하면 사용자가 선호하는 Tailwind 중심 수정 흐름을 유지하면서도, 1296px 헤더 정렬과 287px 사이드바 계산 같은 핵심 레이아웃 기준을 다시 안정적으로 보존할 수 있다.
2026-04-14 v0.1.31
zip 업로드 없이 로컬 Ghost에서 바로 확인하려면 자동 sync가 필요했지만, fs.watch 기반 재귀 watcher는 현재 환경에서 EMFILE 오류로 안정적으로 유지되지 않았다. 그래서 별도 의존성을 추가하지 않고, 제외 디렉터리를 뺀 파일 목록의 수정 시간을 주기적으로 비교하는 polling 방식으로 dev:watch를 구현했다. 이 방식은 다소 단순하지만 현재 저장소 크기에서는 충분히 가볍고, 사용자가 템플릿을 저장한 뒤 바로 브라우저 새로고침으로 확인할 수 있다는 점이 더 중요하다고 판단했다.
2026-04-14 v0.1.30
prose는 Tailwind 기본 유틸리티가 아니라 @tailwindcss/typography 플러그인 영역인데, 현재 저장소에는 해당 플러그인이 들어있지 않았다. 이번 단계에서는 사용자가 이미 수정한 Tailwind 마크업을 최대한 유지하는 것이 우선이었기 때문에, 의존성을 새로 늘리기보다 assets/styles/tailwind.css의 @layer components에 원본 소스 기준 타이포그래피 규칙을 직접 옮겨 적용했다. 동시에 bg-accent/10처럼 현재 빌드에서 누락되던 유틸리티도 같은 방식으로 보강해 카드 태그 배경과 리스트 구분선이 다시 보이도록 정리했다.
2026-04-14 v0.1.29
브라우저 기본 h1, button 스타일이 계속 남는 문제는 개별 요소 보정보다 Tailwind 전역 초기화 자체를 다시 켜는 편이 더 맞다고 판단했다. 초기 단계에서 preflight를 꺼두었지만, 현재처럼 Tailwind 마크업 비중이 커진 상태에서는 기본 리셋이 없는 쪽이 오히려 예측 불가능한 차이를 만들기 때문에 preflight를 복원했다.
2026-04-14 v0.1.28
포스트 상세 화면은 기존 post-header, post-meta CSS 구조를 유지한 채 부분 수정하는 것보다, 홈 카드와 같은 기준으로 Tailwind 마크업 쪽으로 맞추는 편이 원본 화면에 더 가깝다고 판단했다. 또한 원본 상세 화면에는 제목 위 별도 태그 라벨이 없기 때문에, 메타 영역 태그만 남기고 상단 중복 태그는 제거했다.
2026-04-14 v0.1.27
포스트 카드의 큰 구조를 Tailwind 기준으로 되돌린 뒤에도, 실제 사용 화면에서는 구분선과 콘텐츠 폭 제약처럼 아주 기본적인 레이아웃 안정화가 먼저 필요했다. 그래서 이번 단계에서는 새 해석을 추가하지 않고, 사용자가 준 구조를 유지한 채 border-b, min-w-0, items-start처럼 레이아웃 안정성에 직접 연결되는 속성만 최소 보정했다.
2026-04-14 v0.1.26
포스트 카드 영역은 원본 구조를 닮게 보이도록 CSS로 따로 해석하는 방식보다, 사용자가 준 Tailwind 마크업 흐름을 직접 반영하는 편이 맞다고 다시 정리했다. 그래서 카드 관련 커스텀 구조를 최소화하고, 부족한 유틸리티만 Tailwind 입력 파일에 보강하는 방향으로 수정했다.
2026-04-14 v0.1.25
포스트 리스트 카드는 이전 단계에서 간격과 밀도만 먼저 끌어올렸지만, 사용자가 원하는 기준은 구조 자체가 원본에 더 가까운 형태였다. 그래서 이번에는 post-items 템플릿을 기준 삼아 마크업 레벨에서 media / content / meta / share action 흐름을 다시 맞추고, 댓글과 우측 액션 아이콘도 지정된 로컬 SVG 자산으로 통일했다.
2026-04-14 v0.1.24
홈 메인 영역은 기존 단순 카드 레이아웃에서 벗어나 원본의 정보 밀도와 간격을 더 직접적으로 따르기로 했다. 다만 좌측 네비게이션과 마찬가지로 즉시 전환보다 현재 선호하는 부드러운 동작과 기존 Ghost 헬퍼 호환성을 유지해야 했기 때문에, 전체 구조를 새로 갈아엎기보다 hero, tabbed-feed, post-items partial 단위로 시각 표현만 단계적으로 끌어올리는 방향을 선택했다.
2026-04-14 v0.1.23
좌측 네비게이션은 원본의 Tailwind/Alpine 구조를 더 직접적으로 따르되, 기존 구현에서 선호한 열고 닫히는 애니메이션은 유지하기로 했다. 또한 /tags/, /authors/는 Ghost 기본 라우트가 아니므로, 페이지 슬러그 방식뿐 아니라 routes.yaml 커스텀 라우트 방식도 함께 지원할 수 있도록 별도 인덱스 템플릿과 예시 라우트 파일을 추가했다.
2026-04-14 v0.1.22
원본 테마와 spacing 차이가 크게 나는 원인 중 하나가 브라우저 기본 리스트 스타일이었다. Tailwind preflight를 끈 상태를 유지하고 있으므로, 필요한 범위의 전역 리셋만 screen.css에 수동으로 추가해 기본 ul, ol, menu 패딩과 불릿을 제거했다. 카테고리 화살표는 회전 기반 표현 대신 상태별 아이콘 교체 방식으로 바꿔 원본과 더 가깝게 맞췄다.
2026-04-14 v0.1.21
카테고리 영역은 기존 JS 아코디언 대신 Alpine.js 문법으로 다시 맞췄다. 원본 테마 코드를 더 직접적으로 참조하는 요구가 생겼고, Tailwind 유틸리티와 Alpine 상태 표현을 함께 쓰는 편이 spacing과 hover 동작을 더 가깝게 재현하기 쉬웠기 때문이다. 또한 Ghost 경고에 맞춰 limit="all" 대신 limit="100"으로 조정했다.
2026-04-14 v0.1.20
앞으로 원본 테마 섹션 코드를 더 직접적으로 참고할 수 있도록 Alpine.js를 로컬 자산으로 포함하기로 했다. 외부 CDN 의존 대신 테마 빌드 단계에서 assets/built/alpine.js를 생성해 함께 배포하고, 기존 theme.js는 즉시 제거하지 않고 공존시키면서 점진적으로 Alpine 문법을 허용하는 방향으로 정리했다.
2026-04-14 v0.1.19
Ghost 업로드 오류에 맞춰 author.hbs의 구식 {{#author}} 블록 헬퍼를 제거했다. 작성자 아카이브 템플릿은 이미 작성자 컨텍스트에서 렌더링되므로, 별도 블록 헬퍼 없이 현재 컨텍스트 값을 직접 사용하는 방식이 Ghost 최신 검사 기준과도 맞다.
2026-04-14 v0.1.18
카테고리 접힘 동작은 Alpine.js를 추가하지 않고 기존 theme.js의 아코디언 로직으로 통일하기로 유지했다. 다만 기존 초기화가 .menu-group에만 한정되어 있어 카테고리 블록이 빠져 있었기 때문에, 아코디언 초기화 대상을 일반화하고 카테고리 블록에만 1024px 기준 반응형 기본 상태를 따로 적용하도록 정리했다.
2026-04-13 v0.1.17
Tailwind CSS를 한 번에 전면 전환하지 않고, 기존 Ghost 테마 구조와 수작업 CSS를 유지한 채 부분 도입하기로 결정했다. 현재 스타일 의존성이 큰 편이라 전면 교체는 레이아웃 붕괴 위험이 높기 때문에, 먼저 빌드 파이프라인만 추가하고 topbar처럼 영향 범위가 작은 영역부터 유틸리티 클래스를 병행 적용하는 방식이 가장 안전하다고 판단했다.