2강. 프로젝트 구조 이해하고 첫 페이지 만들기

1강에서 만든 프로젝트를 열어 보면 여러 폴더와 파일이 있습니다. 이번 강의에서는 각 폴더가 어떤 역할을 하는지 알아보고, 페이지를 하나 추가해 봅니다.

폴더 구조 한눈에 보기

my-astro-site/
├── public/            # 그대로 복사되는 정적 파일 (파비콘, robots.txt 등)
├── src/
│   ├── components/    # 재사용 가능한 UI 조각
│   ├── layouts/       # 페이지의 공통 뼈대 (헤더·푸터 포함)
│   ├── pages/         # ★ 여기 파일이 곧 사이트의 주소가 됩니다
│   └── styles/        # 전역 CSS
├── astro.config.mjs   # Astro 설정 파일
├── package.json       # 프로젝트 정보와 명령어
└── tsconfig.json      # TypeScript 설정

`src/pages/` — 가장 중요한 폴더

Astro는 파일 기반 라우팅을 사용합니다. src/pages/ 안에 있는 파일의 경로가 그대로 웹사이트 주소가 됩니다.

파일 경로	웹 주소
`src/pages/index.astro`	`/` (홈)
`src/pages/about.astro`	`/about`
`src/pages/blog/index.astro`	`/blog`
`src/pages/blog/first-post.astro`	`/blog/first-post`

별도의 라우터 설정 없이 파일만 만들면 페이지가 생깁니다.

`public/` — 있는 그대로 복사

public/ 폴더의 파일은 아무 처리 없이 그대로 배포됩니다. 파비콘, robots.txt, 폰트 파일처럼 가공이 필요 없는 파일을 넣습니다. public/favicon.svg는 /favicon.svg 주소로 접근합니다.

`src/components/` 와 `src/layouts/`

둘 다 .astro 파일이 들어가지만 역할이 다릅니다. 컴포넌트는 버튼, 카드처럼 작은 UI 조각이고, 레이아웃은 헤더와 푸터를 포함한 페이지 전체의 틀입니다. 자세한 내용은 3강에서 다룹니다.

.astro 파일의 구조

.astro 파일은 두 부분으로 나뉩니다. 위쪽 --- 사이는 컴포넌트 스크립트(빌드 시 실행되는 자바스크립트), 아래쪽은 템플릿(HTML)입니다.

---
// 여기는 빌드 시점에 서버에서 실행됩니다. 브라우저로 전달되지 않습니다.
const siteName = 'My Astro Site';
const today = new Date().toLocaleDateString('ko-KR');
---

<!-- 여기부터는 HTML 입니다. 중괄호로 위의 변수를 사용할 수 있습니다. -->
<h1>{siteName}</h1>
<p>오늘은 {today} 입니다.</p>

중요한 점은 --- 사이의 코드가 브라우저에서 실행되지 않는다는 것입니다. 빌드할 때 한 번 실행되어 결과가 HTML로 굳어집니다. 그래서 API 키를 다루거나 파일을 읽는 코드를 넣어도 방문자에게 노출되지 않습니다.

첫 페이지 만들기

src/pages/about.astro 파일을 새로 만들고 아래 내용을 넣어 봅니다.

---
const skills = ['HTML', 'CSS', 'Astro'];
---

<html lang="ko">
  <head>
    <meta charset="utf-8" />
    <title>소개</title>
  </head>
  <body>
    <h1>소개 페이지</h1>
    <p>Astro를 배우고 있습니다.</p>
    <ul>
      {skills.map((skill) => <li>{skill}</li>)}
    </ul>
    <a href="/">홈으로</a>
  </body>
</html>

저장한 뒤 브라우저에서 http://localhost:4321/about을 열면 페이지가 나타납니다. skills.map(...) 부분은 배열을 반복해 <li>를 만드는 문법으로, React의 JSX와 비슷합니다.

동적 라우트 맛보기

파일 이름을 대괄호로 감싸면 여러 주소를 한 파일로 처리할 수 있습니다. 예를 들어 src/pages/blog/[slug].astro는 /blog/aaa, /blog/bbb 같은 주소를 모두 담당합니다. 이때 어떤 주소를 만들지 getStaticPaths() 함수로 알려줘야 하는데, 이는 4강에서 블로그를 만들며 자세히 다룹니다.

정리

src/pages/의 파일 경로가 곧 URL입니다. 파일을 만들면 페이지가 생깁니다.
.astro 파일은 --- 위쪽 스크립트(빌드 시 실행)와 아래쪽 HTML 템플릿으로 구성됩니다.
public/은 그대로 복사되는 정적 파일 보관소입니다.

다음 강의에서는 페이지마다 반복되는 <html>, <head>, 헤더, 푸터를 레이아웃과 컴포넌트로 분리하는 방법을 배웁니다.