블로그 테마를 템플릿째 복사해 쓰다가 별도 저장소로 떼어 내면 무엇이 남을까?
답부터 적습니다. 블로그 저장소에는 글과 설정만 남습니다. 2026-11-16 에 Astro 블로그의 테마를 떼어 내자 추적 파일이 152개에서 32개로 줄었습니다. 글 주소 10개는 그대로였습니다. 다음 날 이 사이트를 Hugo 로 옮길 때도 원칙은 같았습니다. 테마는 별도 저장소에 두고, 사이트에는 고정한 사본만 둡니다. 바뀐 것은 테마를 끼우는 방법 하나뿐입니다.
그림으로 줄이면 이렇습니다. 테마는 한 작업대에서 만들고 사이트는 받아 쓰기만 합니다. Astro 블로그는 깃 태그로 받고, Hugo 사이트는 폴더째 복사해 커밋 해시를 적어 둡니다.
- Astro 테마: LeeYudok/astro-theme-doksam
- Hugo 테마: LeeYudok/hugo-theme-doksam
- Astro 블로그: LeeYudok/leeyudok.github.io
전환 작업은 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/ 에 폴더째 사본 |
| 고정하는 값 | 락파일의 커밋 해시 fd819e7 | VERSION 파일의 커밋 해시 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 한 줄로 끝나는지 확인하겠습니다.
참고
- Astro Integration API:
injectRoute와updateConfig - Node.js: Modules: TypeScript:
node_modules아래 타입 제거 제한 - Hugo: Template lookup order: 사이트 템플릿이 테마 템플릿보다 먼저 쓰인다
이 글은 2026-11-17 에 옛 블로그에 올린 글을 2026-11-18 에 다시 확인하고 고쳐 쓴 것입니다.