VuePress食用说明

LUNARTIC
1,733 阅读6分钟

最初缘于在搭建公司官网时有搭建成熟的文档集的需求,在多方查阅之后对vuepress兴趣颇深,遂尝试了自己搭建一个demo,但官网的说明个人觉得有些零(wo)散(tai)细(cai)碎(le),故希望能够以自己的逻辑,把搭建的过程记录下来,便于其他同学查阅.

安装

我们的目的是搭建一个可维护文档的项目,所以需要把VuePress安装为本地依赖,我们可以在一个基础的VUE-CLI模板项目中进行安装,也可以在空文件夹中进行项目初始化后安装.(VuePress的项目结构与一般的Vue项目结构不同,一般vue项目的相关文件不会被VuePress打包)

npm install -D vuepress

框架搭建&相关配置

项目框架搭建

在完成VuePress的安装之后我们需要创建一个docs文件夹,这个文件夹便是VuePress项目的主体,主要包含了两部分,VuePressde的配置文件以及文档文件.

同时我们需要在docs下创建一个vuepress文件夹放置具体的配置文件config.js.

.
├─ docs
│  ├─ README.md  // 默认主题配置
│  └─ .vuepress  // 项目配置文件夹
│  │   └─ config.js  //配置文件
│  └─ .docmkdir1  //文档文件夹1
│  └─ .docmkdir2  //文档文件夹2
│  └─ ...         //文档文件夹n
└─ package.json

配置文件创建

在基本配置文件中我们需要导出一个JS对象并先进行初始化设置.

module.exports = {
  title: 'Hello VuePress',  //标题
  description: 'Just playing around'  //描述
}

同时我们在docs文件夹中创建README.MD来进行默认主题信息的配置.

---
home: true
heroImage: /hero.png //你肯定没有这张图
actionText: 起步 →   //按钮
actionLink: /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
---

把配置信息复制到README.MD中即可,相关资源和路由需要后来的设置.(菜鸡的我并不知道yaml,在复制的时候首行为空行导致设置没生效,找了半天设置问题 = =如果格式正确应该编译器会对其进行着色)

执行脚本添加

我们可以在package.json中设置VuePress的执行脚本:

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

为了方便也可以这样

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

如果使用的是VUE-CLI记得删除原有同名的执行脚本.

接下来我们执行npm run dev就可以启动项目了

主题配置

导航栏配置

顶部导航栏是一个以text(显示名称,任意编辑),link(文件路径)为元信息的对象数组,支持多层嵌套.我们需要在**.vuepress中的config.js中创建主题配置对象themeConfig**,同时创建导航栏对象数组nav,具体如下:

  1. 无下拉菜单

    // .vuepress/config.js
module.exports = {
  themeConfig: {
    nav: [
      { text: 'Home', link: '/' },
      { text: 'Guide', link: '/guide/' },  //即/docs/guide
      { text: 'External', link: 'https://google.com' },  //支持域名链接
    ]
  }
}

  2. 一级下拉菜单

    module.exports = {
  themeConfig: {
    nav: [
      {
        text: 'Languages',
        items: [
          { text: 'Chinese', link: '/language/chinese' },
          { text: 'Japanese', link: '/language/japanese' }
        ]
      }
    ]
  }
}

  3. 二级下拉菜单

    module.exports = {
  themeConfig: {
    nav: [
      {
        text: 'Languages',
        items: [
          { text: 'Group1', items: [/*  */] },
          { text: 'Group2', items: [/*  */] }
        ]
      }
    ]
  }
}

侧边栏配置

友情 ♂ 提示 : 侧边栏配置坑还是挺多的,因为其比较严格稍有不慎就会导致侧边栏消失,而且配置文件产生的侧边栏和导航栏并不会热刷新(做了变更没效果真的崩溃,后来发现没有热刷新!!!)加上官方文档这里确实不(shi)够(wo)详(tai)细(cai). 如果这个部分出现问题的话需要多尝试下官方提供的两个例子鼓捣一下,稍加思考就理清楚了.这个部分确实很容易让人疑惑.

官方举例了两种配置方式:

  1. 分组侧边栏

    // .vuepress/config.js
module.exports = {
  themeConfig: {
    sidebar: [
      {
        title: 'Group 1',  //标题
        collapsable: false,  //是否可以折叠,false则直接展开
        children: [  //分组下所有页面
          '/'
        ]
      },
      {
        title: 'Group 2',
        children: [ /* ... */ ]
      }
    ]
  }
}

    我们可以看到这是一个由对象组成的数组,每个对象都是一个分组,元信息具体如注释所示.

  2. 多个侧边栏

    // .vuepress/config.js
module.exports = {
  themeConfig: {
    sidebar: {
      '/foo/': [
        '',     /* /foo/ */
        'one',  /* /foo/one.html */
        'two'   /* /foo/two.html */
      ],

      '/bar/': [
        '',      /* /bar/ */
        'three', /* /bar/three.html */
        'four'   /* /bar/four.html */
      ],

      // 回退(fallback)侧边栏配置
      '/': [
        '',        /* / */
        'contact', /* /contact.html */
        'about'    /* /about.html */
      ]
    }
  }
}

    所谓多个侧边栏就是每个目录下文件都会单独渲染一个侧边栏.侧边栏对象里根据文件夹为不同文件夹内文件生成单独的侧边栏.文件夹路径是数组名,数组里是其他文件的路径.这个时候侧边栏会读取文件里的第一个标题作为侧边栏内显示的标题.

那么当我们想要生成多个分组的侧边栏要怎么办呢,根据著名的PPAP定理,I have a Single , I have a Group, ahh~ SingleGroup !!!我们只需要把构成分组的对象放进多个侧边栏里就好了,不明白也没关系,直接上代码:

  1. 多个分组侧边栏

    // .vuepress/config.js
module.exports = {
    themeConfig: {
        sidebar: {
            '/doc1/': [  //为doc1生成单独的侧边栏
                {
                    title: 'Group 1',  //doc1中的第一个分组
                    collapsable: false,  //是否可以折叠,false则直接展开
                    children: [  //分组下所有页面
                        '/group1/one',
                        '/group1/two'
                        '/group1/thr'
                    ]
                },
                {
                    title: 'Group 2',  //doc1中的第二个分组
                    collapsable: false,  //是否可以折叠,false则直接展开
                    children: [  //分组下所有页面
                        '/group2/one',
                        '/group2/two'
                        '/group2/thr'
                    ]
                },
            ],
        }
    }
}

    于是我们可以得到仅显示doc1文件夹下文件,并对文件进行分组的侧边栏.

部署

部署是另外一个会让人费解的地方,如果不了解git和linux就会走进死胡同.具体流程大概是在建立好项目仓库之后将打包好的文件进行部署.具体流程也可以参照官方文档中的自动化部署指南,我这里部署到了Github:

我们在项目根目录里创建一个deploy.sh 的shell脚本,需要在IDE中对终端的打开方式进行设置,才能通过bash+文件名的形式执行该脚本.

#!/usr/bin/env sh

# 终止一个错误
set -e

# 构建
npm run build //我在package.json中是这么定义的,具体以你的配置为准

# 进入生成的构建文件夹
cd docs/.vuepress/dist

# 如果你是要部署到自定义域名
# echo 'www.example.com' > CNAME

git init
git add -A
git commit -m 'deploy'

# 如果你想要部署到 https://<USERNAME>.github.io
# git push -f git@github.com:<USERNAME>/<USERNAME>.github.io.git master

# 如果你想要部署到 https://LLLUNARTIC.github.io/l_B
git push -f git@github.com:LLLUNARTIC/l_B.git master:gh-pages

cd -

我这里部署到了指定项目所以需要在配置文件中指定基路由

module.exports = {
  base: '/base/'
}

同时我们在package.json中增加一条执行脚本--deploy

{
  "scripts": {
    "deploy": "bash deploy.sh"
  }
}

我们就可以通过 npm run deploy 执行该脚本进行部署.

在这里我只是进行一些补充说明,希望能够帮助大家顺利快速的把demo搭建出来,避免不必要的时间成本,其他的集体设置和方法还请参阅 官方文档

avatar
文章
阅读
粉丝