前段时间在朋友的推荐下了解到尤大还弄了个专门写技术文档的工具。当我第一次看到VuePress的时候有点小激动，这简约的设计太适合用来做博客网站了。

vuepress是什么

按照官方的说法：VuePress由两部分构成，一部分是一个极简静态网站生成器，它包含由 Vue 驱动的主题系统和插件 API。另一部分是为写技术文档而优化的默认主题。你可以在VuePress中编写Markdown文档，然后生成网页。每一个由VuePress生成的页面都带有预渲染好的HTML。通过虚拟访问每一条路径来渲染对应的HTML。在此就不多做赘述了。现在就用VuePress+github pages搭建一个博客网站。

先看一眼效果图，很简单，只是把架子搭出来，而其中的内容可以慢慢累积添加：

主页

文档页

环境要求

VuePress要求Node.js的版本最低是8。打开命令行执行node -v可以查看。如果你的版本低于这个可以先升级。

安装vuepress

全局安装，同时支持 npm 和 yarn

npm install -g vuepress

# 或者

yarn global add vuepress

初始化项目

下面是通过命令行进行操作，更快捷。每一步都有简单注释。如果习惯手动创建就只看注释好了 这里用的是windows系统，如果你是mac的话，创建文件的命令不一样windows是type nul>文件名，mac是touch 文件名。注意区分一下

C:\Users\Administrator>e:          

# 进入e盘

E:\>mkdir vuepress-test            

# 创建项目目录 vuepress-test

E:\>cd vuepress-test                

# 进入 vuepress-test

E:\vuepress-test>npm init          

# 初始化项目npm init， 也可以 yarn init

E:\vuepress-test>mkdir docs        

# 在vuepress-test下创建docs目录,作为项目文档根目录,主要放置.vuepress目录和你的MD文档

E:\vuepress-test>cd docs          

# 进入 docs

E:\vuepress-test\docs>mkdir .vuepress          

# 创建 .vuepress 目录

E:\vuepress-test\docs>cd .vuepress            

# 进入 .vuepress 目录

E:\vuepress-test\docs\.vuepress>type nul>config.js  

# 创建 config.js文件，这是配置文件。

E:\vuepress-test\docs\.vuepress>mkdir public  

# 创建 public 目录，这里面主要放置图片等资源

基本的结构就出来了，如下：

vuepress-test

├─── docs

│   └── .vuepress

│       ├── public

│       └── config.js

└── package.json

接下来我们象征性的建两个文件夹js和vue和各自目录下的md文件。这里做一个简单提示：在vuepress中会把.md文件解析成html。一个目录下面的README.md就相当于index.js。访问该目录的时候没有指定文件就默认是访问README.md

继续……

E:\vuepress-test\docs\.vuepress>cd ..

# 返回上一级目录 docs

E:\vuepress-test\docs>type nul>READEME.md

# 创建 READEME.md  也就是我们网站的首页

E:\vuepress-test\docs>mkdir js

# 创建目录 js

E:\vuepress-test\docs>cd js

# 进入 js 目录

E:\vuepress-test\docs\js>type nul>READEME.md

# 创建 READEME.md 文件

E:\vuepress-test\docs\js>cd ..

# 返回上一级目录 js

E:\vuepress-test\docs>mkdir vue

# 创建目录 vue  

E:\vuepress-test\docs>cd vue

# 进入目录 vue

E:\vuepress-test\docs\vue>type nul>README.md

# 创建 README.md 文件

E:\vuepress-test\docs\vue>type nul>vuex.md

# 创建 vuex.md

这时候我们需要的文件就基本创建好了，然后进行相应的配置。

配置

config.js 主要配置包括网站的标题、描述和网站导航配置等基本信息。这里简单的列举一下常用配置。

module.exports = {

 title: 'myblog',            //'标题'

 description: '马上开始吧',  //'描述'

 head: [                    // 注入到当前页面的 中的标签

   ['link', { rel: 'icon', href: './public/apple-touch-icon-152x152.png' }],  //网页标签上的icon图标

 ],

 dest: 'public',      //放置静态资源文件，打包后会在.vuepress/dist中

 markdown: {

   lineNumbers: true // 代码块是否显示行号

 },

 themeConfig: {                

   nav:[            //顶部导航栏配置

     { text: '主页', link: '/' },    //此处的斜杠代表 docs里面的README.md 文件，也就是的主页

     { text: 'javascript', link: '/js/' },    

     { text: 'vue', link: '/vue/' },

     {

       text: '传送门',         // 鼠标悬浮出现下拉导航菜单

       items: [

         { text: 'vue.js', link: 'https://cn.vuejs.org/' },

         { text: 'react', link: 'https://reactjs.org/' },

       ]

     }      

   ],

   sidebar: [      //  侧边导航配置

     {

       title: 'javascript', // 侧边栏名称

       collapsable: true,   // 可以折叠

       children: [          

         '/js/'        //js文件夹下的 README.md

       ]

     },

     {

       title: 'vue',

       collapsable: true,

       children: [

         '/vue/',

         '/vue/vuex',

       ]

     }

   ],

   sidebarDepth: 2, // 可提取markdown中h2 和 h3 标题，显示在侧边栏上。

   lastUpdated: 'Last Updated', // 显示文档更新时间：每个文件git最后提交的时间

 }

}

简单的配置就ok了。然后再把那几个md文档随便写点内容以进行区分

首页

docs目录下的README.md，我们这里是按照官网的默认主题。 当然也可以使用其他的主题。

---

home: true

heroImage: /logo.jpg       //主页中的那张图片

actionText: 快速上手 →

actionLink: /js/      //点击快速上手需要查看的文件路径

features:

- title: 简洁至上

 details: 以 Markdown 为中心的项目结构，以最少的配置帮助你专注于写作。

- title: Vue驱动

 details: 享受 Vue + webpack 的开发体验，在 Markdown 中使用 Vue 组件，同时可以使用 Vue 来开发自定义主题。

- title: 高性能

 details: VuePress 为每个页面预渲染生成静态的 HTML，同时在页面被加载的时候，将作为 SPA 运行。

footer: MIT Licensed | Copyright © 2018-present Evan You

---

文档页

把js和vue文件夹下的.md文件象征性的写点内容区分一下。当然如果你之前就有现成的md文章也可以拿过来。例如：

## js

>这里是js页面

设置package.json

配置dev 和 build命令

{

 "name": "project",

 "version": "1.0.0",

 "description": "",

 "main": "index.js",

 "scripts": {

   "dev": "vuepress dev docs",        

   "build": "vuepress build docs"            

 },

 "keywords": [],

 "author": "",

 "license": "ISC"

}

 npm run dev 把项目跑起来。通过http://localhost:8080即可预览网站

部署

执行 npm run build 然后将打出来的项目包上传到github仓库。在仓库设置中找到GitHub Pages下的Source将网站挂出来。这样其他的人就能访问你的博客网站了。在此给新手提个提示，一定要将仓库名称设置成.github.io结尾。

另外也可以配置脚本的方式部署，非常方便。基本做法是在项目根目录下建一个deploy.sh的文件。将打包命令和git命令写进去。在config.js中设置base属性(路径)。在package.json的scripts中添加一条命令("deploy": "bash deploy.sh" )执行该脚本。这样就可以远程一键部署了，仓库资源更新，博客网站的内容也就跟着更新了。详情参考 官方文档 -> 部署

还想继续玩的话可以买个域名，设置域名解析到GitHub pages给你分配的固定IP(命令行输入ping 加你的.github.io域名)。再到github仓库设置中，GitHub Pages下找到Custom domain，输入你购买的域名，然后保存即可。可能要过一两天的时间才会生效。当然购买域名的时候要注意，域名备案流程比较麻烦。而有些域名是必须要备案的，如.cn。可以选择购买那些不强制要求备案的，如.com .net。

最重要的

坚持写文章，把内容丰富起来。