페이지

페이지는 Astro 프로젝트의 src/pages/ 하위 디렉터리에 있는 파일입니다. 웹 사이트의 모든 페이지에 대한 라우팅, 데이터 로딩 및 전체 페이지 레이아웃을 처리합니다.

지원되는 페이지 파일

Astro는 src/pages/ 디렉터리에서 다음 파일 형식을 지원합니다.

.astro
.md
.mdx (MDX 통합 설치 시)
.html
.js/.ts (엔드포인트로 사용 시)

파일 기반 라우팅

Astro는 파일 기반 라우팅이라는 라우팅 전략을 활용합니다. src/pages/ 디렉터리의 각 파일은 파일 경로를 기반으로 사이트의 엔드포인트가 됩니다.

단일 파일은 동적 라우팅을 사용하여 여러 페이지를 생성할 수도 있습니다. 이를 통해 콘텐츠 컬렉션이나 CMS와 같이, 특수 /pages/ 디렉터리 외부에 콘텐츠가 있는 경우에도 페이지를 만들 수 있습니다.

Astro의 라우팅에 대해 자세히 알아보세요.

페이지 간 링크

Astro 페이지에서 표준 HTML <a> 요소를 작성하여 사이트의 다른 페이지에 연결합니다. 상대 파일 경로가 아닌 루트 도메인에 상대적인 URL 경로를 링크로 사용하세요.

예를 들어, example.com의 다른 페이지에서 https://example.com/authors/sonali/로 연결하려면 다음을 따릅니다.

<a href="/authors/sonali/">Sonali</a>에 대해 더 자세히 알아보세요.

Astro 페이지

Astro 페이지는 .astro 파일 확장자를 사용하며 Astro 컴포넌트와 동일한 기능을 지원합니다.

---
---
<html lang="ko-KR">
  <head>
    <title>나의 홈페이지</title>
  </head>
  <body>
    <h1>나의 웹사이트에 오신 것을 환영합니다!</h1>
  </body>
</html>

페이지는 전체 HTML 문서를 생성해야 합니다. 명시적으로 포함되지 않은 경우 Astro는 기본적으로 src/pages/에 있는 모든 .astro 컴포넌트에 <!DOCTYPE html> 선언과 <head> 콘텐츠를 추가합니다. 부분 페이지로 표시하여 컴포넌트별로 이 동작을 선택 해제할 수 있습니다.

모든 페이지에서 동일한 HTML 요소를 반복하는 것을 방지하려면 공통 <head> 및 <body> 요소를 사용자 정의 레이아웃 컴포넌트로 이동하면 됩니다. 원하는 만큼 레이아웃 컴포넌트를 사용할 수 있습니다.

---
import MySiteLayout from "../layouts/MySiteLayout.astro";
---
<MySiteLayout>
  <p>레이아웃으로 래핑된 페이지 콘텐츠입니다!</p>
</MySiteLayout>

Astro의 레이아웃 컴포넌트에 대해 자세히 알아보세요.

Markdown/MDX 페이지

Astro는 src/pages/의 모든 Markdown (.md) 파일을 최종 웹 사이트의 페이지로 처리합니다. MDX 통합이 설치되어 있는 경우 MDX (.mdx) 파일도 같은 방식으로 처리합니다.

Markdown 파일은 특수 layout 프런트매터 속성을 사용하여 Markdown 콘텐츠를 전체 <html>...</html> 페이지 문서로 래핑하는 레이아웃 컴포넌트를 지정할 수 있습니다.

---
layout: ../layouts/MySiteLayout.astro
title: 나의 Markdown 페이지
---
# 제목

**Markdown**으로 작성된 페이지입니다.

Astro의 Markdown에 대해 자세히 알아보세요.

HTML 페이지

.html 파일 확장자를 가진 파일은 src/pages/ 디렉터리에 배치하여 사이트에서 페이지로 직접 사용할 수 있습니다. 일부 주요 Astro 기능은 HTML 컴포넌트에서 지원되지 않습니다.

사용자 정의 404 오류 페이지

사용자 정의 404 오류 페이지를 만들려면 src/pages에 404.astro 또는 404.md 파일을 생성하면 됩니다.

그러면 404.html 페이지로 빌드됩니다. 대부분의 배포 서비스는 이 페이지를 찾아 사용합니다.

사용자 정의 500 오류 페이지

요청 시 렌더링되는 페이지에 표시할 사용자 정의 500 오류 페이지를 만들려면 src/pages/500.astro 파일을 생성하세요. 이 사용자 정의 페이지는 사전 렌더링된 페이지에서는 사용할 수 없으며 사전 렌더링할 수도 없습니다.

이 페이지를 렌더링하는 동안 오류가 발생하면 호스트의 기본 500 오류 페이지가 방문자에게 표시됩니다.

추가된 버전: astro@4.10.3

개발 중에 500.astro가 있는 경우, 런타임에 발생하는 오류는 오류 오버레이에 표시되는 대신 터미널에 기록됩니다.

`error`

추가된 버전: astro@4.11.0

src/pages/500.astro는 렌더링 중에 발생하는 모든 오류에 대해 자동으로 error prop이 전달되는 특수 페이지입니다. 이를 통해 오류 세부 정보 (예: 페이지 오류, 미들웨어 오류 등)를 사용하여 방문자에게 정보를 표시할 수 있습니다.

error prop의 데이터 타입은 어떤 것이든 될 수 있으며, 이는 코드에서 타입을 지정하거나 값을 사용하는 방식에 영향을 줄 수 있습니다.

---
interface Props {
  error: unknown;
}

const { error } = Astro.props;
---
<div>{error instanceof Error ? error.message : "알 수 없는 오류"}</div>

error prop의 콘텐츠를 표시할 때 중요한 정보가 유출되는 것을 방지하려면 먼저 오류를 평가하고 발생한 오류에 따라 적절한 콘텐츠를 반환하는 것을 고려하세요. 예를 들어, 오류의 스택은 서버의 코드 구조에 대한 정보를 포함하므로 표시하지 않아야 합니다.

페이지 부분 (Page Partials)

추가된 버전: astro@3.4.0

부분은 전체 페이지로 렌더링되지 않는 src/pages/에 위치한 페이지 컴포넌트입니다.

이 폴더 외부에 있는 컴포넌트와 마찬가지로 이러한 파일에는 <!DOCTYPE html> 선언이나 범위가 지정된 스타일 및 스크립트와 같은 <head> 콘텐츠가 자동으로 포함되지 않습니다.

하지만 특수 src/pages/ 디렉터리에 있기 때문에 생성된 HTML은 파일 경로에 해당하는 URL에서 사용할 수 있습니다. 따라서 렌더링 라이브러리 (예: htmx, Stimulus, jQuery)는 클라이언트에서 액세스하여 브라우저 새로 고침이나 페이지 탐색 없이 페이지에서 HTML 섹션을 동적으로 로드할 수 있습니다.

부분은 렌더링 라이브러리와 결합하면 Astro에서 동적 콘텐츠를 구축하기 위한 Astro 아일랜드 및 <script> 태그의 대안을 제공합니다.

partial 값을 내보낼 수 있는 페이지 파일 (.astro 및 .mdx는 가능하지만 .md는 불가능)은 부분으로 표시될 수 있습니다.

---
export const partial = true;
---
<li>여기는 부분 (partial)입니다!</li>

라이브러리와 함께 사용

부분은 htmx와 같은 라이브러리를 사용하여 페이지의 섹션을 동적으로 업데이트하는 데 사용됩니다.

다음 예제는 부분의 URL로 설정된 hx-post 속성을 보여줍니다. 부분 페이지의 콘텐츠는 이 페이지의 대상 HTML 요소를 업데이트하는 데 사용됩니다.

<html>
  <head>
    <title>나의 페이지</title>
    <script src="https://unpkg.com/htmx.org@1.9.6"
      integrity="sha384-FhXw7b6AlE/jyjlZH5iHa/tTe9EpJ1Y55RjcgPbjeWMskSxZt1v9qkxLJWNJaGni"
      crossorigin="anonymous"></script>
  </head>
  <body>
    <section>
      <div id="parent-div">대상 요소</div>

      <button hx-post="/partials/clicked/"
        hx-trigger="click"
        hx-target="#parent-div"
        hx-swap="innerHTML"
      >
        여기를 클릭하세요!
      </button>
    </section>
  </body>
</html>

해당 파일 경로에 .astro 부분이 존재해야 하며, 페이지를 부분으로 정의하는 내보내기를 포함해야 합니다.

---
export const partial = true;
---
<div>클릭하였습니다!</div>

htmx 사용에 대한 자세한 내용은 htmx 문서를 참조하세요.

기여하기 커뮤니티 후원하기