VuePress 文档

快速导航

• 简介
  • 核心特性
  • 适用场景
• 快速开始
  • 环境要求
  • 安装步骤
• 项目结构
• 基础配置
  • 站点配置
  • Frontmatter
• Markdown 增强
  • 代码块
  • 提示框
  • Vue 组件
• 部署指南
  • 构建
  • 部署平台
  • 部署步骤
• 进阶功能
  • 国际化
  • PWA 支持
  • SEO 优化

简介

VuePress 是一个基于 Vue 的静态网站生成器，由 Vue.js 的创建者尤雨溪开发。它专注于以 Markdown 为中心的内容创作，通过最少的配置帮助你专注于写作。

核心特性

• Vue 驱动: 享受 Vue + webpack 开发体验
• 高性能: 预渲染的静态 HTML，运行时 SPA
• 主题系统: 支持自定义主题
• 插件支持: 灵活的插件 API
• Markdown 增强: 内置强大的 Markdown 扩展

适用场景

• 技术文档
• 项目文档
• API 文档
• 个人博客
• 团队知识库

快速开始

环境要求

• Node.js >= 12.0.0
• Yarn 或 npm 或 pnpm

安装步骤

1. 创建并进入项目目录

mkdir vuepress-demo
cd vuepress-demo

2. 初始化项目

npm init

3. 安装 VuePress

npm install -D vuepress@next

4. 创建文档

mkdir docs
echo '# Hello VuePress' > docs/README.md

5. 配置 package.json

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

项目结构

.
├── docs
│   ├── .vuepress
│   │   ├── config.js     # 配置文件
│   │   ├── public        # 静态资源
│   │   └── styles        # 样式文件
│   └── README.md         # 首页
└── package.json

基础配置

站点配置

在 .vuepress/config.js 中配置：

module.exports = {
  title: '网站标题',
  description: '网站描述',
  themeConfig: {
    navbar: true,
    sidebar: 'auto'
  }
}

Frontmatter

在 Markdown 文件顶部配置：

---
title: 页面标题
description: 页面描述
sidebar: auto
---

Markdown 增强

VuePress 提供了多种 Markdown 增强特性：

代码块

console.log('Hello VuePress!')

提示框

提示

这是一个提示

警告

这是一个警告

Vue 组件

你可以在 Markdown 中直接使用 Vue 组件：

<CustomComponent/>

部署指南

构建

npm run docs:build

部署平台

• GitHub Pages
• Netlify
• Vercel
• 自托管服务器

部署步骤

1. 构建静态文件
2. 选择部署平台
3. 配置部署选项
4. 上传并发布

进阶功能

国际化

module.exports = {
  locales: {
    '/': {
      lang: 'zh-CN',
      title: '中文网站'
    },
    '/en/': {
      lang: 'en-US',
      title: 'English Site'
    }
  }
}

PWA 支持

module.exports = {
  plugins: [
    '@vuepress/pwa',
    {
      serviceWorker: true,
      updatePopup: true
    }
  ]
}

SEO 优化

module.exports = {
  head: [
    ['meta', { name: 'keywords', content: '关键词' }],
    ['meta', { name: 'description', content: '描述' }]
  ]
}