유용균

유용균

반갑습니다.

Buy me a coffee Buy Me a Coffee QR 코드

Blog Maintenance Guide

이 문서는 새 작업 세션에서 블로그의 현재 상태와 작업 원칙을 빠르게 파악하기 위한 유지보수 가이드다.

1. 프로젝트 개요

  • 로컬 저장소: C:\Users\yuioo\repos\blog
  • GitHub: https://github.com/BaristaYU/BaristaYU.github.io
  • 기본 브랜치: main
  • 배포 주소: https://yongkyun.com
  • 프레임워크: Jekyll + Minimal Mistakes
  • 테마: dark
  • Obsidian 연결 위치: C:\Users\yuioo\Desktop\wkdir\99_obisidian\03_resource\github blog
  • Obsidian의 블로그 디렉터리는 실제 저장소와 연결되어 있으므로 양쪽에서 별도 복사하지 않는다.

GitHub Pages는 main 브랜치에서 배포된다. 저장소 루트의 CNAME은 반드시 yongkyun.com을 유지한다.

2. 도메인과 HTTPS

  • _config.yml의 url: https://yongkyun.com
  • apex A 레코드:
    • 185.199.108.153
    • 185.199.109.153
    • 185.199.110.153
    • 185.199.111.153
  • www CNAME: baristayu.github.io
  • Cloudflare 레코드는 GitHub Pages 검증을 위해 DNS only로 사용한다.
  • GitHub Pages의 Enforce HTTPS가 활성화되어 있다.
  • 정상 동작:
    • http://yongkyun.com → https://yongkyun.com/
    • https://www.yongkyun.com → https://yongkyun.com/

도메인을 바꾸면 CNAME, _config.yml의 url, GitHub Pages Custom domain을 함께 변경한다.

3. 현재 디자인 원칙

  • 전체적으로 작고 간결한 스타일을 유지한다.
  • 다크 테마를 유지한다.
  • 카테고리 hover는 색을 바꾸지 않고 밑줄만 표시한다.
  • About 페이지와 공유 영역은 사용하지 않는다.
  • 검색은 포스트만 대상으로 한다.
    • _config.yml: lunr.search_within_pages: false
  • 사이드바 카테고리 글 수는 site.posts에서 자동 집계한다.
  • 메인, 카테고리, Portfolio, Recommended 제목은 같은 위치·크기·가로선을 사용한다.

데스크톱

  • 상단: YONGKYUN 로고, Portfolio, Recommended, 인라인 검색창
  • 좌측: 프로필, 연락처, 카테고리, Buy Me a Coffee 및 QR
  • 사이드바와 본문 사이에는 별도 여백이 적용되어 있다.

모바일 (<= 768px)

  • 닫힌 헤더: 왼쪽 햄버거 버튼과 YONGKYUN 로고만 표시
  • 햄버거 메뉴 순서:
    1. Portfolio / Recommended
    2. 검색창
    3. 카테고리
    4. 프로필 및 연락처
    5. Buy Me a Coffee
  • assets/js/mobile-menu.js가 검색창과 본문 사이드바 DOM을 모바일 패널로 이동한다.
  • 화면이 다시 넓어지면 검색창과 사이드바를 원래 데스크톱 위치로 복원한다.
  • 검색창이나 사이드바를 복제하면 ID 충돌이 생길 수 있으므로 현재의 DOM 이동 방식을 유지한다.

4. 프로필과 사용 이미지

현재 images/에서 실제 사용하는 파일은 다음 네 개다.

파일 용도
images/logo.png 투명 배경의 헤더 로고
images/yongk_crop_2.jpg 프로필 사진
images/bmc_qr.png Buy Me a Coffee QR
images/thubnail.png 카카오톡 등 소셜 공유용 기본 Open Graph 이미지

현재 프로필 소개는 반갑습니다.다.

새 포스트에서 이미지를 추가할 때는 images/에 저장하고 Markdown에서 /images/파일명으로 참조한다. 이미지 정리 전에는 _config.yml, _includes, _pages, _posts의 참조를 반드시 검색한다.

5. 카테고리

카테고리의 표시명은 한글, frontmatter 키와 URL은 영문을 사용한다.

그룹 표시명 category 키 URL
취미 커피 coffee /coffee
취미 음악 music /music
IT 데이터 data /data
IT AI ai /ai
IT 생산성 productivity /productivity
IT 인프라 infra /infra
IT 논문 paper /paper

카테고리 내비게이션은 _data/blog_categories.yml, 페이지는 _pages/category-*.md에서 관리한다. 두 파일의 URL과 category 키가 일치해야 한다.

6. 포스트 작성

포스트 경로:

_posts/YYYY-MM-DD-제목.md

기본 frontmatter 예시:

---
title: "포스트 제목"
date: YYYY-MM-DD HH:MM:SS +0900
categories: [coffee]
tags: [태그1, 태그2]
toc: true
toc_sticky: true
excerpt: "미리보기 문장"
---

categories에는 위 표의 영문 category 키를 사용한다. 현재 _posts에는 게시물이 없으며, 새 글이 추가되면 전체보기와 각 카테고리 숫자가 자동 갱신된다.

7. 주요 구현 파일

  • _config.yml: 도메인, 검색, 프로필, 사이트 설정
  • _data/blog_categories.yml: 사이드바 카테고리 구조
  • _includes/masthead.html: 데스크톱 헤더와 모바일 메뉴 마크업
  • _includes/sidebar.html: 카테고리 및 Buy Me a Coffee
  • _includes/author-profile.html: 프로필과 연락처
  • _includes/seo.html: 브라우저 제목 및 SEO
  • _layouts/archive.html: 공통 제목 레이아웃
  • _layouts/blog-category.html: 카테고리 목록
  • _layouts/blog-page.html: Portfolio와 Recommended 공통 레이아웃
  • _sass/custom/_blog-layout.scss: 대부분의 커스텀 반응형 스타일
  • _sass/minimal-mistakes/_sidebar.scss: 프로필과 사이드바 기본 스타일
  • assets/js/header-search.js: Lunr 헤더 검색
  • assets/js/mobile-menu.js: 모바일 메뉴와 DOM 이동

메인 CSS와 커스텀 JavaScript URL에는 site.time 기반 버전이 붙어 있어 배포 캐시 혼합을 줄인다. GitHub Pages HTML 자체는 최대 약 10분 캐시될 수 있다.

8. 안전한 작업 절차

작업 시작 시:

cd "C:/Users/yuioo/repos/blog"
git status --short --branch
git fetch origin
git rev-list --left-right --count HEAD...origin/main

원격이 앞서 있고 로컬 작업과 충돌하지 않으면 먼저 동기화한다.

git pull --ff-only origin main

작업 원칙:

  1. 사용자가 수정한 파일을 임의로 덮어쓰지 않는다.
  2. 작업 대상 파일만 명시적으로 stage한다.
  3. 관련 없는 로컬 변경은 커밋에서 제외한다.
  4. 삭제 전에는 rg로 실제 참조 여부를 확인한다.
  5. push 전에 git diff --check와 Jekyll 빌드를 실행한다.
  6. push 후 실제 https://yongkyun.com 결과를 확인한다.

9. 로컬 빌드

Ruby와 Bundler가 설치되어 있으면:

bundle install
bundle exec jekyll build
bundle exec jekyll serve

로컬 미리보기:

http://127.0.0.1:4000

Docker 검증 예시:

docker run --rm -it -v "C:/Users/yuioo/repos/blog:/src:ro" ruby:3.3-bookworm bash

컨테이너 내부:

cp -a /src /tmp/blog
cd /tmp/blog
gem install bundler -v 2.5.14 --no-document
bundle lock --add-platform x86_64-linux
bundle install
bundle exec jekyll build

빌드 성공만 보지 말고 생성 HTML에서 canonical URL, 카테고리 링크, 이미지 경로, 모바일 메뉴 마크업도 확인한다.

10. 배포 확인

push 후 다음 항목을 확인한다.

  • https://yongkyun.com이 200 OK
  • http://yongkyun.com이 HTTPS로 301 이동
  • https://www.yongkyun.com이 apex로 이동
  • 새 카테고리 페이지가 200 OK
  • canonical URL이 .com
  • 모바일 407px 전후에서 햄버거 메뉴가 정상 동작

배포가 늦어 보이면 GitHub Pages 빌드와 최대 10분의 캐시를 고려하고, 브라우저에서는 강력 새로고침 또는 시크릿 창으로 확인한다.