AstroPaper 테마 설정 방법

AstroPaper는 높은 수준의 커스터마이징이 가능한 Astro 블로그 테마입니다. AstroPaper를 사용하면 개인 취향에 맞게 모든 것을 커스터마이징할 수 있습니다. 이 글에서는 설정 파일에서 간편하게 커스터마이징하는 방법을 설명합니다.

SITE 설정하기

주요 설정은 src/config.ts 파일에 있습니다. 이 파일 내의 SITE 객체에서 웹사이트의 주요 설정을 지정할 수 있습니다.

개발 중에는 SITE.website를 비워 두어도 괜찮습니다. 하지만 프로덕션 모드에서는 SITE.website 옵션에 배포된 URL을 지정해야 합니다. 이 값은 정규 URL, 소셜 카드 URL 등 SEO에 중요한 요소에 사용되기 때문입니다.

export const SITE = {
  website: "https://astro-paper.pages.dev/", // 배포된 도메인으로 변경하세요
  author: "Sat Naing",
  profile: "https://satnaing.dev/",
  desc: "A minimal, responsive and SEO-friendly Astro blog theme.",
  title: "AstroPaper",
  ogImage: "astropaper-og.jpg",
  lightAndDarkMode: true,
  postPerIndex: 4,
  postPerPage: 4,
  scheduledPostMargin: 15 * 60 * 1000, // 15분
  showArchives: true,
  showBackButton: true, // 글 상세 페이지에서 뒤로 가기 버튼 표시
  editPost: {
    enabled: true,
    text: "Suggest Changes",
    url: "https://github.com/satnaing/astro-paper/edit/main/",
  },
  dynamicOgImage: true, // 자동 동적 OG 이미지 생성 활성화
  dir: "ltr", // "rtl" | "auto"
  lang: "en", // html lang 코드. 비워두면 기본값은 "en"
  timezone: "Asia/Bangkok", // 기본 전역 시간대 (IANA 형식) https://en.wikipedia.org/wiki/List_of_tz_database_time_zones
} as const;src/config.ts

다음은 SITE 설정 옵션 목록입니다.

레이아웃 너비 변경

블로그의 레이아웃 너비는 두 가지 유틸리티로 관리됩니다:

• app-layout — 메인 화면, Header, Footer 등 공통 영역 (max-w-6xl)
• prose-layout — 게시글, About 등 글 읽기 영역 (max-w-4xl)

기본 너비를 변경하고 싶다면 global.css에서 max-w-app 또는 prose-layout 유틸리티를 수정할 수 있습니다. 예시:

@utility max-w-app {
  @apply max-w-6xl;
  @apply max-w-7xl;
}src/styles/global.css

더 많은 max-width 값은 Tailwind CSS 문서에서 확인할 수 있습니다.

로고 또는 제목 설정

AstroPaper v5 이전에는 src/config.ts 파일의 LOGO_IMAGE 객체에서 사이트 이름/로고를 업데이트할 수 있었습니다. 하지만 AstroPaper v5에서는 Astro의 기본 SVG 및 Image 컴포넌트를 사용하기 위해 이 옵션이 제거되었습니다.

3가지 옵션이 있습니다:

옵션 1: SITE 제목 텍스트

가장 간단한 옵션입니다. src/config.ts 파일에서 SITE.title만 수정하면 됩니다.

옵션 2: Astro의 SVG 컴포넌트

SVG 로고를 사용하고 싶다면 이 옵션을 활용하세요.

• 먼저 src/assets 디렉토리에 SVG 파일을 추가합니다. (예: src/assets/dummy-logo.svg)

• 그런 다음 Header.astro에서 해당 SVG를 import합니다.

  ---
  // ...
  import DummyLogo from "@/assets/dummy-logo.svg";
  ---src/components/Header.astro

• 마지막으로 {SITE.title}을 import한 로고로 교체합니다.

  <a
    href="/"
    class="absolute py-1 text-left text-2xl leading-7 font-semibold whitespace-nowrap sm:static"
  >
    <DummyLogo class="scale-75 dark:invert" />
    <!-- {SITE.title} -->
  </a>

이 방식의 장점은 필요에 따라 SVG 스타일을 커스터마이징할 수 있다는 것입니다. 위 예시에서 다크 모드에서 SVG 로고 색상을 반전시키는 방법을 확인할 수 있습니다.

옵션 3: Astro의 Image 컴포넌트

로고가 SVG가 아닌 이미지인 경우 Astro의 Image 컴포넌트를 사용할 수 있습니다.

• src/assets 디렉토리에 로고를 추가합니다. (예: src/assets/dummy-logo.png)

• Header.astro에서 Image와 로고를 import합니다.

  ---
  // ...
  import { Image } from "astro:assets";
  import dummyLogo from "@/assets/dummy-logo.png";
  ---src/components/Header.astro

• 그런 다음 {SITE.title}을 import한 로고로 교체합니다.

  <a
    href="/"
    class="absolute py-1 text-left text-2xl leading-7 font-semibold whitespace-nowrap sm:static"
  >
    <Image src="{dummyLogo}" alt="Dummy Blog" class="dark:invert" />
    <!-- {SITE.title} -->
  </a>

이 방식에서도 CSS 클래스를 사용하여 이미지 모양을 조정할 수 있습니다. 하지만 항상 원하는 대로 되지 않을 수 있습니다. 라이트/다크 모드에 따라 다른 로고 이미지를 표시해야 한다면, Header.astro 컴포넌트 내에서 라이트/다크 아이콘이 어떻게 처리되는지 확인해 보세요.

소셜 링크 설정

constants.ts의 SOCIALS 객체에서 소셜 링크를 설정할 수 있습니다.

export const SOCIALS = [
  {
    name: "GitHub",
    href: "https://github.com/satnaing/astro-paper",
    linkTitle: ` ${SITE.title} on GitHub`,
    icon: IconGitHub,
  },
  {
    name: "X",
    href: "https://x.com/username",
    linkTitle: `${SITE.title} on X`,
    icon: IconBrandX,
  },
  {
    name: "LinkedIn",
    href: "https://www.linkedin.com/in/username/",
    linkTitle: `${SITE.title} on LinkedIn`,
    icon: IconLinkedin,
  },
  {
    name: "Mail",
    href: "mailto:yourmail@gmail.com",
    linkTitle: `Send an email to ${SITE.title}`,
    icon: IconMail,
  },
] as const;src/constants.ts

공유 링크 설정

src/constants.ts의 SHARE_LINKS 객체에서 공유 링크를 설정할 수 있습니다.

폰트 설정

AstroPaper는 Astro의 실험적 폰트 API와 Google Sans Code를 기본 폰트로 사용합니다. 이를 통해 프리로딩과 캐싱을 포함한 자동 폰트 최적화와 함께 모든 플랫폼에서 일관된 타이포그래피를 제공합니다.

기본 폰트 사용

폰트는 astro.config.ts에서 자동으로 설정되고 Layout.astro에서 로드됩니다. 기본 Google Sans Code 폰트를 사용하기 위해 추가 설정은 필요 없습니다.

폰트 커스터마이징

다른 폰트를 사용하려면 세 곳을 수정해야 합니다:

1. astro.config.ts에서 폰트 설정 업데이트:

import { defineConfig, fontProviders } from "astro/config";

export default defineConfig({
  // ...
  experimental: {
    fonts: [
      {
        name: "Your Font Name",
        cssVariable: "--font-your-font",
        provider: fontProviders.google(),
        fallbacks: ["monospace"],
        weights: [300, 400, 500, 600, 700],
        styles: ["normal", "italic"],
      },
    ],
  },
});astro.config.ts

1. Layout.astro에서 Font 컴포넌트 업데이트:

---
import { Font } from "astro:assets";
// ...
---

<head>
  <!-- ... -->
  <Font
    cssVariable="--font-your-font"
    preload={[{ subset: "latin", weight: 400, style: "normal" }]}
  />
  <!-- ... -->
</head>src/layouts/Layout.astro

1. global.css에서 CSS 변수 매핑 업데이트:

@theme inline {
  --font-app: var(--font-your-font); 
  --color-background: var(--background);
  --color-foreground: var(--foreground);
  --color-accent: var(--accent);
  --color-muted: var(--muted);
  --color-border: var(--border);
}src/styles/global.css

--font-app 변수는 테마 전체에서 font-app Tailwind 유틸리티 클래스를 통해 사용되므로, 이 단일 변수를 업데이트하면 커스텀 폰트가 모든 곳에 적용됩니다.

참고: 폰트 이름이 Google Fonts에 표시된 것과 정확히 일치하는지 확인하세요. 다른 폰트 제공자나 로컬 폰트의 경우 Astro 실험적 폰트 API 문서를 참고하세요.

마치며

이상으로 이 테마를 커스터마이징하는 방법을 간략히 소개했습니다. 코딩에 익숙하다면 더 많은 커스터마이징이 가능합니다. 스타일 커스터마이징에 대해서는 이 글을 읽어보세요. 읽어주셔서 감사합니다.