글, 시리즈, 태그, 썸네일을 이 테마에서 다루는 방법

이 테마에서 포스트는 Jekyll 기본 규칙을 따르면서도, 개발 블로그에 자주 필요한 메타데이터를 조금 더 얹어서 씁니다. 핵심은 “글 파일은 단순하게 유지하고, 시리즈 이름이나 UI 문구는 별도 데이터 파일에 분리한다”는 점입니다.

기본 front matter

가장 많이 쓰는 형태는 아래 정도입니다.

---
title: 글 제목
description: 목록에 보일 요약
date: 2026-04-03 09:00:00 +0900
updated_at: 2026-04-03 21:00:00 +0900
thumbnail: /assets/images/posts/my-post-cover.png
series: theme-overview
tags:
  - Jekyll
  - Theme
---

각 필드가 화면에서 쓰이는 곳

필드	쓰이는 위치
`title`	글 목록 제목, 상세 제목
`description`	글 카드 요약 문구
`thumbnail`	카드 상단, 글 상세 상단
`series`	시리즈 카드 제목, 시리즈 필터
`tags`	홈 태그 목록, 글 상세 태그 링크
`updated_at`	수정일 표기, 최신 정렬 기준

시리즈를 붙이는 방식

포스트는 series: theme-overview처럼 키만 넣고, 실제 표시용 제목과 설명은 _data/series.yml에 둡니다.

이렇게 분리하면 같은 시리즈 이름을 여러 글에서 반복 입력할 필요가 없고, 시리즈 카드 문구를 한 곳에서 수정할 수 있습니다.

태그는 어떻게 보이는가

태그는 두 군데에서 동시에 쓰입니다.

홈 왼쪽 태그 패널
글 카드와 글 상세의 태그 링크

그래서 태그는 단순 메모 용도가 아니라 실제 탐색 체계라고 생각하고 붙이는 편이 좋습니다. 너무 세분화하면 목록이 지저분해지고, 너무 넓으면 필터 가치가 떨어집니다.

썸네일 규칙

이 테마는 thumbnail이 있을 때만 이미지를 그립니다.

카드: thumbnail이 있을 때만 표시
상세: thumbnail이 있을 때만 상단 이미지 표시
시리즈 카드: 대표 글의 thumbnail이 있을 때만 표시

즉, 이미지가 없는 글은 텍스트 중심 카드로 자연스럽게 남고, 이미지가 있는 글만 시각적으로 강조됩니다.

커버 이미지 준비 팁

오픈소스 데모 저장소라면 썸네일도 대충 넣기보다 기준을 정해 두는 편이 좋습니다.

너무 작은 이미지는 피하기
카드와 상세 모두에서 자연스럽게 보이도록 가로형 비율 사용
저작권 출처를 NOTICE.md에 남기기
데모용이라면 분위기가 비슷한 이미지를 한 세트로 맞추기

이 저장소는 실제 공개용 데모로 보이도록 코드 화면, 작업 환경, 노트북 사용 장면처럼 개발 블로그와 자연스럽게 어울리는 커버 이미지를 사용합니다.

Markdown 지원 범위

현재 데모 글 기준으로 확인해 둔 요소는 다음과 같습니다.

제목과 일반 문단
리스트와 체크리스트
표
코드 블록
이미지
링크
인용문
raw HTML
YouTube iframe

문서형 블로그에 필요한 기본 범위는 충분히 커버한다고 보면 됩니다.

글 발행 전 체크리스트

실제 운영에서는 아래 정도만 확인하면 안정적입니다.

description이 카드 요약으로 자연스러운지
tags가 너무 많지 않은지
series 키가 _data/series.yml에 존재하는지
thumbnail 경로가 실제 자산과 일치하는지
updated_at를 수정했는지

이 기준만 지켜도 홈 목록, 시리즈, 상세 화면이 한 번에 자연스럽게 맞춰집니다.