VitePress 가이드: 설치부터 배포까지

VitePress 소개

VitePress는 Vite와 Vue 3를 기반으로 하는 정적 사이트 생성기(SSG)입니다. Markdown 파일을 정적 HTML로 변환하여 웹사이트를 빠르게 구축할 수 있게 해줍니다.

VitePress는 문서 사이트에 널리 사용됩니다. 예를 들어, Vue.js와 Vite의 공식 문서는 모두 VitePress로 구축되었습니다.

문서 외에도 많은 사람들이 개인 블로그를 만드는 데 VitePress를 사용합니다. Markdown 파일을 웹 페이지로 변환하기 때문에 기술적인 세부 사항에 너무 많이 신경 쓰지 않고 콘텐츠 제작에 집중할 수 있습니다.

VuePress와 어떻게 다른가요?

이름에 한 글자 차이만 있지만, VuePress와 VitePress는 상당히 다릅니다.

VuePress는 Vue 팀에서 출시한 초기 정적 사이트 생성기로, 특히 Vue 2.x를 위해 설계되었습니다. 반면에 VitePress는 Vue 3.x에 맞춰 제작되었습니다.

Vue 3가 주류가 됨에 따라, 더 활발한 생태계와 커뮤니티 지원을 활용하기 위해 최신 버전의 VitePress를 사용하는 것이 좋습니다.

빠른 시작

새로운 VitePress 프로젝트를 만들려면 다음 명령을 순서대로 실행하세요.

# 새 프로젝트 폴더를 만들고 해당 폴더로 이동합니다.
mkdir vitepress-blog && cd vitepress-blog

# VitePress를 추가합니다.
npm add -D vitepress@next

# 초기화 마법사를 실행합니다.
npx vitepress init

위 명령을 실행한 후 VitePress는 콘텐츠 위치, 사이트 제목, 테마 등의 일련의 질문을 통해 기본 구성을 안내합니다. 초보자의 경우 모든 질문에 대해 기본 옵션을 받아들이려면 Enter 키를 누르기만 하면 됩니다.

┌  Welcome to VitePress!
│
◇  Where should VitePress initialize the config?
│  ./
│
◇  Where should VitePress look for your markdown files?
│  ./
│
◇  Site title:
│  My Awesome Project
│
◇  Site description:
│  A VitePress Site
│
◇  Theme:
│  Default Theme
│
◇  Use TypeScript for config and theme files?
│  Yes
│
◇  Add VitePress npm scripts to package.json?
│  Yes
│
◇  Add a prefix for VitePress npm scripts?
│  Yes
│
◇  Prefix for VitePress npm scripts:
│  docs
│
└  Done! Now run npm run docs:dev and start writing.

마법사가 완료되면 프로젝트가 초기화됩니다. 프로젝트 디렉터리 구조는 다음과 같아야 합니다.

.
├── .vitepress
│   └── config.mts  # VitePress 구성 파일
├── api-examples.md
├── markdown-examples.md
├── index.md      # 사이트 홈페이지
└── package.json

개발 서버를 시작하려면 다음 명령을 실행하세요.

npm run docs:dev

브라우저에서 http://localhost:5173으로 이동하면 VitePress 사이트를 볼 수 있습니다.

첫 번째 게시물 추가하기

루트 디렉터리에 새 Markdown 파일을 만듭니다. 예를 들어 my-first-post.md입니다. 내용을 작성하세요.

---
title: My First Post
date: 2025-09-21
---

# Hello, VitePress!

This is the first post on my personal blog.

@Built with VitePress

게시물을 작성한 후에는 사이트에 나타나지 않는다는 것을 알게 될 것입니다. 이는 VitePress가 파일 변경 사항을 자동으로 감지하여 탐색을 업데이트하지 않기 때문입니다. 게시물을 VitePress에 추가하려면 구성 파일을 수동으로 업데이트해야 합니다.

.vitepress/config.mts 파일을 열고 sidebar 구성 옵션을 찾아 새 게시물을 추가하세요.

import { defineConfig } from 'vitepress';

export default defineConfig({
  // ... 기타 구성
  themeConfig: {
    // ... 기타 테마 구성
    sidebar: [
      {
        text: 'My Posts', // 이것은 그룹 제목입니다.
        items: [{ text: 'My First Post', link: '/my-first-post' }],
      },
    ],
  },
});

파일을 저장한 후 브라우저 페이지를 새로고침하면 사이드바에서 게시물 링크를 볼 수 있습니다. 클릭하여 새 게시물을 봅니다.

사이드바를 자동으로 업데이트하는 방법이 있나요?

새 게시물을 만들 때마다 사이드바를 수동으로 업데이트하는 것은 번거로울 수 있습니다. 그러나 공식 팀에서 제공하는 내장 자동화 솔루션은 현재 없습니다.

이 문제를 해결하기 위해 VitePress Sidebar와 같은 커뮤니티 플러그인을 사용할 수 있습니다.

홈페이지를 수정하는 방법?

기본 홈페이지는 index.md에 있습니다. 그러나 내용은 다소 이상해 보입니다. 구성 세트일 뿐이며 Markdown이나 HTML이 없습니다.

구성 블록이 전체 웹페이지로 어떻게 변환될까요?

홈페이지는 실제로 VitePress 테마에 의해 생성됩니다. 기본 구성을 사용하여 만든 사이트에는 테마도 포함됩니다.

index.md 파일의 Frontmatter(파일 상단의 구성 영역)에 layout: home을 지정하면 VitePress는 테마에 내장된 홈페이지 템플릿을 사용하여 페이지를 렌더링합니다. 템플릿에 필요한 제목, 태그라인, 버튼 및 기타 콘텐츠는 모두 index.md에서 구성하는 hero, actions 및 기타 필드에서 가져옵니다.

홈페이지의 스타일을 변경하는 가장 직접적인 방법은 사이트의 테마를 변경하거나 사용자 정의하는 것입니다.

홈페이지를 완전히 다시 작성하거나 커뮤니티에서 제공하는 테마를 사용할 수 있습니다. Awesome VitePress와 같은 "awesome lists"에서 많은 커뮤니티 테마를 찾을 수 있습니다.

블로그를 더욱 풍부하게 만드는 방법?

기본 프레임워크를 설정한 후에는 다음과 같은 방법으로 블로그를 더욱 풍부하고 개인적으로 만들 수 있습니다.

Vue.js 학습: Vue를 학습하여 Markdown 파일 내에 사용자 정의 구성 요소를 만들어 차트, 캐러셀 또는 더 복잡한 애플리케이션과 같이 웹 콘텐츠를 풍부하게 만들 수 있습니다.
VitePress 문서 살펴보기: 공식 문서를 자세히 읽고 탐색 모음, 바닥글, 국제화(i18n)를 구성하는 방법과 내장 Markdown 확장을 최대한 활용하는 방법을 알아보세요.
커뮤니티 테마 및 플러그인 탐색: Awesome VitePress와 같은 커뮤니티 개발자가 기여한 테마 및 플러그인을 사용하여 고급 기능과 스타일을 블로그에 빠르게 추가할 수 있습니다.

VitePress 웹사이트 배포하기

이제 블로그가 설정되었으므로 온라인으로 배포하여 친구들과 전 세계에 공유할 때입니다.

배포에는 Leapcell 사용을 권장합니다.

Leapcell은 매우 간단하고 사용하기 쉬운 인터페이스를 제공하는 웹 앱 호스팅 플랫폼으로, 몇 가지 간단한 단계만으로 VitePress 사이트를 온라인으로 배포할 수 있습니다.

또한 Leapcell에는 트래픽 분석 기능이 내장되어 있어 사용자 방문 빈도 및 사용자 소스와 같은 웹사이트 액세스 정보를 쉽게 볼 수 있어 독자를 더 잘 이해하는 데 도움이 됩니다.

특정 배포 단계

프로젝트의 루트 디렉터리에서 Caddyfile이라는 파일을 만들고 다음 내용을 포함합니다.

:8080 {
  root * ./.vitepress/dist
  file_server
}

프로젝트를 GitHub에 커밋합니다. 단계는 GitHub 공식 문서를 참조하세요. Leapcell은 나중에 GitHub 저장소에서 코드를 가져옵니다.
Leapcell 페이지에서 "Create Service"를 클릭합니다.

런타임으로 "nodejs20"을 선택하고 다음 배포 필드를 채웁니다.

Build Command:

apt update && apt install -y debian-keyring debian-archive-keyring apt-transport-https curl
curl -1sLf 'https://dl.cloudsmith.io/public/caddy/stable/gpg.key' | gpg --dearmor -o /usr/share/keyrings/caddy-stable-archive-keyring.gpg
curl -1sLf 'https://dl.cloudsmith.io/public/caddy/stable/debian.deb.txt' | tee /etc/apt/sources.list.d/caddy-stable.list
chmod o+r /usr/share/keyrings/caddy-stable-archive-keyring.gpg
chmod o+r /etc/apt/sources.list.d/caddy-stable.list
apt update && apt install -y caddy

npm install && npm run docs:build

Start Command: