덕삼
블로그

테마는 별도 저장소에, 사이트에는 글과 설정만 — Astro 통합에서 Hugo 사본까지

· 수정 2026-11-18

블로그 테마를 템플릿째 복사해 쓰다가 별도 저장소로 떼어 내면 무엇이 남을까?

답부터 적습니다. 블로그 저장소에는 글과 설정만 남습니다. 2026-11-16 에 Astro 블로그의 테마를 떼어 내자 추적 파일이 152개에서 32개로 줄었습니다. 글 주소 10개는 그대로였습니다. 다음 날 이 사이트를 Hugo 로 옮길 때도 원칙은 같았습니다. 테마는 별도 저장소에 두고, 사이트에는 고정한 사본만 둡니다. 바뀐 것은 테마를 끼우는 방법 하나뿐입니다.

왼쪽 테마 저장소의 작업대에서 로봇이 테마 상자를 만든다. 상자는 위쪽 Astro 블로그 집에는 태그로, 아래쪽 Hugo 사이트 집에는 통째로 복사되어 들어간다. 두 집 안에는 글과 설정만 있다

그림으로 줄이면 이렇습니다. 테마는 한 작업대에서 만들고 사이트는 받아 쓰기만 합니다. Astro 블로그는 깃 태그로 받고, Hugo 사이트는 폴더째 복사해 커밋 해시를 적어 둡니다.

전환 작업은 2026-11-16 저녁에 Claude Code 와 함께 했습니다. 빌드 수치는 그날 제 맥(M4 Pro)에서 잰 값입니다. 저장소 상태와 버전은 2026-11-18 에 다시 확인했습니다.

템플릿을 복사하면 남의 파일이 남고 테마를 올리지 못합니다

이 블로그는 2026년 3월에 AstroPaper 템플릿을 복사해서 시작했습니다. 템플릿을 복사하면 테마 소스가 내 저장소에 섞입니다. 여덟 달 쓰는 동안 세 가지가 걸렸습니다.

문제근거
남의 파일이 남는다전환 커밋에서 테마 사용법 샘플 글 13개, 릴리스 소개 글 4개, 원작자 후원 설정(FUNDING.yml)을 지웠다
테마를 올리지 못한다2026-03-21 커밋 다음 커밋이 2026-11-16 이다. 그 사이 테마 원본의 변경을 한 번도 받지 않았다
화면 구조가 맞지 않는다증시 요약과 개발 글을 첫 화면에 나란히 두고 싶었다. 템플릿은 글 목록 하나만 그린다

새 테마를 입힌 블로그 첫 화면. 왼쪽 칸은 증시 요약, 오른쪽 칸은 개발 글 목록이다

새 테마의 첫 화면입니다. 대표 이미지가 붙는 증시 요약과 제목 위주의 개발 글이 두 칸으로 나란히 섭니다. 템플릿에는 없던 구조입니다.

테마는 Astro 통합으로 화면·설정·스키마를 넣습니다

Astro 통합(integration)은 빌드 설정에 끼어드는 플러그인입니다. 테마를 통합으로 만들면 블로그는 astro.config.ts 에 함수 호출 하나만 더합니다. 테마가 하는 일은 세 가지입니다.

1. 화면을 주입합니다. injectRoute 로 주소와 화면 파일을 잇습니다. 블로그의 src/pages/ 에 파일이 없어도 화면이 생깁니다.

for (const locale of config.locales) {
  const p = locale === config.defaultLocale ? "" : `/${locale}`;
  injectRoute({ pattern: `${p}/`, entrypoint: page("Home.astro") });
  injectRoute({ pattern: `${p}/posts`, entrypoint: page("Posts.astro") });
  for (const section of config.sections) {
    injectRoute({ pattern: `${p}/${section.id}`, entrypoint: page("Section.astro") });
  }
}

2. 설정을 가상 모듈로 넘깁니다. 블로그가 넘긴 옵션을 Vite 플러그인이 virtual:doksam/config 라는 모듈로 만듭니다. 테마의 화면은 이 모듈을 읽습니다.

3. 글 머리말 스키마를 내보냅니다. 블로그의 src/content.config.ts 는 astro-theme-doksam/schema 에서 blogSchema 를 가져다 씁니다.

블로그 쪽 설정은 아래가 핵심입니다. 2026-11-18 기준으로 섹션은 증시·개발·여행 셋입니다.

doksam({
  title: "덕삼ol야기",
  defaultLocale: "ko",
  locales: ["ko", "en"],
  sections: [
    { id: "market", label: { ko: "증시", en: "Markets" } },
    { id: "dev", label: { ko: "개발", en: "Dev" } },
    { id: "travel", label: { ko: "여행", en: "Travel" } },
  ],
  nav: [{ label: { ko: "소개", en: "About" }, href: "/about" }],
});

2026-11-18 에 Astro Integration API 문서를 다시 봤습니다. 문서는 Astro 7.x 기준이고, astro:config:setup 훅의 injectRoute 와 updateConfig 는 그대로 있습니다.

막힌 곳은 네 군데였고, 두 군데는 지금도 처음 판단대로 둡니다

1. 오류 위치가 엉뚱한 줄을 가리켰습니다. 첫 빌드가 Unexpected "!" 로 실패했는데, 가리킨 Base.astro 66번째 줄에는 ! 가 없었습니다. Astro 컴파일러로 파일을 직접 변환해 보니 원인은 템플릿 리터럴 안의 템플릿 리터럴이었습니다.

// 실패
const rssHref = `${lang === config.defaultLocale ? "" : `/${lang}`}/rss.xml`;
// 통과
const rssHref = prefix(lang) + "/rss.xml";

컴파일러와 esbuild 가운데 어느 쪽이 이 문법을 잘못 읽는지는 확인하지 않았습니다. 확인한 것은 이 한 줄을 바꾸면 오류가 사라진다는 사실입니다.

2. 컴포넌트의 스타일이 자식 컴포넌트에 닿지 않았습니다. 밝게·어둡게 버튼에 해와 달 아이콘이 함께 보였습니다. Astro 는 <style> 을 그 컴포넌트가 직접 쓴 요소에만 적용합니다. 아이콘은 다른 컴포넌트가 그렸습니다. 숨김 규칙을 전역 CSS 로 옮겨서 고쳤습니다.

3. 언어별 글 주소는 화면 파일을 둘로 나눴습니다. /posts/[...slug] 와 /[locale]/posts/[...slug] 는 getStaticPaths 가 돌려줄 값이 다릅니다. 그래서 진입 파일을 PostDefault.astro 와 PostLocale.astro 로 나누고 본문은 PostView.astro 하나를 같이 씁니다. 블로그에 설치된 Astro 5.16.6 의 타입 정의(common.d.ts)에는 getStaticPaths 가 받는 routePattern 이 있습니다. 이 값을 쓰면 파일 하나로 합칠 수 있을 것으로 봅니다. 2026-11-18 의 테마 v0.1.5 도 여전히 두 파일이고, 합치는 것은 아직 해 보지 않았습니다.

4. 통합의 진입 파일은 자바스크립트로 썼습니다. index.js 와 schema.js 를 쓰고 타입은 .d.ts 로 따로 둡니다. 패키지는 설치되면 node_modules 에 놓이는데, Node.js 는 그 아래의 타입스크립트 파일을 처리하지 않습니다. 2026-11-18 에 Node.js 문서를 다시 봤습니다. 타입 제거는 v22.18.0 부터 기본으로 켜졌습니다. v24.12.0·v25.2.0 에서는 안정(Stable) 단계가 됐습니다. 그래도 “node_modules 경로 아래의 타입스크립트 파일은 처리하지 않는다"는 문장은 그대로입니다. 실패를 재현해 본 것은 아니고 문서를 따라 피했습니다.

파일은 줄었고, 빌드가 빨라진 것은 일이 줄어서입니다

항목이전 (AstroPaper 복사본)전환 직후2026-11-18
블로그 저장소 추적 파일152개32개43개 (글이 늘었다)
빌드한 쪽 수92쪽56쪽다시 세지 않았다
astro build 시간 (M4 Pro)14.36초약 0.9초다시 재지 않았다
글 주소10개10개, 모두 같음—

추적 파일 수는 전환 커밋 앞뒤를 git ls-tree 로 다시 셌습니다. 빌드 시간은 같은 조건의 비교가 아닙니다. 이전 빌드에는 샘플 글과 글마다 만들던 공유용 이미지가 들어 있었습니다. 새 테마가 빠른 것이 아니라 하는 일이 줄었습니다.

전환 커밋은 파일 130개를 바꿨고 200줄을 더하고 18,911줄을 지웠습니다. 지운 줄 가운데 11,311줄은 락파일 두 개(package-lock.json 9,721줄, pnpm-lock.yaml 1,590줄)입니다. 락파일을 빼면 7,600줄입니다. 테마 저장소의 파일은 v0.1.0 에서 44개, v0.1.5 에서 63개로 늘었습니다.

태그로 받으면 락파일이 커밋을 고정합니다

블로그는 테마를 깃 태그로 가져옵니다. 2026-11-18 의 package.json 은 이렇습니다.

"astro-theme-doksam": "github:LeeYudok/astro-theme-doksam#v0.1.4"

pnpm 은 락파일에 태그가 아니라 커밋 해시가 든 압축 파일 주소를 적습니다. v0.1.0 은 커밋 a4ece0b 였고, 지금 락파일의 v0.1.4 는 fd819e7 입니다. 태그가 나중에 다른 커밋을 가리켜도 락파일을 다시 만들기 전에는 설치 결과가 바뀌지 않습니다.

테마를 고치면 새 태그를 만들고 블로그에서 태그를 바꿉니다. 테마는 2026-11-16 의 v0.1.0 에서 다음 날 v0.1.5 까지 올랐습니다. 블로그는 v0.1.4 까지 따라갔습니다.

v0.1.5 는 Astro 5·6·7 을 모두 받고 Astro base 설정을 지원합니다. 블로그는 아직 이 태그를 받지 않았고 Astro 5.16.6 에 있습니다. 같은 날 npm 의 Astro 최신은 7.4.12 입니다. 언제 올릴지는 블로그가 정합니다. 테마를 떼어 낸 뒤 생긴 선택권입니다.

전환 때 버린 기능 가운데 아카이브 화면, 글마다 만들던 공유용 이미지, 목록의 쪽 나눔은 지금도 없습니다. base 설정은 위의 v0.1.5 에서 다시 들어왔습니다.

Hugo 로 옮긴 뒤에도 원칙은 같고, 끼우는 방법만 바뀌었습니다

2026-11-17 00:14 에 같은 화면을 Hugo 테마로 만든 저장소의 첫 커밋이 올라갔습니다. 같은 날 20:14 에는 이 사이트(www.doksam.com)가 Hugo 와 작은 Go 서버로 바뀌었습니다. 그전에는 Next.js 16 서버였습니다. 전환 커밋 하나에서 파일 242개가 바뀌었고, 더한 줄은 5,029줄, 지운 줄은 6,763줄이었습니다.

이 사이트는 테마를 site/themes/hugo-theme-doksam 에 사본으로 둡니다. 가져온 커밋은 같은 폴더의 VERSION 파일에 적습니다. 지금 값은 원본 저장소의 508043a 입니다. 저장소 지침(AGENTS.md)에는 이렇게 적혀 있습니다.

테마는 고치지 않는다. site/themes/hugo-theme-doksam 은 원본 저장소의 사본이다. 이 사이트만의 화면과 스타일은 site/layouts/, site/assets/css/custom.css 에 둔다. 테마를 고쳐야 하면 원본을 고친 뒤 사본을 통째로 바꾸고 VERSION 을 갱신한다.

이 규칙이 지켜지고 있는지 2026-11-18 에 확인했습니다. 원본의 508043a 를 git archive 로 풀어 사본과 diff -r 로 비교했습니다. assets, i18n, layouts, static, LICENSE, theme.toml 이 모두 같았고, 사본 폴더를 건드린 커밋은 전환 커밋 하나뿐입니다. 원본은 그 뒤 v0.1.4 태그를 더 찍었습니다. 그 태그에서 바뀐 것은 README, 데모 배포 설정, 화면 이미지이고 화면 코드는 그대로입니다.

사이트만의 화면은 site/layouts/ 의 파일 16개와 custom.css 435줄입니다. Hugo 문서에 따르면 사이트와 테마에 같은 이름의 템플릿이 있으면 사이트 것을 씁니다. 그래서 테마를 고치지 않고도 화면을 바꿀 수 있습니다.

두 사이트가 테마를 들이는 방법을 나란히 놓으면 이렇습니다.

Astro 블로그이 사이트 (Hugo)
테마를 들이는 방법package.json 의 깃 태그 의존성site/themes/ 에 폴더째 사본
고정하는 값락파일의 커밋 해시 fd819e7VERSION 파일의 커밋 해시 508043a
사이트만의 화면통합에 넘기는 옵션site/layouts/ 16개, custom.css 435줄
테마 올리기태그를 바꾸고 pnpm install원본 폴더로 통째로 바꾸고 VERSION 갱신
빌드 중 GitHub 접근설치 단계에서 필요필요 없다. 컨테이너 빌드는 COPY site/ 뿐이다

Hugo 테마의 README 는 git submodule 로 설치하라고 안내합니다. 이 사이트는 사본을 골랐습니다. 작업 이슈에는 “사본으로 둔다"는 결정만 있고 이유는 적혀 있지 않습니다. 확인할 수 있는 효과는 위 표의 마지막 줄입니다.

이 방식이 맞는 경우와 틀리는 경우

테마를 떼어 내면 저장소가 둘이 됩니다. 화면 하나를 고치려면 테마 저장소에서 고치고, 태그를 만들고, 사이트에서 버전을 올려야 합니다. 2026-11-18 기준으로 두 테마를 쓰는 곳은 각각 사이트 하나와 데모 사이트뿐입니다. 재사용 이득은 아직 작습니다.

해석은 이렇습니다. 얻은 것은 재사용이 아니라 분리입니다. 글 저장소의 이력에 화면 코드 변경이 섞이지 않고, 남의 템플릿에 딸려 온 파일이 사라졌습니다. 근거는 위의 추적 파일 수와 사본 비교 결과입니다.

이 판단이 틀리는 경우도 있습니다.

  • 블로그를 처음 시작하거나 테마를 거의 고치지 않는다면 템플릿 복사가 빠릅니다. 원본을 따라가지 않을 생각일 때도 그렇습니다.
  • 화면을 하루에도 여러 번 고치는 시기에는 두 저장소 왕복이 짐입니다. 2026-11-17 하루에 Astro 테마 태그를 v0.1.1 부터 v0.1.5 까지 다섯 번 찍었습니다.
  • 사본은 아무도 고치지 않는다는 규칙이 지켜질 때만 뜻이 있습니다. 사본과 원본의 diff -r 에 화면 코드 차이가 나오기 시작하면 사본은 다시 템플릿 복사본이 됩니다.

정리

테마를 떼어 내면 사이트 저장소에는 글과 설정만 남습니다. Astro 에서는 깃 태그와 락파일로, Hugo 에서는 사본과 VERSION 파일로 같은 원칙을 지켰습니다.

다음에 볼 것은 하나입니다. 이 사이트가 처음으로 테마를 올릴 때 폴더 교체와 VERSION 한 줄로 끝나는지 확인하겠습니다.

참고

이 글은 2026-11-17 에 옛 블로그에 올린 글을 2026-11-18 에 다시 확인하고 고쳐 쓴 것입니다.