Astro-Theme-Aither 시작하기

이 가이드는 처음 설정부터 다국어 블로그 배포까지 전체 흐름을 안내합니다. 처음부터 끝까지 읽어도 되고, 필요한 섹션만 바로 찾아가도 됩니다.

준비 사항

• Node.js 22 LTS 이상
• pnpm 10 이상
• GitHub 계정
• 배포용 Cloudflare 계정

설치

git clone https://github.com/YOUR_USERNAME/YOUR_REPO.git
cd YOUR_REPO
corepack enable
pnpm install
pnpm validate
pnpm dev

브라우저에서 http://localhost:4321을 열면 됩니다.

프로젝트 구조

src/
├── components/        # Astro 및 React 컴포넌트
├── config/site.ts     # 사이트 이름, 내비게이션, 푸터, 소셜 링크
├── content/posts/     # 로케일별 글 콘텐츠
├── i18n/              # UI 번역
├── layouts/           # 레이아웃
├── lib/               # 유틸리티
├── pages/             # 페이지와 라우트
└── styles/global.css  # Tailwind v4 테마 토큰

설정

Site Config

src/config/site.ts가 사이트 설정의 단일 진실 공급원입니다:

1
export const siteConfig = {
2
  name: '블로그 이름',
3
  title: '태그라인',
4
  description: 'SEO용 사이트 설명',
5
  author: {
6
    name: '작성자 이름',
7
    avatar: '',
8
  },
9
};

환경 변수

cp .env.example .env

값을 비워두면 해당 서비스는 자동으로 비활성화됩니다.

사이트 URL

운영 URL은 astro.config.mjs에서 설정합니다:

1
import { defineConfig } from 'astro/config';
2
import aither from '@aither/astro';
3

4
export default defineConfig({
5
  site: 'https://your-domain.pages.dev',
6
  integrations: [aither()],
7
});

글 작성하기

src/content/posts/en/ 아래에 새 .mdx 파일을 만드세요:

1
---
2
title: 나의 첫 글
3
date: "2026-03-14T16:00:00+08:00"
4
category: General
5
description: SEO와 소셜 미리보기를 위한 짧은 설명.
6
tags: [Topic, Another]
7
pinned: false
8
---
9

10
여기서부터 본문이 시작됩니다.

Frontmatter 참고

MDX 컴포넌트

콘텐츠 안에서 컴포넌트를 바로 사용할 수 있습니다:

1
import MyChart from '@/components/MyChart'
2

3
<MyChart data={[10, 20, 30]} />

국제화

이 테마는 기본적으로 11개 언어를 지원합니다. 번역 글을 추가하려면 대상 로케일 디렉터리에 같은 파일명을 만들면 됩니다:

src/content/posts/en/my-post.mdx
src/content/posts/ko/my-post.mdx
src/content/posts/zh-hans/my-post.mdx

UI 문자열은 src/i18n/messages/에 있습니다.

커스텀 콘텐츠 섹션

번역, 노트, 튜토리얼 같은 별도 컬렉션은 src/content.config.ts와 src/config/site.ts에서 등록할 수 있습니다. 그러면 목록 페이지와 상세 페이지가 자동 생성됩니다.

테마 설정

테마는 두 층으로 나뉩니다:

• 색상 모드: light, dark, system
• 스타일 모드: default 또는 evolution 같은 내장 스타일

1
ui: {
2
  defaultMode: 'system',
3
  defaultStyle: 'default',
4
  showMoreThemesMenu: true,
5
},

색상 토큰은 src/styles/global.css에 있고, 기본 본문은 시스템 sans-serif, 코드 영역은 monospace를 사용합니다.

SEO 및 AI

각 페이지는 다음과 같은 출력물을 기본 제공합니다:

• /sitemap-index.xml
• /rss.xml
• /robots.txt
• /llms.txt
• /llms-full.txt
• /posts/slug.md
• JSON-LD 및 Open Graph

배포

Cloudflare Pages

권장 방식은 먼저 Pages 프로젝트를 만드는 것입니다. 워크플로는 기본적으로 저장소 이름을 사용하고, 필요하면 CLOUDFLARE_PAGES_PROJECT_NAME으로 덮어쓸 수 있습니다.

GitHub Secrets에 아래 값을 추가하세요:

• CLOUDFLARE_API_TOKEN
• CLOUDFLARE_ACCOUNT_ID

그다음 pnpm validate를 실행하고 main에 푸시하세요.

자주 쓰는 명령어

버전 체계

공개 릴리스 태그는 v2026.04.08 같은 CalVer 스타일 이름을 사용합니다.