src/pages

페이지(Page)

Astro에서 페이지는 프로젝트의 src/pages/ 하위 폴더에 들어 있는 파일이에요. 파일 하나가 곧 '웹사이트의 한 페이지'가 되는 책임을 지는데, 라우팅과 데이터 로딩, 그리고 전체 페이지 레이아웃을 담당해요. 이 폴더 구조가 어떻게 페이지를 만들어 내는지 하나씩 볼게요.

출처: 공식문서

본문

지원하는 페이지 파일

Astro는 src/pages/ 폴더에서 다음 파일 형식을 모두 페이지로 지원해요.

  • .astro
  • .md
  • .mdx (MDX Integration이 설치된 경우)
  • .html
  • .js / .ts (엔드포인트로 사용)

파일 기반 라우팅

Astro는 파일 기반 라우팅(file-based routing) 전략을 써요. src/pages/ 폴더의 각 파일은 그 파일 경로를 기준으로 사이트의 엔드포인트가 돼요.

하나의 파일이 동적 라우팅으로 여러 페이지를 만들어 낼 수도 있어요. 이렇게 하면 콘텐츠가 /pages/ 폴더 밖(예: 콘텐츠 콜렉션이나 CMS)에 있어도 페이지를 만들 수 있어요.

페이지 사이 링크

Astro 페이지에서 다른 페이지로 연결할 때는 표준 HTML <a> 요소를 쓰면 돼요. 링크는 상대 파일 경로가 아니라 루트 도메인 기준의 URL 경로를 사용해야 해요.

Astro 페이지

Astro 페이지는 .astro 확장자를 쓰고, Astro 컴포넌트와 동일한 기능을 지원해요.

---
---
<html lang="en">
  <head>
    <title>My Homepage</title>
  </head>
  <body>
    <h1>Welcome to my website!</h1>
  </body>
</html>

페이지는 완전한 HTML 문서를 만들어 내야 해요. 명시하지 않으면 Astro는 src/pages/ 안에 있는 .astro 컴포넌트에 필요한 <!DOCTYPE html> 선언과 <head> 내용을 기본으로 추가해 주거든요. 이 동작을 끄고 싶으면 해당 컴포넌트를 **부분 페이지(partial)**로 표시하면 돼요.

매 페이지에서 같은 HTML 요소를 반복하지 않으려면, 공통 <head>와 <body> 요소를 레이아웃 컴포넌트로 옮기면 돼요. 레이아웃은 몇 개를 쓰든 자유예요.

---
import MySiteLayout from '../layouts/MySiteLayout.astro';
---
<MySiteLayout>
  <p>My page content, wrapped in a layout!</p>
</MySiteLayout>

Markdown/MDX 페이지

Astro는 src/pages/ 안의 Markdown(.md) 파일도 최종 사이트의 페이지로 취급해요. MDX Integration이 설치돼 있으면 MDX(.mdx) 파일도 같은 방식으로 다뤄요.

Tip: 구조가 비슷한 Markdown 파일들을 모아 관리한다면(블로그 글이나 상품 목록처럼) 페이지보다는 콘텐츠 콜렉션으로 만드는 걸 권장해요.

Markdown 파일은 특별한 layout frontmatter 속성으로, 자신의 Markdown 콘텐츠를 감싸는 레이아웃 컴포넌트를 지정할 수 있어요.

---
layout: ../layouts/MySiteLayout.astro
title: My Markdown page
---
# Title

This is my page, written in **Markdown.**

페이지 부분(Page Partials)

부분 페이지는 렌더링 라이브러리(예: htmx, Unpoly)와 함께 쓸 때 Astro islands와 <script> 태그의 대안이 돼요. partial 값을 export할 수 있는 페이지 파일(.astro, .mdx 등 .md 제외)은 부분 페이지로 표시할 수 있어요.

.astro 부분은 대응하는 파일 경로에 있어야 하고, 페이지가 부분임을 알리는 export를 포함해야 해요.

---
export const partial = true;
---
<div>I was clicked!</div>

활용 예시는 htmx 문서를 참고하세요. htmx는 전체 HTML 페이지 대신 페이지 조각(fragment)을 교환하는 방식으로 동적 UI를 만들거든요.

더 알아보기