DIMORIN BLOG

vuepress

Inside an Existing Project

If you have an existing project and would like to keep documentation inside the project, you should install VuePress as a local dependency. This setup also allows you to use CI or services like Netlify for automatic deployment on push.

# install as a local dependency
yarn add -D vuepress # OR npm install -D vuepress

# create a docs directory
mkdir docs
# create a markdown file
echo '# Hello VuePress' > docs/README.md

Then, add some scripts to package.json:

{
  "scripts": {
    "docs:dev": "vuepress dev docs",
    "docs:build": "vuepress build docs"
  }
}

You can now start writing with:

yarn docs:dev # OR npm run docs:dev

To generate static assets, run:

yarn docs:build # Or npm run docs:build

By default the built files will be in .vuepress/dist, which can be configured via the dest field in .vuepress/config.js.

tip

# Visual Studio Code 실행
code .

Config File

Without any configuration, the page is pretty minimal, and the user has no way to navigate around the site. To customize your site, let's first create a .vuepress directory inside your docs directory. This is where all VuePress-specific files will be placed in. Your project structure is probably like this:

.
├─ docs
│  ├─ README.md
│  └─ .vuepress
│     └─ config.js
└─ package.json

The essential file for configuring a VuePress site is .vuepress/config.js, which should export a JavaScript object:

module.exports = {
  title: 'Hello VuePress',
  description: 'Just playing around'
}

If you've got the dev server running, you should see the page now has a header with the title and a search box. VuePress comes with built-in headers-based search - it automatically builds a simple search index from the title, h2 and h3 headers from all the pages.

The Navbar may contain your page title, Search Box, Navbar Links, Languages and Repository Link, all of them depends on your configuration.

You can add links to the navbar via themeConfig.nav:

// .vuepress/config.js
module.exports = {
  title: 'Hello VuePress',
  description: 'Just playing around',
  themeConfig: {
    nav: [
      { text: 'Home', link: '/' },
      { text: 'Guide', link: '/guide/' },
      { text: 'External', link: 'https://google.com' },
    ]
  }
}

Homepage

vuepress 공식 홈페이지의 대문과 똑같이 꾸미기 위해,

.vuepress 디렉토리 아래에 public 폴더를 만들고 그 안에 images 폴더를 만들고 이미지를 하나 넣어놓자. vuepress 공식 홈페이지에서 Default Theme Config / Homepage 에서 아래의 코드를 복사해 루트의 README.md 에 붙여놓자. heroImage 경로와 이미지명도 수정!

---
home: true
heroImage: /images/Latest.png
heroText: Hero Title
tagline: Hero subtitle
actionText: Get Started →
actionLink: /guide/
features:
- title: Simplicity First
  details: Minimal setup with markdown-centered project structure helps you focus on writing.
- title: Vue-Powered
  details: Enjoy the dev experience of Vue + webpack, use Vue components in markdown, and develop custom themes with Vue.
- title: Performant
  details: VuePress generates pre-rendered static HTML for each page, and runs as an SPA once a page is loaded.
footer: MIT Licensed | Copyright © 2018-present Evan You
---

Auto Sidebar for Single Pages

docs 폴더 아래에 guide 폴더를 만들고 그 안에 README.md 만들어 내용을 채워넣는다.

아래와 같이 config.js에 sidebar:'auto' 삽입한다.

// .vuepress/config.js
module.exports = {
  title: 'Hello VuePress',
  description: 'Just playing around',
  themeConfig: {
    nav: [
      { text: 'Home', link: '/' },
      { text: 'Guide', link: '/guide/' },
      { text: 'External', link: 'https://google.com' },
    ],
    sidebar: 'auto'
  }
}

Multiple Sidebars

If you wish to display different sidebars for different sections of content, first organize your pages into directories for each desired section: guide 폴더 안에 backend.md 와 frontend.md를 만들어 내용을 채워넣는다.

.
├─ README.md
├─ guide/
  ├─ README.md
  ├─ frontend.md
  └─ backend.md

Then, update your configuration to define your sidebar for each section.

// .vuepress/config.js
module.exports = {
  themeConfig: {
    sidebar: {
      '/guide/': [
        '',     /* /guide/ */
        'frontend',  /* /guide/frontend.html */
        'backend'   /* /guide/backend.html */
      ]
    }
  }
}

Styling

palette.styl

If you wish to apply simple color overrides to the styling of the default preset or define some color variables for using later, you can create an .vuepress/styles/palette.styl file.

There are a few color variables you can tweak:

// showing default values
$accentColor = #3eaf7c
$textColor = #2c3e50
$borderColor = #eaecef
$codeBgColor = #282c34

index.styl

VuePress provides a convenient way to add extra styles. you can create an .vuepress/styles/index.styl file for that. This is a Stylus file but you can use normal CSS syntax as well.

.content {
  font-size 30px
}

Github pages로 배포하기

vuepress build docs 명령어를 사용하면 .vuepress/dist 폴더 안에 빌드된 프로젝트 파일들이 생성되는데 (평상시에는 vuepress dev docs 명령어로 실시간 프리뷰와 디버깅을 할 수 있다), Github에서 지원하는 subtree 기능을 통해 같은 레포지토리에서 dist 폴더만을 깃허브 페이지를 통해 배포할 수 있다.

git add docs/.vuepress/dist
# CRLF 에러시 다음 명령
git config --global core.safecrlf false
git commit -m "Upload dist"
git subtree push --prefix docs/.vuepress/dist origin master

해당 커맨드로 레포지토리의 master 브랜치에 dist 폴더의 내용이 업로드되고, 이 브랜치를 Github pages의 배포 기능에서 선택하면 된다.

Git 에러 CRLF will be replaced by LF (혹은 반대) 핸들링하는 방법

← jekyll 이란? →