快速搭建一个类似vue文档风格的vuepress技术项目

发布于 2021-01-06  930 次阅读 本文共2772个字


前边想整理下文档,结果发现没有好用且免费支持md的软件,感觉 Vue官网 的风格还不错,简单明了,那就自己也搭建一个咯。

如果你也想搭建一个类似这样的网站,可以使用 VuePress ,高效快捷,写文档简直不要太爽。

特点:

官网 介绍:

  • 简洁至上
  • Vue 驱动
  • 高性能

使用总结:

  • 内置Markdown拓展
  • 在Markdown中可以使用vue
  • 自动生成service worker
  • 响应式
  • 包含默认主题也可自定义
  • 支持多种插件

快速上手

直接根据官网安装步骤依次操作即可,注意点是Nodejs版本需 >= 8.6

创建本地目录并进入

mkdir <file name> && cd <file name>

初始化

// 使用 npm 、 yarn 、 cnpm 都可
npm init 

安装本地依赖

// 使用 npm 、 yarn 、 cnpm 都可
npm yarn add -D vuepress

官网不推荐全局安装,其实都可以,根据自己喜好即可

创建文档根目录

mkdir docs

在docs下创建 .vupress 文件夹

所有vuepress相关的文件都会放在这里

在 .vuepress 下创建配置文件

touch config.js

config.js 是VuePress项目必要的配置文件,会导出一个对象。

在初始化生成的package.json文件补充scripts

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

官网的 docs:dev 和 docs:build 命令太麻烦,直接简写成dev和build即可,你也可以根据自己喜好命名。

启动服务

npm run dev

然后打开 http://localhost:8080/ 即可预览。

构建

npm run build

build后会在 .vuepress 下生成一个dist文件,里边则是打包好生成的HTML静态文件。

文件的目录结构可以参考 VuePress推荐目录结构

网站配置

像刚才提到config.js文件,网站的配置都在这里,详细配置参考文档API,这里列举常用的。

title和描述

module.exports = {
  title: '萤火之森',
  description: '这里是高佳睿的学习空间'
}

网站logo

module.exports = {
  themeConfig: {
    logo: 'xxxxxx' // 可以引用本地静态文件,也可以使用外部链接
  }
}

导航栏配置

module.exports = {
  themeConfig: {
    nav: [
      // 首页, / 代表docs下的README.md或index.md
      { text: 'home', link: '/' },
      // 直接路径, /web/ 代表 docs下的web下的README.md或index.md
      { text: 'web', link: '/web/'},
      // 下拉列表
      { 
         text: 'language', 
         items: [
            { text: '中文', link: '/language/zh.md' }
            { text: '英文', link: '/language/en.md' }
         ]
      },
      // 外部链接
      { text: '萤火之森', link: 'https://www.scar.vip' }
    ]
  }
}

link中的路径,如/web/,后边没有跟具体的文件名,代表访问的是默认文件,默认文件命名通常为README.md 或 index.md 。若想链接某个具体的文件的话,直接写全路径就好,如/language/zh.md,也可省略.md拓展名。

第一个 / 都代表的是docs文件。

侧边栏配置

sidebar支持数组和对象,简单配置直接像官网似的直接在数组中添加页面路由即可

module.exports = {
  themeConfig: {
    sidebar: [
      '/',
      '/page-a',
      ['/page-b', 'Explicit link text']
    ]
  }
}

我们用到的多个侧边栏和分组侧边栏会可能会多点,下边举例,并在备注里边详细说明

多个侧边栏

多个侧边栏会跟文档对应的目录有关

module.exports = {
  themeConfig: {
    sidebar: {
      // 在docs文件夹下的web文件夹下的md文档(和导航栏上web对应)
      '/web/': [
        'http', // docs文件夹下的web文件夹下的http.md 文件,
         // 层叠标题
        {
          title: '框架', // 侧标栏层叠标题的名称
          children: [
             'vue', // 直接这样写找的是docs文件夹下的web文件夹下的vue.md文件
             '/react/test' // 这样写找的是docs文件夹下的react文件夹下的test.md 文件
          ]
        }
      ]
    }
  }
}

分组侧边栏

module.exports = {
  themeConfig: {
    sidebar: [
      {
        title: 'group1', 侧边栏分组标题为group1
        children: [
          '/web/http' // group1下的文档,路径为docs文件夹下的web文件夹下的http.md文件
        ]
      }
    ]
  }
}

侧边栏其他配置

深度展示slidebar 2是最大值,展示到h3, 默认展示h2,可以配置在最外层,也可以在分组或多个侧边栏具体选项里具体配置

sidebarDepth: 0

自动生成侧栏

sidebar: 'auto'

禁用侧边栏

sidebar: false

搜索配置

直接参照官方文档即可,很简单。

主题修改

默认样式修改

在.vuepress文件夹下创建一个styles文件夹,并创建palette.styl文件

$accentColor =blue //默认主题颜色
$textColor = red //默认字体颜色
$borderColor = rgb(255, 255, 0) //默认边框颜色
$codeBgColor = #ccc //默认背景颜色

修改某个具体的样式直接根据css样式去写就可以了,如:

div > .test {
  color: pink
}

#title {
  font-size: 20px;
}

自定义页面修改

在具体的md文件中声明页面class,如:

---
pageClass: page-class-test
---

具体修改方法直接和上边一样,直接写写对应class下的css即可。

Markdown拓展

对于Markdown的支持还是比较全面的,里边还支持Emoji等,直接参考官方Markdown文档即可。

支持多语言

多语言支持首先你需要准备对应语言的文档,参考官方多语言配置文档。

部署

官方介绍了好几种部署方案。我的呢是直接部署到服务器的,这里就直接介绍这一种,其余的可多方参考。

写好服务器的nginx的server配置后,然后我们执行 npm run build命令后,会在.vuepress 文件夹下生成一个dist文件,直接把这个dist文件部署到服务器对应的地方(具体的文件地址和你nginx 相关server里的root对应好即可),然后打开你的网站就可以看到。

还有很多需要具体补充的点,后续完善...


努力,只为遇见更好的自己!