使用VuePress搭建一个简洁的技术文档

长期搬砖难免遇到各种各样的问题，新人入职后也需要一份完整、清晰的文档指导其展开工作，而Hexo更适合做个人博客，因此这里选用 VuePress 来构建。

1、安装Node.js

Node.js安装教程
此处不再赘述。

2、创建并进入目录

mkdir vuepress-starter && cd vuepress-starter

3、初始化

npm init

4、安装依赖

npm install -D vuepress

5、创建文档

mkdir docs && echo '# Hello VuePress' > docs/README.md

6、修改package.json

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

7、启动服务器本地预览

npm run docs:dev

在 http://localhost:8080 即可预览

上面的内容与官网文档一致，接下来简单介绍一些进阶配置

1、进入docs文件夹并构建如下目录

1. .vuepress下的config.js存放配置信息，包括导航栏、侧边栏等。
2. images下存放各种图片资源，包括导航栏的logo等
3. data-guide-book存放所有文章

2、使用默认主题

修改 README.md

---
home: true
heroImage: /assets/images/logo1.png
heroText: Data Guide
tagline: 技术文档
actionText: 快速上手 →
actionLink: /data-guide-book/01-getting-started/01-config-env

footer: Copyright © 2021-present 某某人
---

1. heroImage可以引用images下的图片资源
2. actionLink为点击快速上手后跳转到的那篇文章

3、配置

新建几篇测试文章

修改 config.js 中的配置如下：

module.exports = {
  title: '技术文档',
  themeConfig: {
  	// 导航栏logo
    logo: '/assets/images/logo1.png',
    // 导航栏链接
    nav: [
            {text: '测试01', link: 'https://www.baidu.com/'},
            {text: '测试02', link: 'https://www.baidu.com/'},
            {text: '测试03', link: 'https://www.baidu.com/'},
            {text: '测试04', link: 'https://www.baidu.com/'},
        ],
    // 侧边栏
    sidebar: [
      {
        title: '主目录1',   // 必要的
        collapsable: false, // 让一个组永远都是展开状态
        children: [
          ['/data-guide-book/01/01', '文章1'],
          ['/data-guide-book/01/02', '文章2']
        ]
      },
      {
        title: '主目录2',
        collapsable: false, 
        children: [
          ['/data-guide-book/02/01', '文章3']
        ]
      },
      {
        title: '主目录3',
        collapsable: false, // 让一个组永远都是展开状态
        children: [
          ['/data-guide-book/03/01', '二级目录'],


          {
            title: '常见问题2',
            path: '/data-guide-book/03/02',
            collapsable: true,
            children: [
                 ['/data-guide-book/03/02', '文章4'],
                 ['/data-guide-book/03/03', '文章5'],
                 ['/data-guide-book/03/04', '文章6'],
                 ['/data-guide-book/03/05', '文章7']
            ]
          }
        ]
      }
    ],
    sidebarDepth: 2,
    editLinks: true,
    lastUpdated: '最后修改于',
    search: true
  }
}

效果如下图所示：

子目录的使用、目录的对应关系不再赘述，把上面的配置粘到本地自己修改后查看页面变化，试几次就清楚各部分的作用了。

由于文档部署在内网，暂时还没有公网的部署经验可以分享，可以参考官方文档