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' > CNAME

git 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-pages

cd -

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

"scripts": {
  "deploy": "bash deploy.sh"
}

注意：代码提交与部署dist需要分开，部署直接执行 yarn deploy上传至分支即可；

4.发布成功！

在GitHub仓库中 settings 中设置pages预览！

查看自己的博客域名：zhb-ui 文档
这样所有的人都能访问到你的博客了！

---

感谢阅读，谢谢！