之前有很多敌人问我，我的开源我的项目文档网站是用什么搭建的。其实是用Docsify搭建的，具体能够参考如何写出优雅的开源我的项目文档 。Docsify用来搭建成体系的文档网站根本够用了，但有时候咱们既有成体系的文章、又有碎片化的文章，如果把文章都挂上去，看起来未免有些凌乱，这时候咱们可能须要搭建一个相似知识库的网站了。最近发现应用VuePress能够搭建一个功能强大的文档网站，举荐给大家！

SpringBoot实战电商我的项目mall（50k+star）地址：https://github.com/macrozheng/mall

VuePress简介

VuePress是Vue驱动的动态网站生成器。比照咱们的Docsify动静生成网站，对SEO更加敌对。

应用VuePress具备如下长处：

  • 应用Markdown来写文章，程序员写起来棘手，配置网站十分简洁。
  • 咱们能够在Markdown中应用Vue组件，如果你相熟Vue的话会十分不便。
  • 打包网站时会为每个页面预渲染生成动态的HTML，性能好，也有利于SEO。

Vdoing主题

个别咱们应用VuePress搭建网站的时候，都会抉择一个主题。这里抉择的是vuepress-theme-vdoing，一款简洁高效的常识治理&博客主题，用来搭建文档网站入不敷出。

学了技术老忘怎么破？用Vdoing搭建一个知识库试试！它能帮忙咱们更好地治理常识，并可能疾速地把忘记的知识点找回来。

应用Vdoing主题具备如下长处：

  • 常识治理：因为该主题具备目录、分类、标签等性能，能够不便地整合结构化或碎片化的内容。
  • 简洁高效：以 Markdown 为核心的我的项目构造，内置自动化工具，以更少的配置实现更多的事。
  • 沉迷式浏览：专为浏览设计的UI，配合多种色彩模式、可敞开的侧边栏和导航栏，带给你一种沉迷式浏览体验。

成果演示

咱们先来看下成品成果，有三种不同模式可供选择，是不是够炫酷！

搭建

通过Vdoing搭建网站非常简单，就算你对Vue不相熟也没关系。
  • 首先咱们须要去Vdoing的官网下载我的项目，下载地址：https://github.com/xugaoyi/vu...

  • 下载实现后导入IDEA中，因为是Vue我的项目，导入胜利后须要应用如下命令来装置依赖，之后以dev模式运行；
# 装置npm install# 运行npm run dev
  • 运行胜利后，轻易找个文章进去体验下，界面还是挺不错的，拜访地址：http://localhost:8080/

  • 还反对主题切换，比方切换到深色模式。

配置

因为Vdoing自身就是个残缺的网站了，外面有很多咱们不须要的文章和配置，所以咱们得替换这些文章并自定义这些配置。
  • 咱们先来看下我自定义后的首页成果，这个主题还是十分简洁的，看起来挺舒服；

  • 我的项目文件根本都在docs目录下，咱们来看下这些文件的作用；
docs│  index.md -- 首页配置├─.vuepress -- 用于寄存全局的配置、组件、动态资源等│  │  config.js -- 配置文件的入口文件│  │  enhanceApp.js -- 客户端利用的加强│  ├─config│  │      head.js -- 注入到页面<head>中的配置│  │      htmlModules.js -- 插入自定义html模块│  │      nav.js -- 顶部导航栏配置│  │      plugins.js -- 插件配置│  │      themeConfig.js -- 主题配置   │  ├─public -- 动态资源目录│  │  └─img -- 用于寄存图片│  ├─styles│  │       palette.styl -- 主题演示配置│  └─<结构化目录>├─@pages --主动生成的文件夹│      archivesPage.md -- 归档页│      categoriesPage.md -- 分类页│      tagsPage.md -- 标签页├─images -- 能够用来寄存本人的图片└─_posts -- 专门寄存碎片化博客文章的文件夹，不会主动生成目录
  • 大家都用过SpringBoot，有约定优于配置的说法，Vdoing也有这种说法，如果咱们想要依据目录构造主动生成文章目录的话，须要给目录和文件增加序号，比方上面的目录；

  • 在此目录构造下，一级目录被称为专栏，二级目录为专栏内容，专栏之间是互相独立的，下面的目录构造将生成如下构造的侧边栏，同时也会生成右侧的纲要栏；

  • 如果你还想给专栏增加个目录页的话，能够在00.目录页文件夹中增加02.mall学习教程.md作为目录，目录页内容如下，permalink能够指定目录页的永恒门路；
---pageComponent:   name: Catalogue  data:     key: 02.mall学习教程    imgUrl: /img/ui.png    description: mall学习教程，架构、业务、技术要点全方位解析。title: mall学习教程date: 2020-03-11 21:50:54permalink: /mall-learningsidebar: falsearticle: falsecomment: falseeditLink: false---
  • 接下来通过如下地址就能够拜访目录页了：http://localhost:8080/mall-le...

  • 当然你也能够批改导航栏配置nav.js，这样会拜访起来会不便许多；
module.exports = [  { text: '首页', link: '/' },  {    text: 'mall学习教程',    link: '/mall-learning/',    items: [      { text: '序章', link: '/pages/72bed2/' },      { text: '架构篇', link: '/pages/c68875/' },      { text: '业务篇', link: '/pages/c981c1/' },      { text: '技术要点篇', link: '/pages/fab7d9/' },      { text: '部署篇', link: '/pages/db2d1e/' },    ],  }]
  • 增加胜利后导航栏显示成果如下，点击导航栏即可跳转到该目录；

  • 其实你还能够在首页index.md中通过增加feature来实现快速访问，这里咱们创立了三个feature；
---home: true# heroImage: /img/web.pngheroText: macrozheng's blogtagline: Java后端技术博客，积跬步以至千里，致敬每个爱学习的你。features: # 可选的  - title: mall学习教程    details: mall学习教程，架构、业务、技术要点全方位解析。    link: /mall-learning/    imgUrl: /img/ui.png  - title: SpringCloud学习教程    details: 一套涵盖大部分外围组件应用的Spring Cloud教程，包含Spring Cloud Alibaba及分布式事务Seata。    link: /springcloud-learning/    imgUrl: /img/other.png  - title: K8S学习教程    details: 实实在在的K8S实战教程，专为Java方向人群打造！    link: /springcloud-learning/ # 可选    imgUrl: /img/web.png # 可选---
  • 首页显示成果如下；

  • 每次咱们创立文章的Markdown文件时，会主动生成front matter，比方上面这个格局；
---title: mall整合SpringBoot+MyBatis搭建根本骨架date: 2021-08-19 16:30:11permalink: /pages/c68875/categories:  - mall学习教程  - 架构篇tags:  - SpringBoot  - MyBatis---

  • 上面别离介绍下这些属性的作用：

    • title：文章题目，默认为文件名称；
    • date：文章日期，默认为文件创建日期；
    • permalink：文件拜访永恒链接，能够自行批改；
    • categories：文章的分类，依据目录会主动生成；
    • tags：文章标签，不便碎片化文章的查找。
  • 如果你认真看下文章列表的话，能够发现有的文章会显示摘要，而有的不会显示，咱们能够通过<!-- more -->正文来管制摘要的显示，该正文之前内容均会作为摘要来显示；

  • 文章列表是否显示摘要比照如下；

  • 如果你想修改文章作者信息、侧边栏是否折叠、社交信息、页面底部版权信息等信息的话，能够批改主题配置文件themeConfig.js；
// 主题配置module.exports = {  nav,  sidebarDepth: 2, // 侧边栏显示深度，默认1，最大2（显示到h3题目）  logo: '/img/avatar.png', // 导航栏logo  repo: 'macrozheng', // 导航栏右侧生成Github链接  searchMaxSuggestions: 10, // 搜寻结果显示最大数  lastUpdated: '上次更新', // 开启更新工夫，并配置前缀文字   string | boolean (取值为git提交工夫)  docsDir: 'docs', // 编辑的文件夹  editLinks: false, // 启用编辑  editLinkText: '编辑',  sidebar: { mode: 'structuring', collapsable: false}, // 侧边栏  'structuring' | { mode: 'structuring', collapsable: Boolean} | 'auto' | 自定义    舒适提醒：目录页数据依赖于结构化的侧边栏数据，如果你不设置为'structuring',将无奈应用目录页  author: {    // 文章默认的作者信息，可在md文件中独自配置此信息 String | {name: String, link: String}    name: 'macrozheng', // 必须    link: 'https://github.com/macrozheng', // 可选的  },  blogger: {    // 博主信息，显示在首页侧边栏    avatar: '/img/avatar.png',    name: 'macrozheng',    slogan: '这家伙很懒，什么都没写...',  },  social: {    // 社交图标，显示于博主信息栏和页脚栏    // iconfontCssFile: '//at.alicdn.com/t/font_1678482_u4nrnp8xp6g.css', // 可选，阿里图标库在线css文件地址，对于主题没有的图标可自在增加    icons: [      {        iconClass: 'icon-github',        title: 'GitHub',        link: 'https://github.com/macrozheng',      },      {        iconClass: 'icon-gitee',        title: 'Gitee',        link: 'https://gitee.com/macrozheng',      },      {        iconClass: 'icon-juejin',        title: '掘金',        link: 'https://juejin.cn/user/958429871749192',      }    ],  },  footer: {    // 页脚信息    createYear: 2019, // 博客创立年份    copyrightInfo:      'marcozheng | <a href="https://github.com/xugaoyi/vuepress-theme-vdoing/blob/master/LICENSE" target="_blank">MIT License</a>', // 博客版权信息，反对a标签  },  htmlModules // 插入hmtl(广告)模块}
  • Vdoing增加了很多插件，有些你用不上，能够通过批改plugins.js来禁用，比方禁用下百度统计插件，第二个参数改为false就行了；
// 插件配置module.exports = [  [    'vuepress-plugin-baidu-tongji', // 百度统计    false, //禁用    {      hm: 'xxx',    },  ],]
  • Vdoing浅色主题默认代码块主题也是浅色主题，咱们能够通过批改palette.styl文件来改成深色主题；
 // 浅色模式 .theme-mode-light   // 代码块浅色主题   //--codeBg: #f6f6f6   //--codeColor: #525252   //codeThemeLight()    // 代码块深色主题    --codeBg: #252526    --codeColor: #fff    codeThemeDark()
  • 咱们放在docs一级目录下的带序号的专栏默认会生成目录，如果咱们有些碎片化的文章不想生成结构化目录的话，能够放在_posts目录下；

  • Linux命令这篇文章就没有生成结构化目录，只是应用文章中的二级题目生成了个目录。

部署

VuePress生成网站也非常简单，一个命令实现打包，而后搁置到Nginx的html目录下即可。
  • 在命令行应用npm run build命令能够将我的项目打包成动态文件，输入文件目录为docs/.vuepress/dist；

  • 接下来把dist目录下的所有文件复制到Nginx的html目录下即可实现部署，部署后显示内容如下。

总结

应用VuePress+Vdoing来搭建文档网站不仅炫酷而且功能强大！比照Docsify的动静生成文档，VuePress生成动态页面性能更好，同时对SEO也更敌对。 如果你只想搭建简略的单我的项目文档的话，Docsify基本上也够用了。如果你想搭建多我的项目文档，或者博客网站的话，还是举荐你应用VuePress的。

参考资料

  • vuepress-theme-vdoing主题官网：https://doc.xugaoyi.com/
  • VuePress官网：https://vuepress.vuejs.org/zh/

我的项目地址

https://github.com/xugaoyi/vu...

本文 GitHub https://github.com/macrozheng/mall-learning 曾经收录，欢送大家Star！