利用VuePress搭建在线文档系统

Java Miraculous 2021-07-21

3000

最近应部门要求搭建一个在线文档系统，由于之前没太了解过，网上冲浪之后发现一个好东西：VuePress。VuePress是一个纯前端的静态网站，想深入了解的可以看下官网：https://vuepress.vuejs.org/zh/，这里就不详细说了，因为作为一个后端对vue的了解并不多。不过问题不大，本文将带你一步一步的搭建一个静态在线文档系统。

一、安装node环境

1.1、下载node

下载地址：https://nodejs.org/download/release/

注：本文基于版本：v12.0.0

注：这是前置条件，而且node版本必须>=8.6

1.2、安装node

上传：rz -e

解压：tar -zxvf node-v12.0.0-linux-x64.tar.gz

建立软链接：

ln -s usr/local/node-v12.0.0-linux-x64/bin/node usr/bin/node

ln -s usr/local/node-v12.0.0-linux-x64/bin/npm usr/bin/npm

检查是否安装成功：

node -v

npm -v

二、开始搭建在线文档系统

执行：

mkdir arch-doc

cd arch-doc

2.2、用包管理器进行初始化

执行：

npm init

2.3、将 VuePress 安装为本地依赖

执行：

npm install -D vuepress

注：此过程较漫长

2.4、安装评论插件

执行：

npm install --save vuepress-plugin-comment

评论功能是基于第三方的leanCloud，需要注册，网址：https://console.leancloud.cn/login，注册完成后在设置里可以看到应用凭证。

2.5、建立相关文件夹

注：idea或者VScode等其它编辑器均可，这里以idea为例

2.5.1、在桌面上建立一个文件夹

注：名字无要求，这里以arch-doc为例

2.5.2、用idea打开arch-doc
2.5.3、在arch-doc下建立docs文件夹

注：名字必须为docs

2.5.4、在docs文件夹下建立.vuepress文件夹

2.5.5、在.vuepress文件夹下建立config.js文件

module.exports = {
  title: '架构部',
  description: '引导业务开发团队，提出新的技术方案',
  dest: './dist',
  base: '/',
  port: 80,
  head: [
    ['link', { rel: 'icon', href: '/favicon.ico' }],
  ],
  markdown: {
    lineNumbers: true
  },
  plugins: [
  [
      'vuepress-plugin-comment',
      {
         choosen: 'valine',
          options选项中的所有参数，会传给Valine的配置
         options: {
             el: '#valine-vuepress-comment',
             appId: '你的appId',
             appKey: '你的appKey'
          }
      }
    ]
  ],
  themeConfig: {
    displayAllHeaders: true,
    repoLabel: '',
    lastUpdated: 'Last Updated',
    sidebar:[
        {
            title: 'redis',
            children: [
                ['/redis/accessNotes', '接入说明'],
                ['/redis/resources', '相关资源']
            ]
        },
        {
            title: 'apollo(阿波罗)',
            children: [
                ['/apollo/recommendations', '使用建议'],
                ['/apollo/basicConcept', '基本概念'],
                ['/apollo/environment', '环境说明'],
                ['/apollo/accessInstructions', '接入说明']
            ]
        }
    ],
    serviceWorker: {
      updatePopup: true
    },
    nav:[
      { text: '首页', link: '/' }
    ]
  }
};

注：config.js里的base一定要配置成/，不然后续往nginx上部署会出现各种操蛋的问题。

2.5.6、在docs文件夹下添加README.md文件文件作为首页

2.6、编写文档文件

注：推荐markdown文件，比较适合后端同学，毕竟写html和css对于后端来说有点难受。

这里咱简单写几个页面，关于markdown文件的格式，网上一搜一大堆，这里推荐一个：https://www.jianshu.com/p/7b1f94d7b5a6

2.7、将上面的docs文件夹上传到linux

2.8、解压

三、运行及部署

3.1、添加执行脚本

执行:

vi package.json

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

3.1、本地启动

执行：

npm run docs:dev

注：访问之前确保服务器已经关闭防火墙或者开放指定端口

3.2、部署到nginx

上面本地把服务跑起来了，但是不够稳定，ctrl+c或者其它不明原因都可能会使服务挂掉，那怎么办呢？我们将其生成静态文件即可，这样就不用起服务了。

执行：

npm run docs:build

nginx配置（nginx的安装就不说了，回头写篇文章都介绍下）：

注：配置完后别忘了reload

本地配置host：

访问：www.arch.com

最后：

河南加油，郑州加油！

数据库

文章转载自Java Miraculous，如果涉嫌侵权，请发送邮件至：contact@modb.pro进行举报，并提供相关证据，一经查实，墨天轮将立刻删除相关内容。