基础功能

VuePress搭建

mkdir vuepress-demo && cd vuepress-demo

初始化

npm init

将 VuePress 安装为本地依赖

npm install -D vuepress

配置package.json

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

创建文件夹和文件在根文件夹 vuepress-demo 中创建 docs 文件夹，在 docs 中创建 .vuepress 文件夹和README.md，在.vuepress中创建config.js文件，最终项目结构如下所示：

vuepress-demo
├─── docs
│    ├── README.md 
│    └── .vuepress 
│        └── config.js 
└── package.json

在docs/.vuepress/config.js中配置网站标题、描述、导航栏、侧边导航栏等信息

module.exports = {
  title: '个人文档',
  description: '练习文档',
  base: '/', // 这是部署到github相关的配置
  markdown: {
    lineNumbers: false // 代码块显示行号
  },
  themeConfig: {
    nav:[ // 导航栏配置
      {text: '导航栏一', link: '/nav1/' },
      {text: '导航栏二', link: '/nav2/'},
      // 下拉列表显示分组
      {
        text: '高级',
        items: [
          { 
            text: '算法', 
            items: [
              { text: '冒泡', link: '/nav3/nav3-1' },
              { text: '快速', link: '/nav3/nav3-2' }
            ] 
          },
          { 
            text: '设计模式', 
            items: [
              { text: '工厂', link: '/nav4/nav4-1' },
              { text: '单例', link: '/nav4/nav-4-2'},
            ] 
          },
        ]
      }   
    ],
    sidebarDepth: 2, // 侧边栏显示2级 
    sidebar: {  // 侧边栏配置
      '/nav1/': [
        '/nav1/1.md',
        '/nav1/2.md' 
      ],
      '/nav2/':[
        {
          title: 'combination-1',
          collapsable: false,
          children: [
            '/nav2/com1/1.md',
            '/nav2/com2/1.md'
          ]
        },
        {
          title: 'combination-2',
          collapsable: true, // 是否折叠
          children: [
            '/nav2/com2/1.md',
            '/nav2/com1/1.md'
          ]
        },
      ]
    }
  },
};

其中，在nav参数中设置的导航栏，导航栏中的link字段的参数为该导航栏的访问路径，需要与对应的文件放置地址一致，否则访问会404，比如：导航栏一的link为'/nav1/',对应的文件夹路径为/docs/nav1/; sidebar参数设置各个导航栏下的侧边导航栏，支持嵌套。以nav1为例，nav1所包含的侧边栏为/nav1/1.md和/nav1/2.md，这两个路径对应的文件地址分别为/docs/nav1/1.md和/docs/nav1/2.md

设置侧边导航栏的title有两种方式方法一：md文件顶部使用front matter设置标题的方法

---
title: 自定义标题
---

方法二：md文件的第一个一级标题自动转换为该侧边栏的title

# 导航栏一的侧边栏一

在docs/README.md 配置首页信息

---
home: true
actionText: 快速上手
actionLink: /zh/guide/
features:
- title: 简洁至上
  details: 以 Markdown 为中心的项目结构，以最少的配置帮助你专注于写作。
- title: Vue驱动
  details: 享受 Vue + webpack 的开发体验，在 Markdown 中使用 Vue 组件，同时可以使用 Vue 来开发自定义主题。
- title: 高性能
  details: VuePress 为每个页面预渲染生成静态的 HTML，同时在页面被加载的时候，将作为 SPA 运行。
---

8. 在本地启动服务器

npm run docs:dev

配置

1. 不想使用VuePress的默认主题

VuePress官网介绍了如何开发和配置主题：vuepress.vuejs.org/zh/theme/，在这里也简单列出几个开源的VuePress主题

提示：VuePress官网中介绍了以npm包的形式引入主题，如果该主题满足你的需求，可继续采用此种方式，若想在该主题上增加或者修改些东西，那么建议以下面这种方式来引入主题

// 将该主题的npm包下载下来，将该主题的文件夹直接放置在你的工程当中（建议放置在根目录下，与`docs`同级

// .vuepress/config.js
module.exports = {

    theme: require.resolve(主题的路径), // 使用本地主题
}

2. 修改工程的默认首页

上面介绍了首页的配置是在docs/README.md中配置的，其中像actionText、actionLink这些参数都是在主题中暴露出来的，在主题中找到首页对应的文件，修改其代码，即可自定义配置首页。

sushi-docs使用的是vuepress-theme-vdoing主题，首页对应的文件地址为vuepress-theme-vdoing/components/Home.vue,重构该文件即生成了sushi-docs的首页

3. Demo演示框

借助于插件,VuePress 插件可以为你提供各种不同的功能。安装 vuepress-plugin-demo-container或其他同类插件，可以实现像Element UI官网一样的demo演示。

实现方式

安装vuepress-plugin-demo-container

npm i vuepress-plugin-demo-container -s'

在/docs/.vuepress/config.js配置插件

// .vuepress/config.js
module.exports = {

    plugins: [ // 插件
        ['demo-container']
    ]
}

如果demo中使用了第三方的依赖包，在/docs/.vuepress中新增enhanceApp.js

// .vuepress/enhanceApp.js
// 全局注册 Element 组件库
import Vue from 'vue'
import Element from 'element-ui'
import 'element-ui/lib/theme-chalk/index.css'

export default ({
  Vue,
  options,
  router
}) => {
  Vue.use(Element)
}

4. 部署

运行npm run docs:build命令进行打包，在/docs/.vuepress下生成dist文件，把该文件放置在服务器上进行部署。

除此之外，还可利用github和gitee的page服务，在线部署，使用此功能，需要在/docs/.vuepress/config.js中配置base字段

// .vuepress/config.js
module.exports = {

   base: '部署站点的基础路径'
}

VuePress官网关于base的介绍

如何快速搭建博客 or 文档网站