VuePress搭建文档博客超详细教程

本文主要是介绍VuePress搭建文档博客超详细教程，希望对大家解决编程问题提供一定的参考价值，需要的开发者们随着小编来一起学习吧！

前言

搭建文档，个人博客用什么比较用；当然是Vue全家桶之一的vuepress啦；这可是大神尤雨溪推出的一款模板；

vuepress用于迅速搭建技术文档网站与个人博客，简单快捷，下面和我一起开始学习吧！

一、成品展示

1. 技术文档网站：

vue全家桶官网：vue、vuex、vue-cli、vue-router以及vuepress本身

2. 个人博客：

组件zhb-ui 使用文档

3. 官方文档

VuePress

二、开始搭建

搭建之前建议大家先学习了解一下markdown语法，为之后的文档撰写做铺垫;

1. 全局安装 VuePress

npm install \-g vuepress

2. 创建并进入项目

mkdir vuepress-demo && cd vuepress-demo

3. 初始化项目

npm init \-y // 默认配置yes
在生成的package.json中，添加如下两个启动命令：

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

4. 创建基本项目结构

官方只有推荐目录结构，并没有现成的cli，所以需要通过命令行或手动创建如下结构：

vuepress-demo
├─package.json
├─docs
|  ├─README.md
|  ├─.vuepress
|  |     ├─config.js
|  |     ├─public
|  |     |   └avatar.png
|  |     |   └spider.png

其中有后缀的是文件，没后缀的是文件夹

5.创建一个 docs 目录

作为项目文档的根目录来使用

6.在docs文件夹下创建.vuepress文件夹

配置文件都放置在该目录下

7.在.vuepress文件夹下新建config.js

添加网站名称和描述

8. 配置config.js

该文件为项目最重要的配置文件，几乎所有配置项都是在此进行。
我们先来一个最简单的配置看看效果：

module.exports = {base:'/zhb-docs/',title:'zhb-ui',description:"一款轻量级、模块化的前端 UI 组件库",head: [['link', { rel: 'icon', href:'logo.png'}],['meta', { name: 'keywords', content:'jieshao'}]],themeConfig: {logo: '/assets/img/logo.png',nav: [{ text: '组件', link: '/component/giud' },{ text: '前端案例', link: '/demo/'},{ text:'关于我',link:'/about'},{ text:'CSDN',link:'https://blog.csdn.net/u012967771'},{text:'npm',link:"https://www.npmjs.com/package/zhb-ui"},{ text:'GitHub', link:'https://github.com/zhbnyx/zhb-ui'},],sidebar:{'/component/': [{title: '指南',collapsable: false,children: [{title: '介绍', path: '/component/giud'},{title: '安装', path: '/component/install'},{title: '快速开始', path: '/component/start'}]},{title: '基础组件',collapsable: false,children: [{title: 'Icon 图标', path: '/component/icon'},{title: 'Button 按钮', path: '/component/button'}]}],'/demo/': [{title: '前端案例',collapsable: false,children: [{title: '案例', path: '/demo/demo'},]}]},}
}

想看详细配置的同学可直接查询官网-config配置。
注意：路由根路径为docs文件夹，静态资源（图片）根路径为public文件夹

注意：使用静态文件时，需以如下写法，否则打包部署GitHub pages 预览会出现404 问题

<img :src="$withBase('/assets/img/icon.png')" style="margin: 15px 0 ">

9.在.vuepress文件夹下面创建public文件夹

存放用到的静态资源

10.在.vuepress文件夹下面创建README.md

该README.md文件将会被作为默认主题主页布局

11.启动项目

上文在package.json 中script配置了qi'dong项：

vuepress dev docs

默认服务启动在了http://localhost:8080/，效果如下：

预览：我这里做了配置更改，相当于做了一个欢迎页，点击开始使用进入正式文档！

三、部署上线

通过以上步骤，就可以搭建一个文档博客了，下面我们就继续讲项目打包上传部署服务器；

1.服务器选择

代码仓库，GitHub和Gitee，都可以，相比较而言：GitHub受众更广，Gitee速度更快！全凭看官喜好！

这里以GitHub为例：

2. github创建仓库

① 登录 github
② 新建仓库：zhb-docs

3. 建立打包部署脚本

①根目录下新建deploy.sh:

# 确保脚本抛出遇到的错误
set -e# 生成静态文件
npm run docs:build# 进入生成的文件夹
cd docs/.vuepress/dist# 如果是发布到自定义域名
# echo 'www.example.com' > CNAMEgit init
git add -A
git commit -m 'deploy'# 如果发布到 https://<USERNAME>.github.io#git push -f git@github.com:zhbnyx/zhbnyx.github.io.git master# 如果发布到 https://<USERNAME>.github.io/<REPO>
git push -f git@github.com:zhbnyx/zhb-docs.git master:gh-pagescd -

②package.json 文件夹中添加发布命令：