使用VuePress制作技术文档

VuePress的官网：https://www.vuepress.cn/

VuePress开发指南：https://www.vuepress.cn/guide/getting-started.html

VuePress使用MarkDown语法来标记文本，基于npm运行，所以我们先要安装npm！

一、安装npm
npm，全名 node package manger。简单理解就是包管理器，用于下载、安装等的一个工具。
打开cmd,输出 npm help，如果有安装，会提示帮助信息

如果没有安装，请先安装nodejs，npm会随着一并安装。
打开官网https://nodejs.org/en/download/，根据自己的系统下载对应的文件。

安装完成后，打开cmd，输入以下命令查看是否成功。

输入以下命令升级npm到最新版本

npm install npm@latest -g

这时发现已经升级到了8.19.2

二、安装vuepress

为项目创建一个文件夹，比如命名为vuepress，我们可以从网上下载一些现成的模板，这样就不用自己一步步去配置了。

打开cmd，cd到目录vuepress，执行以下命令安装vuepress

npm install -D vuepress

注意，官方已不建议使用全局依赖，所以我们这里使用本地依赖。这样node_modules会安装到项目文件夹中。node_modules包括编译器等文件！

我们的模板主要是在doc文件夹下，结构如下：

而在.vuepress目录下，还有三个配置文件，分别是config.js 、nav.js、sidebar.js

1、config.js

全局配置文件，可以配置网站标题、LOGO图标、风格样式等

// 具体配置文档: https://vuepress.vuejs.org/zh/guide/

module.exports = {

    title: 'CTT在线文档',
    //description: '这是简短描述...',
    dest: './dist',

    // LOGO大图配置
    head: [
        ['link', {rel: 'icon', href: '/logo.jpg'}]
    ],

    markdown: {
        lineNumbers: true
    },

    themeConfig: {

        // 右上角导航菜单
        nav: require('./nav'),

        // 文档侧边栏
        sidebar: require('./sidebar'),

        // 侧边栏展开下潜深度
        sidebarDepth: 2,
		
		// 记录编辑/更新修改时间
		// 需要传到git仓库(vuepress才能获取并显示)
        lastUpdated: 'Last Updated',
        searchMaxSuggestoins: 10,
        serviceWorker: {
            updatePopup: {
                message: "有新的内容.",
                buttonText: '更新'
            }
        },
        editLinks: true,
        editLinkText: '在 GitHub 上编辑此页 ！'
    }
}

2、nav.js

菜单配置，右上角的菜单，并不包括左侧边栏导航。

module.exports = [
    {
        text: 'MES', link: '/mes/'
    },
    {
        text: 'WMS', link: '/wms/'
    },
    {
        text: 'MCC', link: '/mcc/'
    },
    {
        text: '云看板', link: '/kanban/'
    },
    {
        text: '工具箱',
        items: [
			{
                text: 'ERP同步程序',link:'/tools/erpsync/'
            },
			{
                text: 'MCF解析程序',link:'/tools/mcf/'
            },
			{
                text: '自动开工程序',link:'/tools/autowork/'
            },
            {
                text: '应用守护程序',link:'/tools/taskcaptain/'
            },
            {
                text: '运维小工具',link:'/tools/cttools/'
            }
        ]
    },
    {
        text: 'MES演示', link: 'https://192.168.0.145'
    },
]

3、sidebar.js

左侧边栏导航配置

module.exports = {	
	// 普通菜单-管控
	'/mes/': require('../mes/sidebar'),
	'/wms/': require('../wms/sidebar'),
	'/mcc/': require('../mcc/sidebar'),
	'/kanban/': require('../kanban/sidebar'),

	// 多级菜单-管控
	'/tools/erpsync/': require('../tools/erpsync/sidebar'),
	'/tools/mcf/': require('../tools/mcf/sidebar'),
	'/tools/autowork/': require('../tools/autowork/sidebar'),
	'/tools/taskcaptain/': require('../tools/taskcaptain/sidebar'),
	'/tools/cttools/': require('../tools/cttools/sidebar')

	// ...
}

看到require表示相应的栏目下面要有对应的sidebar.js文件

配置完成后，执行以下命令运行网站

npm run dev

那么这个dev配置在哪呢？在模板根目录下有个文件package.json，如

{
  "name": "my_vuepress",
  "version": "1.0.0",
  "description": "",
  "main": "index.js",
  "scripts": {
    "dev": "vuepress dev docs",
    "build": "vuepress build docs"
  },
  "author": "zhiguo.Hong",
  "license": "ISC",
  "devDependencies": {
    "@vuepress/theme-blog": "^2.3.3",
    "core-js": "^3.8.1",
    "vuepress": "^1.7.1"
  },
  "dependencies": {
    "animate.css": "^4.1.1",
    "element-ui": "^2.14.1"
  }
}

运行成功后，显示服务侦听在 http://localhost:8080/，打开这个网址就能看到效果了

当发布到正式网址时，可以生成html，执行以下命令即可

npm run build

然后会在模板根目录下创建一个dist目录，网址指向即可！

参考：https://zhuanlan.zhihu.com/p/393344955

使用VuePress制作技术文档

发表评论