페이지

페이지는 Astro 프로젝트의 하위 디렉터리인 src/pages/에 저장된 파일입니다. 이 파일들은 웹사이트의 모든 페이지에 대해 라우팅, 데이터 불러오기, 전체 페이지 레이아웃 처리를 수행합니다.

지원되는 페이지 파일

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

파일 기반 라우팅

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">
  <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) 파일도 동일한 방식으로 처리됩니다. 이는 일반적으로 블로그 게시물 및 문서와 같이 텍스트가 많은 페이지에 사용됩니다.

src/content/ 디렉터리의 Markdown 또는 MDX 콘텐츠 컬렉션을 사용하여 페이지를 동적으로 생성할 수 있습니다.

페이지 레이아웃은 특히 Markdown 파일에 유용합니다. 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 오류 페이지가 방문자에게 표시됩니다.

Added in: astro@4.10.3

개발 모드에서 500.astro 파일이 있는 경우 런타임에 발생한 오류는 오류 오버레이에 표시되는 것이 아니라 터미널에 기록됩니다.

`error`

Added in: 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 : 'Unknown error'}</div>

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

부분적 페이지

Added in: astro@3.4.0

부분적 페이지는 전체 페이지로 렌더링되지 않는 src/pages/ 디렉터리에 있는 페이지 컴포넌트입니다.

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

그러나 특별한 src/pages/ 디렉터리에 존재하기 때문에, 생성된 HTML은 해당 파일 경로에 해당하는 URL에서 사용할 수 있습니다. 이를 통해 렌더링 라이브러리(예: htmx, Stimulus, jQuery)가 클라이언트에서 URL에 접근할 수 있으며, 브라우저 새로 고침이나 페이지 탐색 없이 페이지에서 동적으로 HTML 섹션을 불러올 수 있습니다.

부분적 페이지를 렌더링 라이브러리와 함께 사용하여 Astro에서 동적 콘텐츠를 만들기 위한 Astro 아일랜드 및 <script> 태그의 대안을 제공합니다.

값을 내보낼 수 있는 페이지 파일(예: .astro , .mdx)은 부분적 페이지로 표시될 수 있습니다.

다음과 같이 내보내기를 추가하여 src/pages/ 디렉터리의 파일을 부분적 페이지로 구성하세요.

---
export const partial = true;
---

<li>부분적 페이지입니다!</li>

export const partial은 정적으로 식별 가능해야 합니다. 다음과 같은 값을 가질 수 있습니다.

불리언 값인 true.
import.meta.env.USE_PARTIALS와 같은 import.meta.env를 사용하는 환경 변수.

라이브러리와 함께 사용

부분적 페이지는 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>
</html>
<section>
  <div id="parent-div">대상 요소</div>

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

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

---
export const partial = true;
---
<div>이미 클릭되었습니다!</div>

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

기여하기

커뮤니티

페이지