The following article is from macrozheng Author 梦想de星空
专注Java技术分享,解析优质开源项目。涵盖SpringBoot、SpringCloud、Docker、K8S等实用技术,作者Github开源项目mall(50K+Star)。
之前有很多朋友问我,我的开源项目文档网站是用什么搭建的。其实是用Docsify搭建的,具体可以参考如何写出优雅的开源项目文档 。Docsify用来搭建成体系的文档网站基本够用了,但有时候我们既有成体系的文章、又有碎片化的文章,如果把文章都挂上去,看起来未免有些凌乱,这时候我们可能需要搭建一个类似知识库的网站了。最近发现使用VuePress可以搭建一个功能强大的文档网站,推荐给大家!
VuePress是Vue驱动的静态网站生成器。对比我们的Docsify动态生成网站,对SEO更加友好。
使用VuePress具有如下优点:
一般我们使用VuePress搭建网站的时候,都会选择一个主题。这里选择的是vuepress-theme-vdoing
,一款简洁高效的知识管理&博客主题,用来搭建文档网站绰绰有余。
学了技术老忘怎么破?用Vdoing搭建一个知识库试试!它能帮助我们更好地管理知识,并能够快速地把遗忘的知识点找回来。
使用Vdoing主题具有如下优点:
我们先来看下成品效果,有三种不同模式可供选择,是不是够炫酷!
通过Vdoing搭建网站非常简单,就算你对Vue不熟悉也没关系。
dev
模式运行;# 安装
npm install
# 运行
npm run dev
深色模式
。由于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 -- 专门存放碎片化博客文章的文件夹,不会自动生成目录
约定优于配置
的说法,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
---
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 # 可选
---
front matter
,比如下面这个格式;---
title: mall整合SpringBoot+MyBatis搭建基本骨架
date: 2021-08-19 16:30:11
permalink: /pages/c68875/
categories:
- mall学习教程
- 架构篇
tags:
- SpringBoot
- MyBatis
---
下面分别介绍下这些属性的作用:
如果你仔细看下文章列表的话,可以发现有的文章会显示摘要,而有的不会显示,我们可以通过<!-- 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(广告)模块
}
htmlModules.js
文件的pageT
和pageB
属性;module.exports = {
pageTshowMode:'article',
pageBshowMode:'article',
pageT: `<p>学习不走弯路,<a href="#%E5%85%AC%E4%BC%97%E5%8F%B7">关注公众号</a> 回复「学习路线」,获取mall项目专属学习路线!</p>`,
pageB: `<h2 id="公众号"><a href="#公众号" class="header-anchor">#</a> 公众号</h2><p><img src="http://macro-oss.oss-cn-shenzhen.aliyuncs.com/mall/banner/qrcode_for_macrozheng_258.jpg" alt="公众号图片" style="cursor: zoom-in;"></p>`,
}
plugins.js
来禁用,比如禁用下百度统计插件,第二个参数改为false
就行了;// 插件配置
module.exports = [
[
'vuepress-plugin-baidu-tongji', // 百度统计
false, //禁用
{
hm: 'xxx',
},
],
]
palette.styl
文件来改成深色主题; // 浅色模式
.theme-mode-light
// 代码块浅色主题
//--codeBg: #f6f6f6
//--codeColor: #525252
//codeThemeLight()
// 代码块深色主题
--codeBg: #252526
--codeColor: #fff
codeThemeDark()
docs
一级目录下的带序号的专栏默认会生成目录,如果我们有些碎片化的文章不想生成结构化目录的话,可以放在_posts
目录下;VuePress生成网站也非常简单,一个命令完成打包,然后放置到Nginx的html目录下即可。
npm run build
命令可以将项目打包成静态文件,输出文件目录为docs/.vuepress/dist
;dist
目录下的所有文件复制到Nginx的html
目录下即可完成部署,部署后显示内容如下。使用VuePress+Vdoing来搭建文档网站不仅炫酷而且功能强大!对比Docsify的动态生成文档,VuePress生成静态页面性能更好,同时对SEO也更友好。如果你只想搭建简单的单项目文档的话,Docsify基本上也够用了。如果你想搭建多项目文档,或者博客网站的话,还是推荐你使用VuePress的。
https://github.com/xugaoyi/vuepress-theme-vdoing
2021-09-09
2021-09-06
2021-09-02