2026-09-03 개발 문서 사이트를 왜 지킬로 만들었나

노션이 아니라 지킬인 이유

문서 도구는 많습니다. 그래도 이걸 택한 이유는 세 가지입니다.

첫째, 칸반이 데이터다. 카드가 문서 안에 그려진 그림이 아니라 _data/ 아래 YAML 의 데이터입니다. 그래서 같은 데이터가 보드, 14일 타임라인, 오늘 할 일, 대시보드 진행률에 동시에 반영됩니다. 상태 한 줄을 고치면 네 군데가 같이 바뀝니다. 옮겨 적을 일이 없습니다.

둘째, 변경 이력이 git 에 남는다. “이 일정 언제 바뀌었지” 를 git log 로 찾을 수 있습니다. 14일 프로젝트에서 이건 생각보다 자주 필요합니다.

셋째, 이미 쓰는 도구다. 새 도구를 배우는 시간이 0입니다. 알아야 할 건 status: 한 줄을 고치고 push 하는 것뿐입니다.

데이터 하나, 화면 넷

_data/ 아래 칸반 YAML
        │
        ├──▶ 보드         4열 칸반 + 날짜별 목록
        ├──▶ 전체 칸반     영역(프론트·백엔드·평가·QA·콘텐츠)별 비교
        ├──▶ 타임라인      14일 (날짜 기준 재배열)
        └──▶ 오늘 할 일 · 대시보드 진행률

status 를 doing 으로 바꾸면 네 화면이 전부 갱신됩니다. 진행률 막대도 같은 데이터에서 계산됩니다.

가독성에 신경 쓴 부분

문서 사이트는 안 읽히면 없는 것과 같습니다. 그래서:

• 한글 본문 행간 1.75 — 영문 기준(1.4)을 그대로 쓰면 한글은 답답합니다
• 어절 단위 줄바꿈 (word-break: keep-all) — 단어 중간에서 안 끊깁니다
• 다크 테마 고정 — 하루 종일 터미널을 보는 눈에 덜 피로합니다
• 왼쪽 고정 목차 — 어디서든 두 번 클릭 안에 원하는 문서로 갑니다
• 모든 카드에 완료 기준(DoD) — 제목만 있는 칸반은 날마다 다르게 해석됩니다

배포

main 에 push 하면 GitHub Actions 가 Jekyll 4 로 빌드해서 Pages 에 올립니다. Pages 기본 Jekyll(3.10) 대신 Actions 를 쓴 건 로컬과 버전을 맞추기 위해서입니다.

빌드가 깨져도 이전 버전이 그대로 서비스되니, 겁내지 말고 고치고 push 하면 됩니다.

사용법

이 사이트 사용법에 정리했습니다. 알아야 할 것은 두 가지뿐입니다 — 카드 상태 바꾸기, 개발일지 쓰기.