Astro Starlight + Vercel: 코드 없이 만드는 프로젝트 문서 사이트 실전 가이드

1. 왜 문서 사이트가 필요했나

오픈소스 프로젝트를 운영하다 보면 README.md 하나로는 한계가 옵니다. 설치 가이드, 설정 옵션, 위젯 레퍼런스, 트러블슈팅... 내용이 늘어날수록 README는 스크롤 지옥이 되고, 원하는 정보를 찾기가 점점 어려워집니다.

제가 운영하는 Claude Code 플러그인 프로젝트가 정확히 이 상황이었습니다:

• 25개의 위젯 — 각각 설정 옵션과 사용법이 다름
• 8가지 테마 — 미리보기와 설정 방법 안내 필요
• 4개의 커맨드 — 각각 옵션과 사용 예시 설명 필요
• 다국어 지원 — 한국어/영어 문서 모두 필요

README에 이걸 전부 넣으니 600줄이 넘어갔습니다. 위젯 목록에서 특정 위젯의 설정법을 찾으려면 Ctrl+F를 여러 번 해야 하고, 테마와 프리셋 같은 관련 설정이 문서 여기저기에 흩어져 있어 전체를 파악하기 어려운 상태였습니다.

목표는 명확했습니다:

1. 검색 가능한 구조화된 문서 사이트
2. 한국어/영어 다국어 지원
3. 최소한의 유지보수 비용
4. 무료 호스팅 + 커스텀 도메인

2. 프레임워크 비교 — 왜 Astro Starlight를 골랐나

문서 사이트를 만들 수 있는 정적 사이트 생성기(SSG)는 여러 개가 있습니다. 후보를 4가지로 좁히고 비교했습니다.

후보 4인방

각 프레임워크의 장단점

VitePress — "가볍고 빠른 Vue 기반"

VitePress는 Vue.js 생태계에서 나온 정적 사이트 생성기입니다. Vite 기반이라 개발 서버 시작이 빠르고, 마크다운 내에서 Vue 컴포넌트를 바로 사용할 수 있습니다.

✅ 장점: 가볍고 빠름, 설정 간단, Vue 생태계 활용
❌ 단점: 블로그 기능 없음, i18n이 수동적, Vue 종속

저는 Vue를 주로 사용하지 않고, 블로그 연동 가능성도 고려했기에 제외했습니다.

Docusaurus — "기능 최강, 하지만 무거움"

Meta(Facebook)에서 만든 Docusaurus는 기능이 가장 풍부합니다. 블로그, 버전 관리, 플러그인 시스템까지 내장되어 있습니다.

✅ 장점: 블로그 내장, 문서 버저닝, 풍부한 플러그인
❌ 단점: React 의존, node_modules가 거대, 빌드 느림

문서 사이트 하나 만드는 데 React 전체 번들이 딸려오는 건 과도하다고 판단했습니다.

Hugo — "가장 빠르지만 러닝 커브"

Go 기반의 Hugo는 빌드 속도가 압도적입니다. 수천 페이지도 수 초 안에 빌드합니다.

✅ 장점: 가장 빠른 빌드, 바이너리라 의존성 없음, 테마 다양
❌ 단점: Go 템플릿 문법 학습 필요, 문서 전용 기능 부족

Go 템플릿 문법({{ .Params.title }})이 직관적이지 않고, 문서 사이트에 특화된 기능(자동 사이드바, 검색)을 직접 구성해야 하는 점이 부담이었습니다.

Astro Starlight — "문서 전용, 마크다운 네이티브"

Astro 위에 구축된 Starlight는 문서 사이트만을 위해 설계되었습니다.

✅ 장점: 문서 전용 설계, i18n 내장, Pagefind 검색 내장, 제로 JS 기본
❌ 단점: 블로그는 플러그인 필요, Astro 생태계 의존

최종 선택 이유

Starlight를 선택한 결정적 이유 3가지입니다:

1. 마크다운만으로 완성되는 구조

.md 파일 하나 만들면 사이드바에 자동 등록되고, frontmatter로 순서와 메타데이터를 제어합니다. React나 Vue 컴포넌트를 작성할 필요가 없습니다.

---
title: 설치
description: 플러그인 설치 방법
sidebar:
  order: 1
---

## 요구 사항

- **Claude Code** v1.0.80 이상
- **Node.js** 18 이상

이게 전부입니다. 이 파일 하나로 사이드바 메뉴, 페이지 제목, SEO 메타 태그, 목차(TOC)가 모두 자동 생성됩니다.

2. i18n이 설정 수준에서 해결됨

설정 파일에서 로케일을 선언하면 언어 전환 UI가 자동으로 나타납니다:

// astro.config.mjs
defaultLocale: 'root',
locales: {
  root: { label: 'English', lang: 'en' },
  ko: { label: '한국어', lang: 'ko' },
},

사이드바 레이블도 translations 속성 하나로 끝입니다:

{
  label: 'Getting Started',
  translations: { ko: '시작하기' },
  items: ['getting-started/installation', 'getting-started/quick-start'],
},

3. 의존성이 극도로 적음

{
  "dependencies": {
    "@astrojs/starlight": "^0.34",
    "astro": "^5.5",
    "sharp": "^0.33"
  }
}

의존성이 딱 3개입니다. sharp는 이미지 최적화용이고, 실질적으로 Astro + Starlight 두 패키지만 있으면 됩니다. Docusaurus의 node_modules가 수백 MB인 것과 비교하면 극적인 차이입니다.

3. 실제 프로젝트 구조 — 코드가 없는 사이트

완성된 사이트의 구조를 보면 놀라울 정도로 단순합니다.

전체 디렉토리

website/
├── astro.config.mjs          ← 설정 (103줄)
├── package.json               ← 의존성 3개
├── tsconfig.json              ← 1줄
├── public/
│   └── favicon.svg
├── src/
│   ├── assets/logo.svg
│   ├── content.config.ts      ← 스키마 (7줄)
│   ├── styles/custom.css      ← 테마 (63줄)
│   └── content/docs/
│       ├── index.mdx          ← 랜딩 페이지
│       ├── getting-started/   ← 설치, 빠른 시작
│       ├── guides/            ← 가이드 5개
│       ├── reference/         ← 레퍼런스 3개
│       ├── troubleshooting.md
│       └── ko/                ← 한국어 번역 (동일 구조)

파일 유형별 비율

코드라고 부를 수 있는 파일이 사실상 없습니다. content.config.ts는 7줄짜리 스키마 선언이고, custom.css는 63줄의 색상 변수 오버라이드입니다. 나머지는 전부 마크다운입니다.

핵심 설정 파일 3개

사이트 전체를 제어하는 파일은 딱 3개입니다.

1. astro.config.mjs — 사이트의 두뇌 (103줄)

import { defineConfig } from 'astro/config';
import starlight from '@astrojs/starlight';

export default defineConfig({
  site: 'https://claude-dashboard.uppinote.dev',
  integrations: [
    starlight({
      title: { ko: 'claude-dashboard', en: 'claude-dashboard' },
      description: 'Comprehensive status line plugin for Claude Code',
      social: [
        { icon: 'github', label: 'GitHub',
          href: 'https://github.com/uppinote20/claude-dashboard' },
      ],
      // i18n 설정
      defaultLocale: 'root',
      locales: {
        root: { label: 'English', lang: 'en' },
        ko: { label: '한국어', lang: 'ko' },
      },
      // 사이드바 구조
      sidebar: [
        { label: 'Getting Started', translations: { ko: '시작하기' },
          items: ['getting-started/installation', 'getting-started/quick-start'] },
        { label: 'Guides', translations: { ko: '가이드' },
          items: ['guides/display-modes', 'guides/widgets', 'guides/themes',
                  'guides/configuration', 'guides/presets'] },
        { label: 'Reference', translations: { ko: '레퍼런스' },
          items: ['reference/commands', 'reference/widget-reference',
                  'reference/config-schema'] },
        'troubleshooting',
        // 외부 블로그 링크
        { label: 'Blog Posts', translations: { ko: '관련 글' },
          items: [
            { label: 'Plugin Guide',
              link: 'https://blog.uppinote.dev/claude-dashboard-plugin-guide/',
              attrs: { target: '_blank' } },
          ] },
      ],
      customCss: ['./src/styles/custom.css'],
    }),
  ],
});

이 하나의 파일에서 사이트 URL, i18n 로케일, 사이드바 전체 구조, GitHub 소셜 링크, 커스텀 CSS, 외부 블로그 연결까지 모두 선언합니다.

2. content.config.ts — 콘텐츠 스키마 (7줄)

import { defineCollection } from 'astro:content';
import { docsLoader } from '@astrojs/starlight/loaders';
import { docsSchema } from '@astrojs/starlight/schema';

export const collections = {
  docs: defineCollection({ loader: docsLoader(), schema: docsSchema() }),
};

Starlight의 기본 스키마를 그대로 사용합니다. 블로그 플러그인을 쓴다면 여기서 스키마를 확장하지만, 문서만 필요하면 이 7줄이면 충분합니다.

3. custom.css — 테마 커스터마이징 (63줄)

:root {
  /* 브랜드 색상 — 터미널 미학에서 영감 */
  --sl-color-accent-low: #1a1b26;
  --sl-color-accent: #7aa2f7;
  --sl-color-accent-high: #c0caf5;

  /* 폰트 — 한국어 지원 포함 */
  --sl-font: 'Pretendard Variable', 'Pretendard', -apple-system,
    BlinkMacSystemFont, system-ui, 'Apple SD Gothic Neo', sans-serif;
  --sl-font-mono: 'JetBrains Mono', 'Fira Code', monospace;
}

/* 라이트 모드 오버라이드 */
:root[data-theme='light'] {
  --sl-color-accent-low: #dbeafe;
  --sl-color-accent: #2563eb;
  --sl-color-accent-high: #1e3a5f;
}

Starlight는 CSS 변수 기반으로 테마를 제공합니다. 변수를 오버라이드하는 것만으로 다크/라이트 모드 모두 커스터마이징됩니다. 컴포넌트를 건드릴 필요가 없습니다.

랜딩 페이지 — MDX 35줄

---
title: claude-dashboard
description: Claude Code를 위한 종합 상태줄 플러그인
template: splash
hero:
  tagline: 컨텍스트 사용량, API 속도 제한, 비용 추적, 그리고 25개 이상의 모듈형 위젯
  actions:
    - text: 시작하기
      link: /getting-started/installation/
      icon: right-arrow
      variant: primary
    - text: GitHub
      link: https://github.com/uppinote20/claude-dashboard
      icon: external
      variant: minimal
---

import { Card, CardGrid } from '@astrojs/starlight/components';

<CardGrid stagger>
  <Card title="25개의 위젯" icon="puzzle">
    모델 정보, 컨텍스트 사용량, 비용 추적 등 25개 위젯으로
    세션을 완벽하게 모니터링하세요.
  </Card>
  <Card title="멀티 CLI 지원" icon="laptop">
    Claude Code, Codex CLI, Gemini CLI, z.ai까지 한눈에.
  </Card>
</CardGrid>

template: splash를 지정하면 사이드바 없는 랜딩 페이지가 됩니다. Starlight 내장 컴포넌트(Card, CardGrid)를 import해서 기능 카드를 배치합니다. 이것이 사이트에서 유일하게 "코드 같은" 부분입니다.

4. i18n의 현실 — 파일 복제 방식의 장단점

Starlight의 i18n은 파일 복제 방식입니다. 같은 구조의 마크다운 파일을 언어별 디렉토리에 각각 만듭니다.

디렉토리 구조

src/content/docs/
├── index.mdx                    ← 영어 (root)
├── getting-started/
│   ├── installation.md
│   └── quick-start.md
├── guides/
│   ├── display-modes.md
│   ├── widgets.md
│   ├── themes.md
│   ├── configuration.md
│   └── presets.md
├── reference/
│   ├── commands.md
│   ├── widget-reference.md
│   └── config-schema.md
├── troubleshooting.md
└── ko/                          ← 한국어
    ├── index.mdx
    ├── getting-started/
    │   ├── installation.md
    │   └── quick-start.md
    ├── guides/
    │   ├── display-modes.md
    │   ├── widgets.md
    │   ├── themes.md
    │   ├── configuration.md
    │   └── presets.md
    ├── reference/
    │   ├── commands.md
    │   ├── widget-reference.md
    │   └── config-schema.md
    └── troubleshooting.md

영어 12파일 + 한국어 12파일 = 총 24파일. 완전히 동일한 구조가 두 벌입니다.

장점

✅ 번역 품질 제어 — 기계 번역이 아닌 수동 번역, 문맥에 맞는 자연스러운 표현 가능
✅ 언어별 독립 — 한국어에만 있는 페이지, 영어에만 있는 페이지 가능
✅ 단순한 구조 — 특별한 도구나 빌드 파이프라인 불필요
✅ 검색 최적화 — 각 언어별로 독립적인 검색 인덱스 생성
✅ 리뷰 용이 — 번역 파일을 직접 열어서 검토 가능

단점

❌ 파일 수 × 언어 수 — 3개 국어면 파일이 3배
❌ 동기화 어려움 — 원본 변경 시 번역 파일도 수동 업데이트 필요
❌ 누락 위험 — 새 페이지 추가 시 번역 파일 생성을 잊기 쉬움
❌ diff가 복잡 — 같은 내용 변경이 여러 파일에 걸쳐 발생

다른 프레임워크와의 비교

사실 대부분의 문서 프레임워크가 파일 복제 방식을 사용합니다. 문서 콘텐츠의 i18n은 UI 문자열과 달리 JSON 키-값으로 관리하기 어렵기 때문입니다. 각 페이지가 수백 줄의 마크다운인데, 이걸 번역 키로 쪼개면 오히려 관리가 어려워집니다.

실전 팁: 동기화 전략

파일 복제 방식에서 동기화를 놓치지 않기 위한 방법입니다:

# 영어 문서와 한국어 문서의 파일 목록 비교
diff <(cd src/content/docs && find . -name "*.md" -o -name "*.mdx" | \
       grep -v "^./ko/" | sort) \
     <(cd src/content/docs/ko && find . -name "*.md" -o -name "*.mdx" | sort)

이 명령으로 영어에는 있지만 한국어에 없는 파일(또는 그 반대)을 빠르게 찾을 수 있습니다.

5. 레포 구조 — 모노레포인가, 아닌가

이 프로젝트는 하나의 Git 레포에 두 개의 독립적인 프로젝트가 들어 있습니다:

claude-dashboard/
├── package.json          ← 플러그인 (Node.js + esbuild)
├── scripts/              ← 플러그인 소스 코드
├── dist/                 ← 플러그인 빌드 산출물
└── website/
    ├── package.json      ← 문서 사이트 (Astro + Starlight)
    └── src/              ← 문서 사이트 소스

각각 별도의 package.json, 별도의 의존성, 별도의 빌드 명령을 갖고 있습니다. 그런데 이걸 "모노레포"라고 부를 수 있을까요?

모노레포 vs Co-located Projects

엄밀히 말하면 "co-located projects" (동거 프로젝트)에 가깝습니다. 모노레포의 핵심 가치인 "패키지 간 코드 공유"가 없기 때문입니다. 플러그인 코드와 문서 사이트가 코드를 공유하지 않고, 각각 완전히 독립적으로 빌드됩니다.

이 구조의 장점

✅ 하나의 레포에서 코드와 문서를 함께 관리
✅ 코드 변경과 문서 업데이트를 같은 PR에 포함 가능
✅ 별도 레포 관리 오버헤드 없음
✅ Vercel이 서브디렉토리 배포를 완벽 지원

이 구조의 단점

❌ 레포 전체 클론 시 문서 사이트 의존성도 포함
❌ 기여자가 혼란할 수 있음 (어디를 수정해야 하는지)
❌ CI/CD에서 변경 감지 로직 필요

6. Vercel 배포 — 서브디렉토리 프로젝트 배포

Vercel은 서브디렉토리 프로젝트 배포를 네이티브로 지원합니다. 핵심은 Root Directory 설정입니다.

배포 단계

Step 1: 프로젝트 Import

Vercel 대시보드에서 GitHub 레포를 import합니다. 이 과정에서 가장 중요한 설정은 하나입니다:

Root Directory를 website로 설정하면, Vercel은 website/ 폴더를 프로젝트 루트로 인식합니다. website/package.json의 의존성을 설치하고, website/ 안에서 빌드를 실행합니다.

Step 2: 커스텀 도메인 연결

Vercel 프로젝트 Settings > Domains에서 원하는 도메인을 추가합니다. DNS 설정은 간단합니다:

Cloudflare 사용 시 주의사항: Proxy 상태를 "DNS only" (회색 구름)로 설정해야 합니다. 주황색 구름(Proxied)이면 Vercel의 SSL 인증서와 충돌합니다.

Step 3: Ignored Build Step

서브디렉토리 프로젝트에서 중요한 설정입니다. 플러그인 코드만 변경했는데 문서 사이트가 매번 다시 빌드되면 낭비입니다.

Vercel Settings > Git > Ignored Build Step에서 Automatic을 선택합니다. Root Directory가 website로 설정되어 있으면, Vercel이 자동으로 해당 폴더의 변경을 감지하여 빌드 여부를 결정합니다. 머지 커밋에서도 올바르게 동작합니다.

참고: 이전에는 git diff HEAD^ HEAD --quiet -- website/ 커스텀 커맨드를 사용했지만, 머지 커밋에서 부모 참조가 기대와 다르게 동작하여 빌드가 스킵되는 문제가 있었습니다. Vercel의 Automatic 모드가 더 안정적입니다.

Vercel vs GitHub Pages vs 셀프 호스팅

Vercel을 선택한 이유는 서브디렉토리 배포 + 프리뷰 배포 + 제로 설정 조합입니다. GitHub Pages도 가능하지만, Actions workflow를 직접 작성해야 하고 프리뷰 배포가 안 됩니다.

7. 제공되는 기능 — Starlight가 자동으로 해주는 것들

설정 파일과 마크다운만 작성했는데, 완성된 사이트에는 다음 기능이 자동으로 포함됩니다:

✅ 반응형 사이드바 네비게이션
✅ 클라이언트 사이드 전문 검색 (Pagefind — Cmd+K)
✅ 다크/라이트 모드 토글
✅ 언어 전환 UI (한국어 ↔ English)
✅ 페이지별 목차 (Table of Contents)
✅ "Edit this page" 링크 (GitHub 연동)
✅ 이전/다음 페이지 네비게이션
✅ SEO 메타 태그 자동 생성
✅ 사이트맵 자동 생성
✅ 접근성 (a11y) 최적화
✅ 모바일 반응형 레이아웃

이 모든 것이 코드 한 줄 작성하지 않고 제공됩니다. 특히 Pagefind 검색은 빌드 시점에 정적 검색 인덱스를 생성하므로, 별도의 검색 서비스(Algolia 등)를 연동할 필요가 없습니다.

8. 주의할 점과 한계

Starlight가 잘 맞지 않는 경우

❌ 블로그 중심 사이트 — 블로그가 주인 사이트라면 Ghost, WordPress, 또는 Docusaurus
❌ 커스텀 레이아웃이 많은 경우 — Starlight의 레이아웃은 문서에 최적화
❌ 동적 기능 필요 — 로그인, 댓글, 실시간 데이터 등
❌ 이미 React/Vue 프로젝트가 있는 경우 — 기존 컴포넌트 재사용이 어려움

블로그와의 분리

저는 블로그를 별도 플랫폼(Ghost)에서 운영하고, 문서 사이트에서는 사이드바에 외부 링크만 넣었습니다:

// astro.config.mjs 사이드바 설정
{
  label: 'Blog Posts',
  translations: { ko: '관련 글' },
  items: [
    { label: 'Plugin Guide',
      link: 'https://blog.uppinote.dev/claude-dashboard-plugin-guide/',
      attrs: { target: '_blank' } }, // ← 새 탭에서 열기
  ],
},

Starlight에 starlight-blog 플러그인을 추가하면 사이트 내에서 블로그를 운영할 수도 있지만, 이미 블로그 플랫폼이 있다면 굳이 중복할 필요가 없습니다.

9. 정리 — 언제 Astro Starlight를 선택할까

Starlight가 최적인 경우

최종 수치

설정 파일:    3개 (astro.config.mjs, content.config.ts, custom.css)
의존성:      3개 (astro, @astrojs/starlight, sharp)
마크다운:    24개 (한국어 12 + 영어 12)
총 코드 줄:  ~173줄 (설정 + CSS)
빌드 시간:   수 초
호스팅 비용:  $0 (Vercel 무료 tier)

코드 한 줄 없이 마크다운과 설정 파일만으로 검색 가능한 다국어 문서 사이트를 만들었습니다. 프레임워크 선택에 시간을 쓰기보다, 콘텐츠에 집중하는 게 더 나은 투자입니다.

10. FAQ

Q: Starlight와 VitePress 중 어떤 것을 추천하시나요?
A: Vue 프로젝트라면 VitePress, 그 외에는 Starlight를 추천합니다. Starlight는 프레임워크 종속성이 없고, 검색(Pagefind)이 내장되어 있어 초기 설정이 더 간단합니다.

Q: 블로그도 Starlight에서 운영할 수 있나요?
A: starlight-blog 커뮤니티 플러그인을 추가하면 가능합니다. 다만 이미 Ghost, WordPress 등 블로그 플랫폼이 있다면 외부 링크로 연결하는 방식이 더 실용적입니다.

Q: Vercel 무료 tier의 한계가 있나요?
A: 월 100GB 대역폭, 빌드당 45분 제한이 있지만 문서 사이트에서는 거의 도달하지 않습니다. 상용 프로젝트도 무료 tier로 충분합니다.

Q: i18n에서 번역 동기화는 어떻게 관리하나요?
A: 현재는 수동입니다. 원본(영어) 변경 시 한국어 파일도 함께 업데이트합니다. 파일 구조가 동일하므로 diff 명령으로 누락을 확인할 수 있습니다. 자동화가 필요하면 CI에서 파일 목록 비교 스크립트를 추가하는 방법도 있습니다.

Q: GitHub Pages 대신 Vercel을 쓴 이유가 있나요?
A: 서브디렉토리 배포(website/)를 네이티브로 지원하고, PR마다 프리뷰 배포가 자동 생성됩니다. GitHub Pages는 GitHub Actions workflow를 직접 작성해야 합니다.

11. 참고 자료

• Astro Starlight 공식 문서
• VitePress 공식 문서
• Docusaurus 공식 문서
• Hugo 공식 문서
• Vercel 공식 문서 — 모노레포 설정