bokchi's story

WordPress 블로그 첫 화면 세팅 — Site Editor로 안 되는 걸 REST API로 한 이야기

Written by

bokchi

in

WordPress 설치하면 기본 테마에 더미 콘텐츠가 가득하다. 깔끔한 기술 블로그로 바꾸려면 카테고리 정리, 메뉴, 레이아웃, 폰트 등 할 일이 많다. Site Editor로 세팅하다가 한계를 만나서 REST API로 돌파한 기록이다.

Phase 1: REST API로 기본 정리

카테고리를 여러 개 한 번에 만들고, 기본 더미 콘텐츠를 삭제하는 건 REST API가 훨씬 빠르다.

# 카테고리 생성
curl -s -u "사용자:앱비밀번호" -X POST \
  "https://사이트/wp-json/wp/v2/categories" \
  -H "Content-Type: application/json" \
  -d '{"name":"IT 개발 노트","slug":"dev-notes"}'

# Hello world! 영구 삭제
curl -s -u "사용자:앱비밀번호" -X DELETE \
  "https://사이트/wp-json/wp/v2/posts/1?force=true"

?force=true를 안 붙이면 휴지통으로만 가고 영구 삭제가 안 된다.

Phase 2: 테마 커스터마이징

Additional CSS로 적용한 것:

항목 적용값 이유
본문 폰트 LINE Seed KR 한국어 가독성
코드 블록 Catppuccin Mocha (#1e1e2e) 다크 테마 가독성
레이아웃 768px 1컬럼 한줄 35~40자 최적
폴백 폰트 Pretendard → Noto Sans KR 로드 실패 대비

Site Editor 스타일 패널만으로는 웹폰트 로딩이나 코드 블록 테마를 못 건드린다. Additional CSS는 테마 업데이트에도 유지되니까 여기서 처리했다.

문제 1: Blog Home 템플릿에 블록 추가가 안 됨

Post Terms 블록을 Group 안에 넣으려 했는데, Group 바깥에만 추가되고 안으로 이동이 안 됐다. 드래그, Cut/Paste, Insert before 전부 안 됨.

Twenty Twenty-Five 테마의 Post Template 안에 중첩 Group 블록이 있어서 Site Editor의 삽입이 제한되는 거였다.

해결: REST API로 템플릿 HTML을 직접 교체.

# 현재 템플릿 확인
curl -s -u "사용자:앱비밀번호" \
  "https://사이트/wp-json/wp/v2/templates/twentytwentyfive//home" \
  | python3 -c "import sys,json; d=json.load(sys.stdin); print(d['content']['raw'])"

WordPress 템플릿은 Block Markup(HTML 주석 형태 블록 선언)으로 되어있다. 이걸 JSON으로 감싸서 REST API로 보내면 교체된다.

문제 2: Navigation 메뉴가 안 보임

Site Editor에서 헤더에 메뉴 링크를 추가했는데 프론트에서 안 보인다.

WordPress Navigation 블록은 메뉴 데이터를 별도 navigation 포스트 타입으로 저장하고, 헤더의 Navigation 블록이 이걸 ref 속성으로 참조하는 구조다. ref가 안 맞으면 빈 메뉴가 뜬다.

REST API로 navigation 포스트에 메뉴를 채우고, 헤더 템플릿에서 ref를 연결해서 해결.

문제 3: 푸터 메뉴 중복

기본 테마 푸터에 Navigation 블록이 2개 있었다. Site Editor에서 하나를 삭제했지만 남아있었다.

# 푸터를 Paragraph 하나로 교체
curl -s -u "사용자:앱비밀번호" \
  -X PUT "https://사이트/wp-json/wp/v2/template-parts/twentytwentyfive//footer" \
  -H "Content-Type: application/json" \
  -d '{"content":"© 2026 bokchi World"}'

문제 4: CSS 레이아웃 충돌

768px 최대 너비를 적용했는데 헤더/푸터 너비가 불일치.

테마의 --wp--style--root--padding-* CSS 변수와 .is-layout-constrained 클래스가 커스텀 CSS와 충돌했다. root padding 리셋, .wp-site-blocks에 통일 레이아웃 적용, constrained 이중 제약 해제로 해결.

블록 테마(Twenty Twenty-Five 등)를 커스터마이징할 때는 --wp--style-- 변수와 is-layout-constrained 클래스를 먼저 파악해야 한다. 이걸 모르면 CSS 충돌이 끝도 없이 난다.

결과

  • LINE Seed KR + JetBrains Mono 코드 폰트
  • 다크 네이비 본문 + 딥 블루 링크 + 흰 배경
  • 768px 1컬럼 미니멀 레이아웃
  • 헤더~푸터 일관 정렬

정리하면: Site Editor는 기본 편집에 편하지만 블록 중첩에서 한계가 있다. 안 되면 REST API로 우회하면 된다. Navigation 블록의 ref 구조, 블록 테마 CSS 변수를 이해해두면 삽질이 줄어든다.

More posts