Create cool open source project documents in seconds, this artifact is elegant enough to use!

Friends who have studied my open source project mall should know that I have a project documentation website built with Docsify. Using Docsify to build a document website is simple, but it lacks functions such as classification, tags, and SEO. With more and more documents, it is a bit inconvenient to find! Today, I would like to recommend a cool document theme vuepress-theme-hope , which is suitable for building a project document website!

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

Introduction to vuepress-theme-hope

vuepress-theme-hope is a powerful VuePress theme that adds more enhanced syntax to Markdown, which can be used to build project documentation and blog sites. Supports categorization and tagging to make your documents more structured! Built-in a variety of plug-ins, powerful, worth a try!

Demonstration effect

Let's first take a look at the demonstration effect of the website built using vuepress-theme-hope , which is quite cool!

Install

Using vuepress-theme-hope build a documentation website is very simple, basically it is out of the box, let's install it first.

• First create the docs directory in the installation directory, and then use the following command to initialize the project;

 npm init vuepress-theme-hope@next docs

• All dependencies will be installed during the initialization process, and some settings need to be made for the project, please refer to the following figure for details;

• After the installation is complete, you can choose to start it immediately, or you can use the following command to start it;

 npm run docs:dev

• After the startup is successful, you can access it. The following is the rendering that I have configured. The access address: http://localhost:8080/

• We can find that this theme not only supports switching of multiple theme colors, but also supports dark mode and light mode, which is quite cool!

use

Next, I will introduce the use of vuepress-theme-hope themes, mainly the use and custom configuration of some interface components.

Directory Structure

First, let's understand the overall directory structure of the project, which will be very helpful for us to use this theme later.

It should be noted here that if an error occurs during the running process, you can try to delete the two temporary folders .cache and .temp .

Navigation Bar

• Generally speaking, we all have the need to modify the top navigation bar. For example, we want to customize the lower navigation bar as follows;

• navbar.ts file can be modified. The modified content is as follows. The modified navigation bar can support sub-directories, which can be navigated to this site or external links.

 export default defineNavbarConfig([
    "/",
    "/home",
    {
        text: "mall学习教程",
        icon: "launch",
        prefix: "/mall/",
        children: [
            {
                text: "序章",
                icon: "note",
                link: "foreword/mall_foreword_01",
            },
            {
                text: "架构篇",
                icon: "note",
                link: "architect/mall_arch_01",
            },
            {
                text: "业务篇",
                icon: "note",
                link: "database/mall_database_overview",
            },
            {
                text: "技术要点篇",
                icon: "note",
                link: "technology/mybatis_mapper",
            },
            {
                text: "部署篇",
                icon: "note",
                link: "deploy/mall_deploy_windows",
            }
        ],
    },
    {
        text: "SpringCloud学习教程",
        icon: "hot",
        link: "/springcloud/springcloud",
    },
    {
        text: "项目地址",
        icon: "stack",
        children: [
            {
                text: "后台项目",
                link: "https://github.com/macrozheng/mall",
            },
            {
                text: "前端项目",
                link: "https://github.com/macrozheng/mall-admin-web",
            },
            {
                text: "学习教程",
                link: "https://github.com/macrozheng/mall-learning",
            },
            {
                text: "项目骨架",
                link: "https://github.com/macrozheng/mall-tiny",
            }
        ],
    },
]);

Sidebar

• Modifying the sidebar is also a common requirement, such as configuring a directory for project documents for easy viewing, such as the sidebar of my mall learning tutorial;

• To achieve the above effect, you need to modify the sidebar.ts file. It is worth mentioning that vuepress-theme-hope supports different sidebars for different paths, so that you don't have to combine all document sidebars together ;

 export default defineSidebarConfig({
  "/mall/":[
    {
      text: "序章",
      icon: "note",
      collapsable: true,
      prefix: "foreword/",
      children: ["mall_foreword_01", "mall_foreword_02"],
    },
    {
      text: "架构篇",
      icon: "note",
      collapsable: true,
      prefix: "architect/",
      children: ["mall_arch_01", "mall_arch_02","mall_arch_03"],
    },
    {
      text: "业务篇",
      icon: "note",
      collapsable: true,
      prefix: "database/",
      children: ["mall_database_overview", "mall_pms_01","mall_pms_02"],
    },
    {
      text: "技术要点篇",
      icon: "note",
      collapsable: true,
      prefix: "technology/",
      children: ["mybatis_mapper", "aop_log"],
    },
    {
      text: "部署篇",
      icon: "note",
      collapsable: true,
      prefix: "deploy/",
      children: ["mall_deploy_windows", "mall_deploy_docker"],
    }
  ],
  "/springcloud":["springcloud", "eureka", "ribbon"]
});

• Take a look at the sidebar of the configured SpringCloud learning tutorial, which is separate from the mall learning tutorial and has a clearer structure, which cannot be done with Docsify.

icon

• vuepress-theme-hope theme supports the use of icons on iconfont by default, we can use them directly in the project document, the following are some selected icons;

• Since the icon prefix is configured in themeConfig.ts , the icon- prefix needs to be removed when using it.

 export default defineThemeConfig({
  iconPrefix: "iconfont icon-",
})

Information customization

When using vuepress-theme-hope to build your own project documentation website, you need to customize some of your own information, such as author name, document link, logo and other information, which can be modified in themeConfig.ts .

 export default defineThemeConfig({
  hostname: "http://www.macrozheng.com",

  author: {
    name: "macrozheng",
    url: "http://www.macrozheng.com",
  },

  iconPrefix: "iconfont icon-",

  logo: "/logo.png",

  repo: "https://github.com/macrozheng",

  docsDir: "demo/src",

  // navbar
  navbar: navbar,

  // sidebar
  sidebar: sidebar,

  footer: "默认页脚",

  displayFooter: true,

  blog: {
    description: "SpringBoot实战电商项目mall（50K+Star）的作者",
    intro: "https://github.com/macrozheng",
    medias: {
      Gitee: "https://gitee.com/macrozheng",
      GitHub: "https://github.com/macrozheng",
      Wechat: "https://example.com",
      Juejin: "https://juejin.cn/user/958429871749192",
      Zhihu: "https://www.zhihu.com/people/macrozheng",
    },
  },
});

Documentation Home

• Homepage information can be modified in home.md , such as the following style of the project document homepage:

• The modification content is as follows, which supports adding multiple custom modules on the home page.

 ---
home: true
icon: home
title: mall学习教程
heroImage: /logo.png
heroText: mall学习教程
tagline: mall学习教程，架构、业务、技术要点全方位解析。mall项目（50k+star）是一套电商系统，使用现阶段主流技术实现。
actions:
  - text: 使用指南 💡
    link: /mall/foreword/mall_foreword_01

  - text: SpringCloud系列 🏠
    link: /springcloud/springcloud
    type: secondary

features:
  - title: mall学习教程
    icon: markdown
    details: mall学习教程，架构、业务、技术要点全方位解析。mall项目（50k+star）是一套电商系统，使用现阶段主流技术实现。
    link: /mall/foreword/mall_foreword_01

  - title: SpringCloud学习教程
    icon: slides
    details: 一套涵盖大部分核心组件使用的Spring Cloud教程，包括Spring Cloud Alibaba及分布式事务Seata，基于Spring Cloud Greenwich及SpringBoot 2.1.7。
    link: /springcloud/springcloud

  - title: K8S系列教程
    icon: layout
    details: 实实在在的K8S实战教程，专为Java方向人群打造！只讲实用的，抛弃那些用不到又难懂的玩意！同时还有配套的微服务实战项目mall-swarm，很好很强大！
    link: https://juejin.cn/column/6962026171823292452
    
  - title: mall
    icon: markdown
    details: mall项目是一套电商系统，包括前台商城系统及后台管理系统，基于SpringBoot+MyBatis实现，采用Docker容器化部署。
    link: https://github.com/macrozheng/mall
    
  - title: mall-admin-web
    icon: comment
    details: mall-admin-web是一个电商后台管理系统的前端项目，基于Vue+Element实现。
    link: https://github.com/macrozheng/mall-admin-web

  - title: mall-swarm
    icon: info
    details: mall-swarm是一套微服务商城系统，采用了 Spring Cloud Hoxton & Alibaba、Spring Boot 2.3、Docker、Kubernetes等核心技术。
    link: https://github.com/macrozheng/mall-swarm
    
  - title: mall-tiny
    icon: blog
    details: mall-tiny是一款基于SpringBoot+MyBatis-Plus的快速开发脚手架，拥有完整的权限管理功能，可对接Vue前端，开箱即用。
    link: https://github.com/macrozheng/mall-tiny

    
copyright: false
footer: MIT Licensed | Copyright © 2019-present macrozheng
---

Blog Home

• vuepress-theme-hope theme can be used not only as a project document website, but also as a blog website. Let's take a look at the style of the blog homepage it generates;

• To achieve the above style, modify the README.md file, the modification content is as follows.

 ---
home: true
layout: Blog
icon: home
title: 主页
heroImage: /logo.png
heroText: macrozheng的个人博客
heroFullScreen: true
tagline: 这家伙很懒，什么都没写...
projects:
  - icon: project
    name: mall
    desc: mall项目是一套电商系统，包括前台商城系统及后台管理系统，基于SpringBoot+MyBatis实现，采用Docker容器化部署。
    link: https://github.com/macrozheng/mall

  - icon: link
    name: mall-admin-web
    desc: mall-admin-web是一个电商后台管理系统的前端项目，基于Vue+Element实现。
    link: https://github.com/macrozheng/mall-admin-web

  - icon: book
    name: mall-swarm
    desc: mall-swarm是一套微服务商城系统，采用了 Spring Cloud Hoxton & Alibaba、Spring Boot 2.3、Docker、Kubernetes等核心技术。
    link: https://github.com/macrozheng/mall-swarm

  - icon: article
    name: mall-tiny
    desc: mall-tiny是一款基于SpringBoot+MyBatis-Plus的快速开发脚手架，拥有完整的权限管理功能，可对接Vue前端，开箱即用。
    link: https://github.com/macrozheng/mall-tiny

footer: 自定义你的页脚文字
---

code style

• Of course, if you think vuepress-theme-hope the default code theme is not cool enough, you can also customize it, the default is one-light and one-dark themes, there are as many as ten A variety of dark and light color themes to choose from;

• Need to modify the config.scss file, here is changed to the theme of the material series;

 $codeLightTheme: material-light;
$codeDarkTheme: material-dark;

• The code style in light mode is as follows;

• The code style in dark mode is as follows, which is quite cool!

Categories and Labels

• vuepress-theme-hope Built-in classification and labeling functions, which can make our project documents more structured and more convenient to view the content, directly add category and tag at the top of the article can be realized;

 ---
title: mall整合SpringBoot+MyBatis搭建基本骨架
date: 2021-08-19 16:30:11
category:
  - mall学习教程
  - 架构篇
tag:
  - SpringBoot
  - MyBatis
---

• After the addition is successful, categories and tags will appear under the title of our article;

• Click on a category to view all articles in that category;

• Click the label to view all related articles, which is much more efficient than Docsify to find articles!

Summarize

vuepress-theme-hope is indeed a useful tool for building project documentation websites and blog websites! Especially its classification and labeling functions make our documents more structured and easier to find!

project address

https://github.com/vuepress-theme-hope/vuepress-theme-hope