VuePress 搭建文档中心

158 阅读3分钟

在我准备搭建这个站点的时候,VuePress 2.x 还在 beta 中,VitePress 也有少量应用,考虑到我想快速搭建一个站点,由于 VitePress 不兼容当前的 VuePress 生态,所以我就选择了 VuePress,至于为什么没有选择 beta 测试版,是因为很多生态中的主题和插件还没有升级,于是我就用了最为稳定的 VuePress 1.x,所以这个系列文章也是基于 VuePress 1.x 写的,像个别函数名和使用方式,到了 VuePress 2.x 中就变了,如果是使用 VuePress 2.x 的同学请千万注意。

建议先看一下官方文档

VuePress特性:一个字快,俩字很快,仨字快快快;避免了二次开发的繁琐工作

搭建

新建文件夹

mkdir project

进入项目后,初始化 npm 包

npm init

将会创建一个package.json文件,长这样子:

{
  "name": "",
  "version": "0.0.0",
  "description": "",
  "main": "index.js",
  "scripts": {
    "test": "echo \"Error: no test specified\" && exit 1"
  },
  "keywords": [],
  "author": "",
  "license": "ISC"
}

进行安装 vuepress

npm install -D vuepress

创建 doc 入口资源文件

mkdir docs

创建README.md,随便加点md文档内容,先跑起来看看效果。

在 package.json,script中添加两条命令

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

在本地启动服务器

npm run docs:dev
//下面没有文件类型后缀的都是文件夹
//部分内容并不是必须的,想自己定制的话可以参考官方文档。这里是按照我的思路写的。
├─docs
│  ├─.vuepress  //存放核心内容的文件夹
│  │ │ ├─components  //存放你需要添加的vue组件
│  │ │ └─public  //存放静态文件,如图片等
│  │ ├─styles  //存放需要定制的样式
│  │ │ └─palette.styl  //配置页面主题颜色的文件
│  │ └─config.js   //设定顶部导航栏、侧边导航栏等项目配置的核心文件
│  ├─ pages   //存放markdown文件,用于设置其他页面内容
│  └README.md   //首页展示用的markdown文件

其中这几个文件较为重要 .vuepress/config.js.vuepress/publicREADME.md

到这里基本完成了项目的启动以及搭建,聊一聊基础的配置,直接上配置

module.exports = {
  title: '网站标题',
  description: '网站描述',
  // 注入到当前页面的 HTML <head> 中的标签
  head: [
    // 增加一个自定义的 favicon(网页标签的图标)
    ['link', { rel: 'icon', href: '/favicon.ico' }],
  ],
  markdown: {
    lineNumbers: true // 代码块显示行号
  },
  themeConfig: {
    sidebarDepth: 2, // e'b将同时提取markdown中h2 和 h3 标题,显示在侧边栏上。
    lastUpdated: 'Last Updated' // 文档更新时间:每个文件git最后提交的时间
  }
};

导航配置

导航栏 导航配置文件在.vuepress/config.js

image.png

直接看代码,还是.vuepress/config.js这个地方

module.exports = {
  themeConfig: {
    nav:[
      { text: '前端算法', link: '/algorithm/' }, // 内部链接 以docs为根目录
      { text: '博客', link: 'http://obkoro1.com/' }, // 外部链接
      // 下拉列表
      {
        text: 'GitHub',
        items: [
          { text: 'GitHub地址', link: 'https://github.com/OBKoro1' },
          {
            text: '算法仓库',
            link: 'https://github.com/OBKoro1/Brush_algorithm'
          }
        ]
      }        
    ]
  }
}

侧边栏

侧边栏的配置相对麻烦点,只能看自己造化了。侧边栏

// .vuepress/config.js
module.exports = {
  themeConfig: {
    sidebar: [
      {
        title: 'Group 1',   // 必要的
        path: '/foo/',      // 可选的, 标题的跳转链接,应为绝对路径且必须存在
        collapsable: false, // 可选的, 默认值是 true,
        sidebarDepth: 1,    // 可选的, 默认值是 1
        children: [
          '/'
        ]
      },
      {
        title: 'Group 2',
        children: [ /* ... */ ],
        initialOpenGroupIndex: -1 // 可选的, 默认值是 0
      }
    ]
  }
}

完结

还有许多拓展功能

祝福每一个热爱生活的你