VuePress 搭建教程

VuePress 是一个由 Vue.js 驱动的静态网站生成器，非常适合用于技术文档的编写。以下是详细的搭建教程：

1. 环境准备

首先确保你已经安装了 Node.js (版本 ≥ 8.6) 和 npm/yarn。

bash 复制代码

# 检查 Node.js 和 npm 是否安装
node -v
npm -v

2. 创建 VuePress 项目

方法一：快速初始化

bash 复制代码

# 创建并进入新目录
mkdir vuepress-demo && cd vuepress-demo

# 初始化项目
npm init -y

# 安装 VuePress
npm install -D vuepress

方法二：使用 create-vuepress 脚手架

bash 复制代码

npx create-vuepress-site my-docs
# 或者
npm init vuepress-site my-docs

3. 项目结构

创建基本目录结构：

bash 复制代码

mkdir docs && cd docs
mkdir .vuepress

典型项目结构：

text 复制代码

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

4. 基本配置

在 .vuepress/config.js 中配置：

javascript 复制代码

module.exports = {
  title: '我的文档网站', // 网站标题
  description: '这是我的第一个 VuePress 网站', // 网站描述
  themeConfig: {
    nav: [
      { text: '首页', link: '/' },
      { text: '指南', link: '/guide/' }
    ],
    sidebar: [
      '/',
      '/guide/'
    ]
  }
}

5. 创建首页

在 docs/README.md 中添加：

markdown 复制代码

---
home: true
heroImage: /hero.png
actionText: 快速开始 →
actionLink: /guide/
features:
- title: 简洁至上
  details: 以 Markdown 为中心的项目结构，以最少的配置帮助你专注于写作。
- title: Vue驱动
  details: 享受 Vue + webpack 的开发体验，可以在 Markdown 中使用 Vue 组件。
- title: 高性能
  details: VuePress 为每个页面预渲染生成静态的 HTML，同时在页面被加载的时候，将作为 SPA 运行。
footer: MIT Licensed | Copyright © 2023-present Your Name
---

6. 添加文档页面

在 docs/guide/README.md 中添加内容：

markdown 复制代码

# 指南

这里是指南内容...

## 子标题

更多内容...

7. 运行开发服务器

在 package.json 中添加脚本：

json 复制代码

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

然后运行：

bash 复制代码

npm run dev

访问 http://localhost:8080 查看效果。

8. 部署

部署到 GitHub Pages

在 config.js 中设置 base：

javascript 复制代码

module.exports = {
  base: '/repository-name/', // 替换为你的仓库名
  // ...其他配置
}

创建部署脚本 deploy.sh：

bash 复制代码

#!/usr/bin/env sh

# 确保脚本抛出遇到的错误
set -e

# 生成静态文件
npm run build

# 进入生成的文件夹
cd docs/.vuepress/dist

# 如果是发布到自定义域名
# echo 'www.example.com' > CNAME

git init
git add -A
git commit -m 'deploy'

# 如果发布到 https://<USERNAME>.github.io
# git push -f git@github.com:<USERNAME>/<USERNAME>.github.io.git master

# 如果发布到 https://<USERNAME>.github.io/<REPO>
# git push -f git@github.com:<USERNAME>/<REPO>.git master:gh-pages

cd -

运行脚本部署：

bash 复制代码

chmod +x deploy.sh
./deploy.sh

9. 进阶配置

自定义主题

javascript 复制代码

module.exports = {
  themeConfig: {
    // 主题配置
    logo: '/assets/img/logo.png',
    lastUpdated: '最后更新',
    // 更多配置...
  }
}

插件系统

安装并使用插件：

bash 复制代码

npm install @vuepress/plugin-back-to-top @vuepress/plugin-medium-zoom --save-dev

配置：

javascript 复制代码

module.exports = {
  plugins: [
    ['@vuepress/back-to-top'],
    ['@vuepress/medium-zoom', {
      selector: '.theme-default-content img',
      options: {
        margin: 16
      }
    }]
  ]
}

10. 常用插件推荐

@vuepress/plugin-back-to-top - 返回顶部按钮
@vuepress/plugin-medium-zoom - 图片点击放大
@vuepress/plugin-search - 搜索功能
@vuepress/plugin-pwa - PWA 支持
vuepress-plugin-code-copy - 代码复制按钮

总结

通过以上步骤，你已经成功搭建了一个基本的 VuePress 文档网站。VuePress 的强大之处在于它的简洁性和可扩展性，你可以根据需要进一步定制主题、添加插件和优化配置。

更多详细配置请参考 VuePress 官方文档。