안녕하세요, 자바파커입니다.
"Vue 로 기술문서 사이트를 만들고 싶은데, 지금 2026년에도 VuePress 를 써도 되나요?" 라는 질문을 자주 받습니다.
결론부터 말씀드리면 — VuePress v2 는 여전히 정상적으로 유지되고 동작하지만, 2026년 현재 Vue 팀이 공식적으로 추천하는 SSG 는 VitePress 입니다. 기존 VuePress 프로젝트를 유지보수 중이라면 그대로 써도 무방하고, 신규로 시작한다면 VitePress 쪽을 먼저 검토하시길 권합니다. 그래도 VuePress 기본기는 Vue 기반 SSG 를 이해하는 데 가장 빠른 지름길이라 오늘은 VuePress 를 기준으로 정리해 보겠습니다.
VuePress 가 뭔가요?
간단히 말해, 마크다운 파일을 예쁜 정적 웹사이트로 변환해주는 Vue.js 기반 도구입니다.
- Vue.js 로 개발된 정적 사이트 생성기 (SSG)
- 기술문서에 최적화된 기본 테마 제공 (검색, 사이드바, 다국어 등)
- Plugin API 로 Google Analytics, PWA, SEO 등을 손쉽게 확장
- 마크다운 안에서 Vue 컴포넌트를 그대로 사용 가능
일상 비유로는, 워드 문서 폴더 하나를 통째로 잘 정돈된 기술 블로그로 바꿔주는 컨베이어 벨트 같은 녀석이라고 보시면 됩니다.
VuePress vs VitePress, 뭐가 다른가?
솔직하게 비교해 보겠습니다.
| 항목 | VuePress v2 | VitePress |
|---|---|---|
| 빌드 도구 | webpack 기반 (옵션으로 Vite) | Vite 기반 (기본) |
| 속도 | 준수 | 매우 빠름 (HMR 체감 2~5배) |
| 플러그인 생태계 | 풍부함 | 점진적으로 확대 중 |
| Vue 팀 공식 추천 | 유지되고 있음 | O (2026 현재) |
| 러닝 커브 | 낮음 | 낮음 |
VuePress 가 "구식" 은 아닙니다. 다만 Vue 팀이 VitePress 쪽으로 무게를 옮긴 상태이므로, 새 프로젝트라면 VitePress 를 먼저 보시는 게 합리적입니다.
설치 및 빌드 (2026 기준)
Node.js 는 LTS (20.x 이상) 권장합니다. 패키지 매니저는 pnpm 을 기본으로, npm 도 병기합니다.
# 프로젝트 초기화
mkdir my-docs && cd my-docs
pnpm init # 또는: npm init -y
# VuePress v2 로컬 설치
pnpm add -D vuepress@next @vuepress/client@next vue
# npm 의 경우
# npm install -D vuepress@next @vuepress/client@next vue
# 문서 디렉토리와 첫 페이지 생성
mkdir docs
echo '# Hello VuePress' > docs/README.mdpackage.json 에 스크립트를 추가합니다.
{
"scripts": {
"docs:dev": "vuepress dev docs",
"docs:build": "vuepress build docs"
}
}개발 서버 실행 및 빌드:
# 개발 모드 (http://localhost:8080)
pnpm docs:dev
# 정적 파일 빌드 (docs/.vuepress/dist)
pnpm docs:build디렉토리 구조
VuePress 에서 권장하는 구조입니다.
.
├── docs
│ ├── .vuepress (옵션)
│ │ ├── components (Vue 컴포넌트)
│ │ ├── theme (커스텀 테마)
│ │ ├── public (정적 리소스)
│ │ ├── styles (스타일)
│ │ ├── config.ts (메인 설정, TS 권장)
│ │ └── client.ts (클라이언트 확장)
│ ├── README.md (루트 페이지)
│ ├── guide
│ │ └── README.md
│ └── config.md
└── package.json2026 기준으로는 config.js 대신 config.ts 로 시작하는 것을 추천합니다. 타입 힌트가 붙어서 설정 실수가 확 줄어듭니다.
페이지 라우팅 규칙
타겟 디렉토리는 docs 이고, 아래 경로는 모두 docs 기준입니다.
| 파일 경로 | URL 경로 |
|---|---|
/README.md |
/ |
/guide/README.md |
/guide/ |
/config.md |
/config.html |
알아두면 좋은 마크다운 확장
코드 하이라이팅
```js
export default {
name: "MyComponent",
}
```줄 번호 표시
// docs/.vuepress/config.ts
import { defineUserConfig } from "vuepress"
export default defineUserConfig({
markdown: {
code: { lineNumbers: true },
},
})커스텀 컨테이너
::: tip
이것은 팁 블록입니다.
:::
::: warning
경고 블록도 가능합니다.
:::배포하기
GitHub Pages (GitHub Actions)
docs/.vuepress/config.ts 에 base 설정을 잊지 마세요. https://<USER>.github.io/<REPO> 라면 base: '/<REPO>/' 입니다.
.github/workflows/deploy.yml:
name: Deploy VuePress
on:
push:
branches: [main]
permissions:
contents: read
pages: write
id-token: write
jobs:
build-and-deploy:
runs-on: ubuntu-latest
steps:
- uses: actions/checkout@v4
- uses: actions/setup-node@v4
with:
node-version: 20
cache: pnpm
- uses: pnpm/action-setup@v4
with:
version: 9
- run: pnpm install --frozen-lockfile
- run: pnpm docs:build
- uses: actions/upload-pages-artifact@v3
with:
path: docs/.vuepress/dist
deploy:
needs: build-and-deploy
runs-on: ubuntu-latest
environment:
name: github-pages
steps:
- id: deployment
uses: actions/deploy-pages@v4Netlify
Netlify 는 2026년에도 VuePress 와 궁합이 좋습니다.
- Build command:
pnpm docs:build(또는npm run docs:build) - Publish directory:
docs/.vuepress/dist - Node version:
20
푸시만 해도 자동 배포되니, 개인 프로젝트라면 Netlify 가 가장 편합니다.
FAQ
Q1. 2026년에 VuePress 새로 시작해도 되나요?
유지는 되지만, 새로 시작한다면 VitePress 를 먼저 검토하시길 권합니다. 공식 추천, 빌드 속도, 최신 생태계 모두 VitePress 쪽이 앞서 있습니다. 기존 VuePress 프로젝트를 굳이 갈아엎을 필요까지는 없습니다.
Q2. React 를 쓰는데 VuePress 를 써도 되나요?
결과물은 정적 HTML 이라 사용자 입장에서는 문제가 없지만, 커스터마이징 시 Vue 컴포넌트 작성이 필요합니다. React 라면 Docusaurus, Nextra 쪽이 더 자연스럽습니다.
Q3. 블로그 용도로도 괜찮나요?
기술문서에 최적화되어 있어 블로그로 쓰려면 @vuepress/plugin-blog 같은 플러그인이 필요합니다. 블로그가 메인이라면 Gatsby, Astro, Next.js 가 더 편합니다.
관련 포스팅
참고 자료
VuePress 는 여전히 Vue 기반 SSG 의 교과서 같은 도구입니다. 입문용으로도, 사내 기술문서용으로도 충분히 제 역할을 합니다. 다만 2026년 기준으로 새 프로젝트라면 VitePress 도 꼭 비교해 보세요.
여러분은 기술문서 도구로 어떤 걸 쓰고 계신가요? 댓글로 경험 공유해 주시면 다음 포스팅 주제로 반영하겠습니다.