Introduction and Quick‑Start Guide to VuePress

VuePress is a minimal static site generator similar to Hexo, primarily used for writing technical documentation, though it can also be used to build blogs.

Key features include responsive design, customizable themes, built‑in Markdown with extensions, the ability to use Vue components inside Markdown, Google Analytics integration, and automatic PWA Service Worker generation.

Quick Start

Initialize a project:

yarn init -y
# or npm init -y

Install VuePress locally:

yarn add -D vuepress
# or npm install -D vuepress

Or install VuePress globally:

yarn global add vuepress
# or npm install -g vuepress

Create a docs folder and add a package.json script configuration:

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

Start the development server:

yarn docs:dev   # or npm run docs:dev

Open http://localhost:8080/ to preview the site.

Build

Generate static HTML files (output to .vuepress/dist ):

yarn docs:build   # or npm run docs:build

Basic Configuration

Create .vuepress/config.js and export a configuration object. Example site information:

module.exports = {
  title: '游魂的文档',
  description: 'Document library',
  head: [
    ['link', { rel: 'icon', href: `/favicon.ico` }]
  ]
}

Navbar Configuration

module.exports = {
  themeConfig: {
    nav: [
      { text: '主页', link: '/' },
      { text: '前端规范', link: '/frontEnd/' },
      { text: '开发环境', link: '/development/' },
      { text: '学习文档', link: '/notes/' },
      { text: '游魂博客', link: 'https://www.iyouhun.com' },
      {
        text: 'Languages',
        items: [
          { text: 'Chinese', link: '/language/chinese' },
          { text: 'English', link: '/language/English' }
        ]
      }
    ]
  }
}

Sidebar Configuration

Use a helper function to generate grouped sidebars:

function genSidebarConfig (title) {
  return [{
    title,
    collapsable: false,
    children: [
      '',
      'html-standard',
      'css-standard',
      'js-standard',
      'git-standard'
    ]
  }]
}

Example of a complex sidebar with front‑end and back‑end sections:

module.exports = {
  themeConfig: {
    sidebar: {
      '/frontEnd/': genSidebarConfig('前端开发规范'),
      '/note': [
        {
          title: '前端',
          collapsable: true,
          children: [
            '/notes/frontEnd/VueJS组件编码规范',
            '/notes/frontEnd/vue-cli脚手架快速搭建项目',
            '/notes/frontEnd/深入理解vue中的slot与slot-scope',
            '/notes/frontEnd/webpack入门',
            '/notes/frontEnd/PWA介绍及快速上手搭建一个PWA应用'
          ]
        },
        {
          title: '后端',
          collapsable: true,
          children: [
            'notes/backEnd/nginx入门',
            'notes/backEnd/CentOS如何挂载磁盘'
          ]
        }
      ]
    }
  }
}

Theme Customization

Create .vuepress/override.styl to modify theme colors:

$accentColor = #3eaf7c   // theme color
$textColor   = #2c3e50   // text color
$borderColor = #eaecef   // border color
$codeBgColor = #282c34   // code background

For page‑specific CSS, add a front‑matter field and target it in override.styl :

---
pageClass: custom-page-class
---

.theme-container.custom-page-class {
  /* custom page CSS */
}

PWA Settings

Enable Service Worker and add a manifest:

module.exports = {
  head: [
    ['link', { rel: 'icon', href: `/favicon.ico` }],
    ['link', { rel: 'manifest', href: '/manifest.json' }]
  ],
  serviceWorker: true
}

Deployment

Set the base URL in .vuepress/config.js when deploying to a sub‑path:

module.exports = {
  base: '/documents/'
}

Build the site and push the generated dist folder to GitHub Pages (or any static host). Example CI script ( deploy.sh ) for automatic deployment:

#!/usr/bin/env sh
set -e
# generate static files
npm run docs:build
# enter the output directory
cd docs/.vuepress/dist
# initialize a new git repo and push
git init
git add -A
git commit -m 'deploy'
# push to GitHub Pages (replace USERNAME/REPO as needed)
# git push -f [email protected]:USERNAME/REPO.git master:gh-pages
cd -

Common Pitfalls

Place all referenced assets in .vuepress/public .

When using a custom domain, remember to adjust the base path.

Sidebar groups automatically generate previous/next links.

Enabling automatic sidebar generation overrides manual sidebar groups.

Enable SSL when configuring PWA.