Why is someone else's open source project documentation so cool? This is the artifact used!

Many of my friends have asked me what my open source project documentation site is built out of. In fact, it is built with Docsify, see how to write elegant open source project documentation. The documentation site Docsify uses to build the system is basically enough, but sometimes we have structured articles and fragmented articles, and if we put all the articles on it, it looks a bit messy, so we may need to build a knowledge base site. Recently found using VuePress can build a powerful document website, recommended to everyone!

SpringBoot e-commerce project mall (50K + STAR) address: github.com/macrozheng/…

VuePress profile

VuePress is a VUUe-powered static web site generator. More SEO friendly than our Docsify dynamically generated site.

Using VuePress has the following advantages:

Using Markdown to write articles makes it easy for programmers to write and very simple to configure the site.
We can use the Vue component in Markdown, which is handy if you are familiar with Vue.
Packaging a website generates static HTML for each page pre-rendered, which is good for performance and SEO.

Vdoing theme

When building a website with VuePress, we usually choose a theme. Vuepress-theme-vdoing, a simple and efficient knowledge management & blog theme, is more than enough to build a document website.

Learn how to forget technology? Use Vdoing to build a knowledge base to try! It helps us to better manage knowledge and quickly retrieve lost knowledge.

Using a Vdoing theme has the following advantages:

Knowledge management: It is easy to integrate structured or fragmented content, thanks to the ability of this topic to catalog, categorize, tag, and so on.
Simple and efficient: Markdown-centric project structure with built-in automation tools to get more done with less configuration.
Immersive Reading: A UI designed for reading, with multiple color modes, closed sidebars and navigation, provides an immersive reading experience.

Results demonstrate

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

Set up

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

First of all, we need to go to the official website of Vdoing to download the project. The download address is github.com/xugaoyi/vue…

After the download is complete, import IDEA. Since it is a Vue project, run the following command to install the dependency after the import is successfuldevMode operation;

# installation
npm install
# run
npm run dev
Copy the code

After successful operation, just find an article to go into the experience, the interface is quite good, visit the address: http://localhost:8080/

It also supports theme switching, such as switching toDark mode.

configuration

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

Let’s take a look at my custom home page effect, the theme is still very simple, looks very comfortable;

The project files are basically theredocsDirectory, let’s look at what these files do;

Docs │ ├─ vuepress - For storing global configuration, components, static resources, etc. │ │ config.js - entry file │ │ enhanceapp.js - enhancement │ for client application │ ├─config │ ├─ head.js -- Add custom HTML module │ │ nav.js -- Top navigation bar │ │ plugins │ ├─ ├─ img -- ├─ Styles │ ├ palette. Styl -- Theme ├─ ├─ ├─ ├─ ├─style │ palette. ├─ @Pages - Generated folder │ Archivespage. md - Categoriespage. md - Categoriespage. md - Tag ├─images - You can store your own pictures ├ ─_posts - a special folder for fragged blog posts that doesn't automatically generate a directoryCopy the code

You’ve all used SpringBootConvention over ConfigurationIf we want to automatically generate the article directory according to the directory structure, we need to add the serial number to the directory and file, such as the following directory;

In this directory structure, the first level directory is called column, the second level directory is column content, each column is independent of each other, the top directory structure will generate the following structure of the sidebar, but also generates the outline bar on the right;

If you want to add a table of contents page to your column, you can do so in the00. Directory pageAdd to folder02. Mall Learning Tutorial. MdAs directories, the contents of the directory page are as follows,permalinkYou can specify a permanent path to the directory page;

---
pageComponent: 
  name: Catalogue
  data: 
ImgUrl: /img/ uI.png Description: Mall learning tutorial, architecture, business, technical points omni-direction analysis. Permalink: / Mall-Learning sidebar: False article: false comment: false editLink: false ---Copy the code

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

Of course, you can also modify the navigation configurationnav.js, so that access will be convenient;

module.exports = [
  { text: 'home'.link: '/' },
  {
    text: 'Mall Learning Tutorial'.link: '/mall-learning/'.items: [{text: 'preface chapter'.link: '/pages/72bed2/' },
      { text: 'Architecture Section'.link: '/pages/c68875/' },
      { text: 'Business Section'.link: '/pages/c981c1/' },
      { text: 'Technical Highlights'.link: '/pages/fab7d9/' },
      { text: Deployment Chapter.link: '/pages/db2d1e/'},],}]Copy the code

After the directory is added successfully, the navigation bar displays as follows. Click the navigation bar to jump to the directory.

In fact, you can also go to the home pageindex.mdBy addingfeatureFor fast access, here we’ve created threefeature;

---
home: true
# heroImage: /img/web.pngHeroText: Macrozheng's Blog Tagline: heroText: Macrozheng's Blog tagline is a Java backend technology blog. # Optional  -Title: Mall learning tutorialDetails: Mall learning tutorial, comprehensive analysis of architecture, business, technical points. Link: /mall-learning/ imgUrl: /img/ui.png - title: SpringCloud A set of Spring Cloud tutorials covering the use of most of the core components, including Spring Cloud Alibaba and distributed transaction Seata. Link: /springcloud-learning/ imgUrl: /img/other.png - title: K8S 教程 details: K8S 教程 details: Url: /img/web.png # Optional --Copy the code

The home page display effect is as follows;

Every time we create a Markdown file for the article, it will be generated automaticallyfront matter, such as the following format;

Date: 2021-08-19 16:30:11 Permalink: /pages/ C68875 / Categories:  -Mall Learning Tutorial  -Architecture tags as the following:  - SpringBoot
  - MyBatis
---
Copy the code

Here’s how these attributes work:
- Title: The title of the article, which defaults to the file name;
- Date: the date of the article. The default is the creation date of the file.
- Permalink: file access permalink, you can modify;
- Categories: Categories of articles, which are automatically generated according to the categories;
- Tags: article tags, easy to find fragmented articles.
If you look at the list of articles, you can see that some articles show summaries and some don’t, so we can go through<! -- more -->Note to control the display of the summary, the content before the note will be displayed as the summary;

Whether the article list shows the abstract comparison as follows;

You can modify the theme profile if you want to change the author information, whether the sidebar folds, social information, copyright information at the bottom of the page, etcthemeConfig.js;

// Theme configuration
module.exports = {
  nav,
  sidebarDepth: 2.// Sidebar display depth, default 1, Max 2 (display to h3 title)
  logo: '/img/avatar.png'.// Navigation logo
  repo: 'macrozheng'.// The Github link is generated on the right side of the navigation bar
  searchMaxSuggestions: 10.// The search results show the maximum number
  lastUpdated: 'Last update'./ / opening time, and configure the prefix text string | Boolean value (for git commit time)
  docsDir: 'docs'.// Edit the folder
  editLinks: false.// Enable editing
  editLinkText: 'edit'.sidebar: { mode: 'structuring'.collapsable: false}, / / the sidebar 'structuring | {mode:' structuring, collapsable: Boolean} | | custom warm prompt: 'auto' page directory data relies on the sidebar of structured data, if you don't set to 'structuring, will not be able to use the directory page

  author: {
    / / default information, the author of the article can separate configuration in md file this information String | {name: String, link: String}
    name: 'macrozheng'./ / necessary
    link: 'https://github.com/macrozheng'./ / optional
  },
  blogger: {
    // The information of the blogger is displayed in the sidebar of the homepage
    avatar: '/img/avatar.png'.name: 'macrozheng'.slogan: 'This guy is lazy and doesn't write anything... ',},social: {
    // Social icon, displayed in the blogger info bar and footer bar
    // iconfontCssFile: '//at.alicdn.com/t/font_1678482_u4nrnp8xp6g.css', // Optional, ali icon library online CSS file address, for the theme does not have ICONS can be freely added
    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: 'the nuggets'.link: 'https://juejin.cn/user/958429871749192',}],},footer: {
    // Footer information
    createYear: 2019.// The year the blog was created
    copyrightInfo:
      'marcozheng | <a href="https://github.com/xugaoyi/vuepress-theme-vdoing/blob/master/LICENSE" target="_blank">MIT License</a>'.// Blog copyright information, support a tag
  },
  htmlModules // Insert the HTML module
}
Copy the code

Vdoing adds a lot of plugins, some you don’t need, you can modifyplugins.jsTo disable, such as disable baidu statistics plug-in, the second parameter is changedfalseWe have to do is;

// Plug-in configuration
module.exports = [
  [
    'vuepress-plugin-baidu-tongji'.// Baidu statistics
    false./ / disable
    {
      hm: 'xxx',}],]Copy the code

Vdoing light theme The default code block theme is also light theme, which we can modifypalette.stylChange the file to a dark theme;

--codeBg: # f6F6F6 --codeColor: #525252 #252526 --codeColor: #fff codeThemeDark()Copy the code

We put indocsThe numbered columns in the first level directory are generated by default. If we have some fragmented articles that do not want to generate a structured directory, we can put them in_postsDirectory;

The Linux command does not generate a structured directory, just a directory using the secondary headings in the article.

The deployment of

VuePress is also very simple to generate a web site, packaged with a single command and placed in an HTML directory in Nginx.

Used at the command linenpm run buildCommand to package the project into a static file with the output file directory asdocs/.vuepress/dist;

Next, put thedistCopy all files in the directory to NginxhtmlAfter the deployment, the following information is displayed:

conclusion

Using VuePress+Vdoing to build a document website is not only cool and powerful! Compared to Docsify’s dynamically generated documents, VuePress generates static pages with better performance and is more SEO friendly. If you only want to build simple single-project documents, Docsify will probably do. VuePress is recommended if you want to build multi-project documentation or blog sites.

The resources

Vuepress-theme -vdoing official website: doc.xugaoy.enterp rise
VuePress website: vuepress.vuejs.org/zh/

The project address

Github.com/xugaoyi/vue…

In this paper, making github.com/macrozheng/… Already included, welcome everyone Star!

mo4tech.com (Moment For Technology) is a global community with thousands techies from across the global hang out!Passionate technologists, be it gadget freaks, tech enthusiasts, coders, technopreneurs, or CIOs, you would find them all here.

Why is someone else’s open source project documentation so cool? This is the artifact used!

VuePress profile

Vdoing theme

Results demonstrate

Set up

configuration

The deployment of

conclusion

The resources

The project address

Why is someone else’s open source project documentation so cool? This is the artifact used!

VuePress profile

Vdoing theme

Results demonstrate

Set up

configuration

The deployment of

conclusion

The resources

The project address

Related Posts

Why shouldn’t thread pools be created automatically?

Microservice – Distributed Lock (3) -Zookeeper solution

Oracle and mysql differences and related knowledge supplement _ Li Meng _ Sina blog