사이트 제작기 1부 — 왜 정적 홈페이지로 시작했나

Home /
Class /
정적홈페이지 /
사이트 제작기 1부 — 왜 정적 홈페이지로 시작했나

이 시리즈에 대하여 이 글은 여러분이 지금 보고 계신 jesusiswith.us 사이트가 어떻게 만들어졌는지를, 실제 코드와 폴더를 열어 보며 처음부터 끝까지 소개하는 4부작 시리즈입니다. “홈페이지를 코딩 없이 만들 수 있다"는 말이 정확히 무슨 뜻인지, 그리고 그 안에서 어떤 자동화가 매일 밤 조용히 돌아가고 있는지를 초보자도 이해할 수 있게 풀어씁니다.
1부 (이 글) — 왜 정적 홈페이지인가 & 전체 아키텍처 조망
2부 — 콘텐츠 3구역(Blog · Class · Databank) 대해부
3부 — 매일 밤 도는 자동화 파이프라인 (IT뉴스 · 오늘의 QT)
4부 — 디자인 커스터마이징과 Git 기반 관리자 패널

1. “이 홈페이지에는 서버가 없습니다”

먼저 조금 이상하게 들릴 수 있는 이야기부터 시작하겠습니다. 여러분이 지금 보고 있는 이 사이트에는 “서버"라고 부를 만한 것이 사실상 없습니다. 정확히 말하면, 방문자가 페이지를 요청할 때마다 무언가를 계산해서 화면을 만들어내는 프로그램이 돌아가고 있지 않다는 뜻입니다.

이걸 이해하려면 홈페이지를 만드는 두 가지 방식을 먼저 구분해야 합니다.

동적 홈페이지 vs 정적 홈페이지

구분	동적(Dynamic) 홈페이지	정적(Static) 홈페이지
대표 예시	워드프레스, 네이버 블로그	이 사이트 (Hugo)
작동 방식	방문자가 들어올 때마다 서버가 페이지를 그때그때 생성	미리 완성된 HTML 파일을 그대로 전달
필요한 것	데이터베이스 + 웹서버(항상 켜져 있어야 함)	단순 파일 저장소만 있으면 됨
속도	상대적으로 느림 (매번 조립)	매우 빠름 (이미 만들어져 있음)
보안	로그인·DB·플러그인이 공격 표면	실행되는 코드가 없어 공격 표면 최소
비용	서버 운영비 발생	무료 또는 매우 저렴

비유하자면 이렇습니다.

동적 홈페이지는 손님이 올 때마다 주방에서 요리를 새로 하는 식당입니다. 주방(서버)과 재료 창고(데이터베이스)가 항상 준비되어 있어야 하고, 손님이 몰리면 느려집니다.
정적 홈페이지는 이미 다 만들어 진열해 둔 도시락 가게입니다. 손님은 그냥 완성된 도시락(HTML 파일)을 집어 가면 됩니다. 주방을 24시간 돌릴 필요가 없습니다.

그래서 어떻게 글이 올라가는가

“미리 만들어 둔다"는 건, 글을 쓸 때마다 HTML 파일로 변환(빌드)하는 과정이 한 번 필요하다는 뜻입니다. 이 변환을 해 주는 도구가 바로 Hugo입니다.

글 작성 (Markdown 파일)
      ↓  Hugo가 변환(빌드)
완성된 HTML 파일 (public 폴더)
      ↓  저장소에 업로드
방문자에게 그대로 전달

즉, 우리가 하는 일은 “글쓰기 + 업로드"뿐이고, HTML을 만들어내는 지루한 작업은 Hugo가 대신합니다. 방문자에게는 이미 완성된 파일이 나가기 때문에 빠르고, 해킹당할 실행 코드가 없으니 안전합니다.

💡 왜 교회·선교 사이트에 정적 홈페이지가 잘 맞을까요? 대부분의 콘텐츠(설교, 자료, 소식)가 “한 번 올리면 자주 바뀌지 않는” 성격이기 때문입니다. 실시간 결제나 회원 관리 같은 복잡한 기능이 필요 없다면, 정적 홈페이지는 비용 0원에 가깝고, 관리가 단순하며, 보안 걱정이 거의 없는 최적의 선택입니다.

2. 이 사이트를 떠받치는 다섯 개의 도구

jesusiswith.us는 다음 다섯 가지 도구가 이어져 돌아갑니다. 하나씩 “무슨 일을 하는지"만 먼저 익혀 두면 나머지 시리즈가 훨씬 쉽게 읽힙니다.

글 작성 (Markdown)
    ↓
Hugo (정적 사이트 빌더 = 변환 엔진)
    ↓
Hugoplate 테마 (Tailwind CSS 기반 디자인 양식)
    ↓
GitHub (코드·콘텐츠 저장소 + 모든 수정 이력 보관)
    ↓
Cloudflare Pages (자동 빌드 + 전 세계 배포)
    ↓
jesusiswith.us (실제 서비스 도메인)

도구	역할	한 줄 비유
Markdown	글 작성 형식	특수 기호를 쓰는 메모장
Hugo	마크다운 → HTML 변환기	원고를 책으로 찍어내는 인쇄소
Hugoplate	디자인 템플릿(테마)	인쇄소가 쓰는 디자인 양식
GitHub	파일 저장·버전 관리	클라우드 저장소 + 수정 이력 타임머신
Cloudflare Pages	자동 빌드·배포	원고가 올라오면 자동으로 찍어 전국에 배송

Hugo와 Hugoplate

Hugo는 Go 언어로 만들어진 정적 사이트 빌더입니다. 세상에서 가장 빠른 축에 속해서, 수백 개의 글도 몇 초 만에 HTML로 변환합니다. 실제로 이 사이트의 설정 파일(hugo.toml) 첫 줄은 이렇게 되어 있습니다.

baseURL = "https://jesusiswith.us/"
title = "JIWU Mission | Jesus is with us"
languageCode = "ko-kr"
theme = "hugoplate"

theme = "hugoplate" 이 한 줄이 중요합니다. Hugoplate는 Zeon Studio가 만든 무료 오픈소스 테마로, Tailwind CSS v4 기반의 깔끔한 디자인과 다크 모드·검색·태그·댓글 같은 기능이 이미 갖춰져 있습니다. 우리는 이 테마를 “바닥부터 만들지 않고” 가져와서, 필요한 부분만 우리 입맛에 맞게 고쳐 썼습니다. (그 커스터마이징 이야기가 4부의 주제입니다.)

GitHub — 저장소이자 타임머신

우리가 쓴 모든 글과 코드는 GitHub의 저장소(ccumgol/jiwumission)에 보관됩니다. GitHub는 단순 저장소가 아니라 모든 수정 이력을 기록하는 버전 관리 시스템이기도 합니다. 언제 무엇을 바꿨는지 전부 남기 때문에, 실수해도 과거로 되돌릴 수 있습니다.

Cloudflare Pages — 자동 배송 시스템

여기가 핵심입니다. 우리가 GitHub에 글을 올리면(git push), Cloudflare Pages가 그 변화를 감지해 자동으로 Hugo 빌드를 돌리고, 전 세계 310개 이상의 Edge 서버로 결과물을 뿌립니다. 사람이 “배포” 버튼을 누를 필요가 없습니다.

GitHub 저장소 (Push 감지)
    ↓
Cloudflare Pages 빌드 서버 구동
    ↓
pnpm run project-setup && pnpm run build -- --baseURL $CF_PAGES_URL
    ↓
전 세계 Edge 서버로 캐싱 배포 (수십 초 이내)

📌 이 사이트는 원래 GitHub Pages로 배포하다가 Cloudflare Pages로 이전했습니다. 대역폭이 사실상 무제한이고, 전 세계 캐싱 성능이 훨씬 좋으며, 작업 브랜치별로 미리보기 URL을 주기 때문입니다. 이전 과정의 상세한 기록은 저장소의 docs/cloudflare_build.md 문서에 남아 있습니다.

3. 이 사이트가 만들어진 순서 (구축 히스토리)

이 사이트는 하루아침에 완성된 게 아니라, 약 4개월에 걸쳐 단계적으로 자랐습니다. 큰 흐름만 짚어 보면 다음과 같습니다.

Phase 1 — 기반 구축 (2026년 4월)

Hugoplate 템플릿으로 Hugo 프로젝트를 초기화
GitHub 저장소 생성 및 첫 업로드
자동 배포 파이프라인 연결
홈 화면 배너·소개·사역 안내 카드의 기본 골격 구성

Phase 2 — 콘텐츠 구조 설계 (2026년 4~5월)

커스텀 도메인 jesusiswith.us 연결
콘텐츠를 Blog / Class / Databank 세 구역으로 분리 (2부에서 자세히)
상단 메뉴의 드롭다운 계층 구조 설계
블로그 카드 3열 + 사이드바 레이아웃 완성
댓글 시스템(OpenRemark) 도입

Phase 3 — 기능 고도화 (2026년 5~6월)

Git 기반 관리자 페이지(/admin/) 구현 — 브라우저에서 설정을 바꾸면 자동 배포까지 (4부에서)
섹션별 정렬 기준을 설정으로 제어 (날짜순/제목순 선택)
모든 이미지를 WebP로 최적화하고, 과거 이력의 대용량 PNG를 영구 삭제해 저장소를 989MB → 134MB로 축소

Phase 4 — 일일 콘텐츠 자동화 (2026년 7월)

오늘의 QT 모달 서비스 개시 — 접속하면 그날의 성경 묵상이 팝업으로 (3부에서)
매일의 IT뉴스 섹션 추가 — AI가 매일 뉴스를 생성해 자동 게시
매일 정해진 시각에 자동으로 빌드·배포되는 스케줄러 구성

이 시리즈의 나머지 세 편은 대략 이 Phase 2~4의 결과물을 하나씩 깊이 들여다보는 여정입니다.

4. 프로젝트 폴더 한눈에 보기

마지막으로, 앞으로 자주 등장할 폴더 구조를 미리 익혀 두겠습니다. 지금 다 이해할 필요는 없고, “이런 게 있구나” 정도면 충분합니다.

jiwumission/               ← 프로젝트 루트
│
├── config/_default/       ← Hugo 설정 파일들
│   ├── hugo.toml          ← 사이트 기본 설정 (도메인, 언어)
│   ├── menus.toml         ← 상단/하단 메뉴 구성
│   └── params.toml        ← 테마 파라미터, 정렬, 카드 옵션
│
├── content/               ← 모든 글 (마크다운) ★ 우리가 가장 자주 만지는 곳
│   ├── blog/              ← 블로그 구역
│   ├── class/             ← 강의 구역  (이 글도 여기 class/ssg 안에 있습니다)
│   └── databank/          ← 자료실 구역
│
├── layouts/               ← HTML 레이아웃 템플릿
│   ├── home.html          ← 첫 페이지 (오늘의 QT 모달이 여기 들어 있음)
│   ├── blog/              ← 목록·개별 글 레이아웃
│   └── shortcodes/        ← 마크다운 안에서 쓰는 특수 태그
│
├── assets/css/custom.css  ← 커스텀 스타일 (테마 덮어쓰기)
├── static/admin/          ← 관리자 패널 (GitHub API 기반)
├── archetypes/            ← 새 글 생성 시 기본 템플릿
├── scripts/               ← 자동 푸시 등 유틸리티 스크립트
└── docs/                  ← 제작 매뉴얼·문제 해결 기록

가장 중요한 원칙 하나만 기억하세요. 우리가 글을 쓰는 곳은 오직 content/ 폴더이고, 나머지는 대부분 “한 번 세팅해 두면 알아서 돌아가는” 뼈대입니다.

마치며

1부에서는 “정적 홈페이지가 무엇인지”, 그리고 “이 사이트를 떠받치는 다섯 개의 도구가 어떻게 이어지는지"를 큰 그림으로 살펴봤습니다. 핵심을 세 줄로 요약하면:

이 사이트는 서버·DB 없이 미리 만들어 둔 HTML을 전달하는 정적 홈페이지다.
글쓰기(Markdown) → Hugo 변환 → GitHub 저장 → Cloudflare 자동 배포의 흐름으로 돌아간다.
우리가 손대는 건 거의 content/ 폴더뿐, 나머지는 자동화되어 있다.

다음 2부에서는 이 content/ 폴더 안의 세 구역 — Blog · Class · Databank — 이 각각 어떤 성격을 가지고, 글이 어떤 경로로 채워지는지를 실제 글 개수까지 세어 가며 해부해 보겠습니다.