如何使用vuepress构建一个VUE文档风格的静态页面

VuePress 简述

VuePress 是 Vue 驱动的静态网站生成器，具有简洁，Markdown 支持，Vue 驱动，高性能等特点，并且十分容易上手，可以在很短时间就能学习并搭建好，拥有以下特点。

为技术文档而优化的内置 Markdown 拓展
在 Markdown 文件中使用 Vue 组件的能力
Vue 驱动的自定义主题系统
自动生成 Service Worker
Google Analytics 集成

快速构建 VuePress 项目

项目安装VuePress

## 安装依赖 #
npm init
npm install -D vuepress
## 创建主页文件 #
mkdir docs && echo '## Hello VuePress' > docs/README.md
## 初始化项目 #
yarn init # 或者 npm init

在`package.json`中的`scripts`添加两行命令

{
  "scripts": {
    "docs:dev": "vuepress dev docs --temp .temp,
    "docs:build": "vuepress build docs"
  }
}

运行编译环境

npm run docs:dev

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

mkdir .vuepress

所有 VuePress 相关的文件都将会被放在这里，具体参考官方的目录说明

在`.vuepress`文件夹下面创建`config.js`

config.js是VuePress必要的配置文件，它导出一个javascript对象。

module.exports = {
  title: 'Hello VuePress',
  description: 'Just playing around'
}

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

mkdir public

这个文件夹用来放置静态资源的，打包出来之后会放在.vuepress/dist/的根目录。

首页 README.md

默认的主题提供了一个首页，像下面一样设置home:true即可，可以把下面的设置放入README.md中。

---
home: true
heroImage: /logo.jpg
actionText: 快速上手 →
actionLink: /zh/guide/
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
---

基本构建结构

project
├─── docs
│   ├── README.md
│   └── .vuepress
│       ├── public
│       └── config.js
└── package.json

config.js 基本配置项

官方文档：vuepress.vuejs.org/zh/config

module.exports = {
  // 文档标题
  title: `Mr.Mao's blog`,
  // 文档说明
  description: 'For man is man and master of his fate.',
  // 静态资源基本路径
  base: '/mao-blog/',
  // 设置网站图标
  head: [
    ['link', { rel: 'shortcut icon', type: "image/x-icon", href: `/favicon.ico` }]
  ],
  themeConfig: {
    // 导航栏配置
    nav: [
      { text: '首页', link: '/' },
      {
        text: '软件开发', icon: 'reco-document', items: [
          { text: '前端开发', link: '/notes/frontend/01-HTML' },
          { text: '后端开发', link: '/notes/backend/01-php' },
          { text: '知识扩展', link: `/notes/extends/01-Promise` }
        ]
      },
      {
        text: '我的扩展', items: [
          { text: '快速创建视图 | create-uniapp-view', link: '/my-extends/create-uniapp-view' },
          { text: '多端海报绘制 | uni-draw-poster', link: '/my-extends/uni-draw-poster' },
          { text: '表单策略验证 | form-strategy', link: '/my-extends/form-strategy' },
        ]
      },
      {
        text: '规划指南', items: [
          { text: '生活指标', link: '/guides/01-life' },
          { text: '总结与规划', link: '/guides/02-year' },
        ]
      },
    ],
  },
}

config.js 插件扩展

解决 markdown 图片引用路径问题

安装：npm i markdown-it-disable-url-encode -D

在config.js中添加如下代码

module.exports = {
  markdown: {
    extendMarkdown: md => {
      md.use(require("markdown-it-disable-url-encode"));
    }
  },
}

自动生成docs下文档目录侧边栏

安装：npm i vuepress-plugin-auto-sidebar -D

project
├─── docs
│   ├── guides
│   	├── a.md
│   	└── b.md
│   ├── ...
│   └── .vuepress
└── package.json