之前有很多敌人问我,我的开源我的项目文档网站是用什么搭建的。其实是用 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:54
permalink: /mall-learning
sidebar: false
article: false
comment: false
editLink: 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.png
heroText: macrozheng's blog
tagline: 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:11
permalink: /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!