# VuePress v1.x로 업그레이드하기
# 서두
VuePress가 어느덧 안정화 되었다고 판단했는지, v1.0을 정식 런칭했다. 간단히 살펴보면 기존 v0.14와 비교해서 눈에 띄는 달라진 점은...
- 마크다운 슬롯
- 플러그인
- 커스텀 테마
정도이다. 기본적인 동작은 크게 바뀌지 않았다.
굳이 공식 사이트에 있는 내용을 그대로 반복 기술하진 않겠다. 진행하면서 발생한 특이사항 위주로 기록한다.
# 사전 준비
글로벌과 현재 프로젝트 내의 VuePress를 v1.x으로 재설치 해준다.
> npm i -g vuepress@1
>
> npm i -D vuepress@1
2
3
WARNING
나의 경우, 기존 v0.x에서 사용하던 모듈이 충돌을 일으켰다.
잘 되지 않는다면 node_modules를 삭제하고 다시 설치해보자.
자, 사전 준비가 되었으니 공식 문서를 보고 마이그레이션을 진행해보자.
Migration from 0.x | VuePress (opens new window)
생각보다 변경할 내용이 많진 않다. 내 프로젝트에 해당하는 사항들을 골라서 적용해보자.
# Google Analytics 설정 변경
기존에는 Google Analytics 설정이 빌트인이었다면, 이제는 플러그인 형태로 분리되었다. 플러그인을 설치하자.
> npm install -D @vuepress/plugin-google-analytics
TIP
공식 문서대로 @next를 붙이면 오히려 1.0.0-rc.1이 설치된다. @next를 빼자.
# style.styl 파일 변경
스타일도 모듈화 가능하도록 폴더 구조로 개선되었다. 역시 적용해보자.
.vuepress/style.styl --이동--> .vuepress/styles/index.styl
# 1차 테스트
가이드에 해당하는 작업은 완료되었다. 한번 돌려보면...
> npm run docs:dev
해보니 CLI에서는 성공이나 브라우저에서 열어보면 흰 화면만 나오며, 개발자도구를 열어보면 에러 뭉텅이가 발견된다...
에러 내용을 잘 살펴보니 커스터마이징 했던 테마가 v0.x꺼라서 호환이 안되는듯 하다. 기존에 예상한대로, 테마나 레이아웃은 버전업 할때마다 다시 적용해줘야 한다.
물론 이제는 커스텀 테마를 플러그인처럼 도입할 수 있으므로 커스텀 테마로 분리해내는 것이 정석이다. 하지만 일단 마이그레이션이 우선이므로 기존 방식대로 프로젝트 내에 빌트인 커스텀 방식으로 해결하자.
Custom Themes | VuePress 0.x (opens new window)
# Custom Theme 제거
레이아웃 관련해서 변경했던 코드를 잘 보관해 둔 후, .vuepress/theme 폴더를 제거한다. 다시 돌려보니 잘 동작한다. 다만 커스텀 테마를 제거하였으므로 태그나 댓글이 보이지 않았다.
앗, 그리고 커스텀 컨테이너가 제대로 나오지 않는다. 예를 들면
::: tip
블라블라
:::
2
3
이 컨테이너가 표현되지 않고 문법이 그대로 드러나버렸다. 개발서버만의 문제인건지... 재시작을 해도 제대로 나오지 않는다. 캐시를 한번 비워줬다.
> vuepress dev docs --no-cache
그래도 완전히 해결되지 않아서, md 파일 자체를 갱신해주니 동작한다.
이 부분은 재현하기 어려운 부분이라 버그 리포트 하기도 번거롭고... 일단 스킵.
# Custom Theme 재적용
이제 이전처럼 다시 커스텀 테마를 적용할 시간이다.
원본 소스의 테마 위치가 조금 변경되었다.
vuepress.git/packages/@vuepress/theme-default --복사--> .vuepress/theme
그리고 .vuepress/theme/component/Page.vue를 기존 포스팅 내용처럼 커스터마이징하면 된다.
정상 작동!
개선
더 좋은 방법을 찾아서 문서를 개선하였습니다.
커스텀 테마를 위해 테마 전체를 덮어씌우는게 아니라 변경된 파일만 적용하는 방법이 소개되어 있다. Theme Inheritance | VuePress (opens new window)
theme 폴더의 내용을 모두 제거하고 설정 파일에 기본 테마를 상속한다고 선언해주자.
// .vuepress/theme/index.js
module.exports = {
extend: '@vuepress/theme-default'
}
2
3
4
그리고 기존에 변경을 가했던 Page.vue 파일과 함께 의존성이 있는 wrapper.styl 파일만 폴더에 넣어준다.
.
└─ .vuepress
└─ theme
├─ components
│ └─ Page.vue
├─ styles
│ └─ wrapper.styl
└─ index.js
2
3
4
5
6
7
8
정상 작동!
# 결론
일단 급한대로 업그레이드가 완료되었다. 정식 버전이긴 하지만 아직도 자잘한 버그는 발견된다. 큰 문제는 없으므로 향후 더욱 개선될 것으로 기대하며 업그레이드를 마무리 하기로...
앞서 언급했지만 커스텀 테마는 기존 방식이 아닌, 별도의 플러그인 프로젝트로 만드는게 답이다. 시간이 된다면 언제 시도해 보도록 하겠다. 아직도 댓글 기능이나 태깅 기능이 들어간 레이아웃이 없는듯 하므로.