날짜: 2026-09-15
관련: Astro 블로그 · Notion CMS 방향성
create astro로 만든 프로젝트는 처음부터 폴더가 잡혀 있다. 공식 문서(프로젝트 구조)를 읽고, basic starter 기준으로 내가 이해한 대로 적어 둔다.
루트에 꼭 있는 축은 다섯 가지다. src/는 소스(페이지·컴포넌트·스타일·이미지), public/은 빌드가 손대지 않는 그대로 복사할 파일, package.json은 의존성과 스크립트, astro.config.mjs는 Astro 설정, tsconfig.json은 타입스크립트·에디터 지원이다. 뒤에 둘은 스타터가 넣어 주고, 문서도 두는 쪽을 말한다.
핵심은 src/와 public/을 헷갈리지 않는 것이다. src/ 안 파일은 Astro가 처리·최적화·번들해서 사이트로 만든다. 컴포넌트는 HTML로 렌더되고, CSS는 묶이거나 줄어들 수 있다. 반대로 public/은 손대지 않고 빌드 결과물로 그대로 복사한다. 파비콘, robots.txt, 글꼴처럼 “가공할 필요 없는 것”이 여기다. CSS·JS를 public/에 넣어도 되지만 그때는 번들·최적화가 안 된다. 직접 쓰는 스타일·스크립트는 src/에 두는 편이 맞다.
src/ 안에서 Astro가 예약해 둔 유일한 디렉터리는 src/pages/다. 여기에 지원 형식 파일을 넣으면 그게 곧 URL이 된다. 이 폴더가 없으면 페이지·경로가 없다. index.astro는 홈, about.astro는 /about처럼 파일 이름이 경로가 된다.
나머지 이름은 관례다. src/components/에 헤더·버튼 같은 재사용 조각을 모으고, src/layouts/에 여러 페이지가 공유하는 뼈대(헤더·푸터·본문 슬롯)를 둔다. src/styles/에 전역 CSS를 두는 식이다. 필수는 아니라서 이름을 바꿔도 되지만, 처음엔 이 관례를 따르는 게 문서·예제랑 맞아서 덜 헤맨다. React 컴포넌트도 같은 components/에 섞어 둘 수 있다.
문서 예시 트리에는 src/blog/에 마크다운 글, layouts/PostLayout.astro, pages/posts/[post].astro, content.config.ts, rss.xml.js 같은 것도 나온다. basic starter에는 이 전부 다 있는 건 아니다. 블로그·Notion 연동을 붙일 때 그 자리를 채우면 된다. 우리는 글을 레포 MD가 아니라 Notion에서 읽을 예정이라, “글 폴더” 자리는 Notion fetch 쪽 코드·데이터로 대체될 가능성이 크다. 그래도 페이지·레이아웃·컴포넌트 축은 그대로 쓴다.
정리하면, 라우트는 pages/, 화면 조각은 components/·layouts/, 가공할 자산은 src/, 가공 안 할 자산은 public/, 설정은 루트 astro.config·tsconfig·package.json이다. 아일랜드(일부만 클라이언트에서 살아 있는 UI)는 이 구조 문서의 본문이 아니라 Islands 가이드 쪽 이야기다. 지금은 “어디에 무엇을 두는지”만 먼저 잡아 두면, 나중에 Figma 화면이랑 Notion CMS를 이 골격 위에 붙일 때 덜 헤맨다.
pnpm create astro@latest를 돌리면 네 가지가 나온다.
A basic, helpful starter로 갔다. 샘플 페이지랑 컴포넌트가 조금 들어 있는 기본 골격이다. 문법은 여기서 익히고, 화면은 Figma랑 Notion CMS 기준으로 직접 붙이려 한다.
blog template은 글 목록·태그·MDX가 이미 잡혀 있는 완성형 테마다. 빨리 “블로그만” 띄우기엔 편하지만, 지금 디자인이랑 Notion이 원본인 흐름이랑 안 맞아서 안 골랐다. 뜯느라 더 헤맬 것 같았다.
**docs (Starlight)**는 기술 문서용이라 패스했고, minimal은 빈 껍데라 지금은 basic이 낫다.
폴더 이름은 기본으로 former-force가 나왔는데, 나중에 바꿔도 된다.