【抽五分钟】使用VuePress创建在线文档中心

 

内容目录

安装初始化核心配置导航栏配置侧边栏配置静态资源配置nginx部署typora编写

安装初始化

  • 全局安装
 npm install -g vuepress
  • 创建目录
mkdir vurepress-blog
  • 项目初始化,初始化完成生成package.json文件
cd vurepress-blog npm init -y

  • 在当前目录中创建docs目录,存放博客书籍内容
mkdir docs
  • 配置首页显示(以下为默认配置)docs下创建README.md
---
home: true
heroImage: /img/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 You
--- 

核心配置

  • 在docs目录下创建.vuepress目录
cd docs mkdir .vuepress
  • 创建配置文件config.js,整个项目的核心配置文件,所有菜单、栏目相关的配置均配置在该模块中
touch config.js
  • 在config.js中加入内容
module.exports = {
    title'文档CMS',
    description'文档管理中心',
    dest'./dist',
    port'7777',
    head: [
        ['link', {rel'icon'href'/logo.jpg'}]
    ],
    markdown: {
        lineNumberstrue
    },
    themeConfig: {
        nav: [{
            text'小新指南'link'/guide/'
        }],
        sidebar: {'/guide/':[
            {
                  title:'新手指南',
                  collapsabletrue,
                  children:[
                    '/guide/notes/one',
                  ]
                },
                {
                  title:'文档CMS',
                  collapsabletrue,
                  children:[
                    '/guide/notes/two',
                  ]
                }
            ]
        },
        sidebarDepth2,
        lastUpdated'Last Updated',
        searchMaxSuggestoins10,
        serviceWorker: {
            updatePopup: {
                message"有新的内容.",
                buttonText'更新'
            }
        },
        editLinkstrue,
        editLinkText'在 GitHub 上编辑此页 !'
    }
}
  • vurepress-blog目录下直接运行调试
vuepress dev docs

导航栏配置

  • nav顶部导航栏配置

config.js中的themeConfig配置项nav单独拿出来配置

touch nav.js
  • 编辑nav.js
module.exports = [
    {
        text'小新指南'link'/guide/'
    },
    {
        text'开发技巧'link'/dev/',
        items: [
            {text'初级篇'link'/dev/zero/'},
            {text'进阶篇'link'/dev/high/'},
        ]
    },
    {
        text'工具箱',
        items: [
            {
                text'在线编辑',
                items: [
                    {text'图片压缩'link'//tinypng.com/'}
                ]
            },
            {
                text'在线服务',
                items: [
                    {text'阿里云'link'//www.aliyun.com/'},
                    {text'腾讯云'link'//cloud.tencent.com/'}
                ]
            },
            {
                text'博客指南',
                items: [
                    {text'掘金'link'//juejin.im/'},
                    {text'CSDN'link'//blog.csdn.net/'}
                ]
            }
        ]
    }
]
  • 修改config.js中nav链接
themeConfig: {     
      navrequire("./nav.js"),
      ...
}
  • 重新启动下看下效果

侧边栏配置

sidebar是左侧标题导航,可以指定配置也可以设置为auto

  • 主侧边栏配置,在.vuepress目录下,sidebar.js,分发指向不同的栏目侧边栏js
module.exports = {
    '/guide/'require('../guide/sidebar'),
    '/dev/zero'require('../dev/zero/sidebar'),
    '/dev/high'require('../dev/high/sidebar'),
}
  • config.js中sidebar配置
sidebar: require("./sidebar.js")
  • 以为小新指南模块为例,/docs/guide/sidebar.js文件内容
module.exports = [
        {
          title:'小新指南',
          collapsabletrue,
          children:[
            '/guide/notes/one',//指向md文档
          ]
        },
        {
          title:'进阶',
          collapsabletrue,
          children:[
            '/guide/notes/two',
          ]
        }
    ]
  • guide/notes/one two就是具体的md文档,编写one.md
# 一级标题 
## 二级标题 
### 三级标题 
#### 四级标题
  • 呈现效果

静态资源配置

  • vuepress目录下public目录,vuepress程序默认的图片目录是/docs/.vuepress/public

    —.vuepress

    ——public

    ———css

    ————styles.css

    ———img

    ————logo.jpg

  • 在config.js中引入

head: [
        ['link', {rel'icon'href'/img/logo.jpg'}],
        ['link', {rel'stylesheet'href'/css/style.css'}],
        ['script', {chartset'utf-8'src'/js/main.js'}]
],

nginx部署

  • 编译,默认输出到dist目录
vuepress build docs
  • 配置nginx的首页(可选)
location / 
{         
    root  home/docs;      
    index index.html index.htm;    
}
  • 将打包后项目拷贝到nginx的root配置下
  • 启动nginx
  • 其他部署,直接扔在自己的站点下。比如做项目时开发软件系统的帮助文档

typora编写

平常使用typora编写Markdown文档较多,编写后如何部署到vuepress中。

  1. 文件-偏好设置,设置图片的相对路径

  1. 文档编写完成后,md文档连同图片文件夹拷贝到vuepress需要显示的位置。如果想要在首页显示,直接放在README.MD处,名称替换为README
  2. 调试运行会有问题,不能会正常编译,参考//www.it610.com/article/1297823992387805184.htm
  3. 安装一下包,用于处理图片路径问题
npm i markdown-it-disable-url-encode
npm i mdurl
  1. 注入到vuepress配置文件中,.vuepress/config.js
module.exports = {
  // .....
  markdown: {
    // ......
    extendMarkdown: md => {
      md.use(require("markdown-it-disable-url-encode"));
    }
  }
};

然后可以正常编译调试打包。