Why are their open source project documents so cool? It turned out to be this artifact!

Many friends asked me what I built my open source project documentation website. In fact, it was built with Docsify. For details, please refer to How to write an elegant open source project document . Docsify is basically enough to build a systematic document website, but sometimes we have both systematic articles and fragmented articles. If you hang up all the articles, it looks messy. At this time, we may need Build a website similar to the knowledge base. I recently discovered that using VuePress can build a powerful document website, and I recommend it to everyone!

SpringBoot actual combat e-commerce project mall (50k+star) address: https://github.com/macrozheng/mall

Introduction to VuePress

VuePress is a static website generator powered by Vue. Compared with our Docsify dynamically generated website, it is more friendly to SEO.

Using VuePress has the following advantages:

Using Markdown to write articles, programmers can write easily, and the configuration of the website is very concise.
We can use Vue components in Markdown, which is very convenient if you are familiar with Vue.
When the website is packaged, static HTML is generated for each page pre-rendering, which has good performance and is also conducive to SEO.

Vdoing theme

Generally, when we use VuePress to build a website, we always choose a theme. The choice here is vuepress-theme-vdoing , a simple and efficient knowledge management & blog theme, more than enough to build a document website.

How do you forget to break after learning the technology? Try to build a knowledge base with Vdoing! It can help us better manage knowledge, and can quickly retrieve the forgotten knowledge points.

Using the Vdoing theme has the following advantages:

Knowledge management: As the subject has functions such as catalog, classification, and label, structured or fragmented content can be easily integrated.
Concise and efficient: Markdown-centric project structure, built-in automation tools, and accomplish more with less configuration.
Immersive reading: UI designed specifically for reading, with multiple color modes, closeable sidebar and navigation bar, brings you an immersive reading experience.

Effect demonstration

Let's take a look at the finished product first, there are three different modes to choose from, is it cool enough?

Build

Building a website through Vdoing is very easy, even if you are not familiar with Vue.

First, we need to download the project from Vdoing's official website. The download address is: https://github.com/xugaoyi/vuepress-theme-vdoing

After the download is complete, import it into IDEA. Since it is a Vue project, you need to use the following command to install the dependencies after the import is successful, and then dev mode;

# 安装
npm install
# 运行
npm run dev

After running successfully, just find an article and experience it, the interface is still pretty good, visit address: http://localhost:8080/

It also supports theme switching, such as switching to dark mode.

`Configuration`

Since Vdoing itself is a complete website, there are many articles and configurations that we don't need, so we have to replace these articles and customize these configurations.

Let's first take a look at the homepage effect after my customization. This theme is still very concise and looks very comfortable;

The project files are basically in the docs directory, let’s take a look at the role of these files;

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 -- 专门存放碎片化博客文章的文件夹，不会自动生成目录

Everyone has used SpringBoot. There is agreement is better than the configuration. Vdoing also has this saying. If we want to automatically generate an article directory based on the directory structure, we need to add a serial number to the directory and file, such as the following directory;

Under this directory structure, the first-level directory is called a column, and the second-level directory is the column content. The columns are independent of each other. The above directory structure will generate a sidebar with the following structure, and an outline on the right will also be generated. column;

If you want to add a catalog page to the column, you can add 02.mall learning tutorial.md 00. catalog page folder as the catalog, and the content of the catalog page is as follows, permalink can specify the permanent path of the catalog page;

---
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
---

Then you can access the catalog page through the following address: http://localhost:8080/mall-learning/

Of course, you can also modify the navigation bar configuration nav.js , which will be much easier to access;

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/' },
    ],
  }
]

After the addition is successful, the navigation bar will display as follows, click on the navigation bar to jump to the directory;

In fact, you can also add feature index.md to achieve quick access. Here we have created three 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 # 可选
---

The homepage display effect is as follows;

Every time we create a Markdown file of an article, front matter will be automatically generated, such as the following format;

---
title: mall整合SpringBoot+MyBatis搭建基本骨架
date: 2021-08-19 16:30:11
permalink: /pages/c68875/
categories:
  - mall学习教程
  - 架构篇
tags:
  - SpringBoot
  - MyBatis
---

The functions of these attributes are described below:
- title: the title of the article, the default is the file name;
- date: the date of the article, the default is the file creation date;
- permalink: file access permanent link, you can modify it yourself;
- categories: The classification of the article, which will be automatically generated according to the category;
- tags: Article tags to facilitate the search of fragmented articles.
If you look carefully at the article list, you can find that some articles will display abstracts, but some will not. We can  comment. The content before the comment will be displayed as an abstract;

Whether the article list shows the summary comparison is as follows;

If you want to modify the author information of the article, whether the sidebar is folded, social information, copyright information at the bottom of the page, etc., you can modify the theme configuration file 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 adds a lot of plug-ins, some of which you can’t use, can plugins.js , such as disabling the Baidu statistics plug-in, and the second parameter is changed to false ;

// 插件配置
module.exports = [
  [
    'vuepress-plugin-baidu-tongji', // 百度统计
    false, //禁用
    {
      hm: 'xxx',
    },
  ],
]

Vdoing light theme The default code block theme is also a light theme, we can change it to a dark theme palette.styl

 // 浅色模式
 .theme-mode-light
   // 代码块浅色主题
   //--codeBg: #f6f6f6
   //--codeColor: #525252
   //codeThemeLight()
    // 代码块深色主题
    --codeBg: #252526
    --codeColor: #fff
    codeThemeDark()

The columns with serial numbers that we put in the docs will generate directories by default. If we don’t want to generate structured directories for some fragmented articles, we can put _posts directory 0614153b2367d0;

Linux command this article does not generate a structured table of contents, but uses the second-level headings in the article to generate a table of contents.

`deploy`

VuePress is also very simple to generate a website. One command completes the packaging, and then places it in the html directory of Nginx.

npm run build command on the command line to package the project into a static file, and the output file directory is docs/.vuepress/dist ;

Next to dist copy all the files in the directory to the Nginx html directory to complete the deployment, post-deployment is displayed as follows.

`Summarize`

Using VuePress+Vdoing to build a document website is not only cool but also powerful! Compared with Docsify's dynamically generated documents, VuePress has better performance in generating static pages, and it is also more SEO friendly. If you just want to build simple single-project documents, Docsify is basically enough. If you want to build a multi-project document, or a blog site, I recommend you to use VuePress.

`Reference`

vuepress-theme-vdoing theme official website: https://doc.xugaoyi.com/
VuePress official website: https://vuepress.vuejs.org/zh/

`project address`

https://github.com/xugaoyi/vuepress-theme-vdoing

This article GitHub https://github.com/macrozheng/mall-learning has been included, welcome to Star!

Why are their open source project documents so cool? It turned out to be this artifact!

Introduction to VuePress

Vdoing theme

Effect demonstration

Build

`Configuration`

`deploy`

`Summarize`

`Reference`

`project address`

macrozheng

`引用和评论`

8.4K star！全新一代终端文件管理神器，用起来够优雅！

💢线上高延迟请求排查

每一个前端，都要拥有属于自己的埋点库~

这些年

Spring-@Configuration注解简析

Specifications 构建动态查询

单元测试-PowerMock