For those of you who have studied my open source project Mall, I have a project documentation site built using Docsify. Using Docsify to build a document website is simple, but it lacks such functions as classification, tags and SEO. With more and more documents, it is a little inconvenient to find them! Today, I recommend a cool document theme vuepress-theme-hope to build a project document website.

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

A brief introduction vuepress – theme – hope

Vuepress-theme-hope is a powerful Vuepress theme that adds more enhanced syntax to Markdown and can be used to build project documents and blog sites. Support classification and tagging functions, can make your documents more structured! Built-in plug-ins, powerful, worth a try!

Demonstration effect

Let’s take a look at the vuepress-theme-hope website demo, or pretty cool!

The installation

Setting up a document site using vuepress-theme-Hope is pretty simple, almost out of the box, so let’s install it first.

  • First create it in the installation directorydocsDirectory, and then initialize the project using the following command;
npm init vuepress-theme-hope@next docs
Copy the code
  • All dependencies will be installed during the initialization process, and some Settings for the project will be required, as shown in the following figure.

  • After the installation is complete, you can start the software immediately or run the following command to start the software.
npm run docs:dev
Copy the code
  • You can access it after successful startup. The following is the effect picture I have configured, and the access address is http://localhost:8080/

  • We can see that the theme not only supports multiple theme colors, but also supports dark mode and light mode, which is quite cool!

use

The next section describes how to use the vuepress-theme-Hope theme, mainly using some interface components and customizing configurations.

The directory structure

First let’s take a look at the overall directory structure of the project, which will help us use the theme later.

Note that if errors occur, you can try to delete the. Cache and. Temp temporary folders.

The navigation bar

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

  • You can modifynavbar.tsThe modified content is as follows. The modified navigation bar can support sub-directories. You can navigate to this site or external links.
export default defineNavbarConfig([
    "/"."/home",
    {
        text: "Mall Learning Course".icon: "launch".prefix: "/mall/".children: [{text: "Prologue".icon: "note".link: "foreword/mall_foreword_01"}, {text: "Framework".icon: "note".link: "architect/mall_arch_01"}, {text: "Business Chapter".icon: "note".link: "database/mall_database_overview"}, {text: "Technical Essentials".icon: "note".link: "technology/mybatis_mapper"}, {text: "Deployment".icon: "note".link: "deploy/mall_deploy_windows",}],}, {text: "SpringCloud Learning Tutorial".icon: "hot".link: "/springcloud/springcloud"}, {text: "Project Address".icon: "stack".children: [{text: "Background project".link: "https://github.com/macrozheng/mall"}, {text: "Front-end project".link: "https://github.com/macrozheng/mall-admin-web"}, {text: "Learning course".link: "https://github.com/macrozheng/mall-learning"}, {text: "Project skeleton".link: "https://github.com/macrozheng/mall-tiny",}],},]);Copy the code

The sidebar

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

  • Achieving the above effect requires modificationsidebar.tsDocuments, it’s worth mentioningvuepress-theme-hopeSupport for implementing different sidebars for different paths, so that you don’t have to merge all the document sidebars together;
export default defineSidebarConfig({
  "/mall/":[
    {
      text: "Prologue".icon: "note".collapsable: true.prefix: "foreword/".children: ["mall_foreword_01"."mall_foreword_02"],}, {text: "Framework".icon: "note".collapsable: true.prefix: "architect/".children: ["mall_arch_01"."mall_arch_02"."mall_arch_03"],}, {text: "Business Chapter".icon: "note".collapsable: true.prefix: "database/".children: ["mall_database_overview"."mall_pms_01"."mall_pms_02"],}, {text: "Technical Essentials".icon: "note".collapsable: true.prefix: "technology/".children: ["mybatis_mapper"."aop_log"],}, {text: "Deployment".icon: "note".collapsable: true.prefix: "deploy/".children: ["mall_deploy_windows"."mall_deploy_docker"],}],"/springcloud": ["springcloud"."eureka"."ribbon"]});Copy the code
  • 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 is not possible with Docsify.

icon

  • vuepress-theme-hopeThemes support iconfont ICONS by default, which can be used directly in project documentation. Here are a few selection ICONS;

  • Due to thethemeConfig.tsIs configured with the icon prefix, which needs to be removed before useicon-Prefix.
export default defineThemeConfig({
  iconPrefix: "iconfont icon-",})Copy the code

Information customization

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

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: "Default footer".displayFooter: true.blog: {
    description: "Author of SpringBoot Actual E-commerce project 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",}}});Copy the code

Document page

  • Home page information is available athome.mdFor example, the following style of the project document home page:

  • The modifications are as follows: Multiple custom modules can be added to the home page.
-- Home: true icon: Home title: Mall heroImage: /logo.png heroText: Mall Tagline: Mall Mall Project (50K + STAR) is a set of e-commerce system, using the current mainstream technology to achieve. actions:  -Text: User guide 💡    link: /mall/foreword/mall_foreword_01

  -Text: SpringCloud series 🏠link: /springcloud/springcloud type: secondary
features:
  -Title: Mall learning tutorialIcon: Markdown Details: Mall learning tutorial, comprehensive analysis of architecture, business, technical points. Mall Project (50K + STAR) is a set of e-commerce system, using the current mainstream technology to achieve. link: /mall/foreword/mall_foreword_01
  -Title: SpringCloud learning Tutorialicon: slides details: A set of Spring Cloud tutorials covering the use of most core components, including Spring Cloud Alibaba and distributed transaction Seata, based on Spring Cloud Greenwich and SpringBoot 2.1.7. link: /springcloud/springcloud
  -Title: K8S series tutorialsIcon: Layout Details: K8S practical tutorial, designed for the Java direction of the crowd! Stick to the practical ones and get rid of those that are not useful and difficult to understand! At the same time there are supporting micro service actual combat project mall-swarm, very good very powerful! link: https://juejin.cn/column/6962026171823292452 - title: mall icon: markdown details: Mall project is a set of e-commerce system, including the foreground mall system and background management system, which is implemented based on SpringBoot+MyBatis and deploys Docker container. link: https://github.com/macrozheng/mall - title: mall-admin-web icon: comment details: Mall - Admin - Web is a front-end project of e-commerce background management system, based on Vue+Element implementation. link: https://github.com/macrozheng/mall-admin-web
  - title: mall-swarm
Mall-swarm is a set of micro service mall system, using Spring Cloud Hoxton & Alibaba, Spring Boot 2.3, Docker, Kubernetes and other core technologies. link: https://github.com/macrozheng/mall-swarm - title: mall-tiny icon: blog details: Mall-tiny is a fast development scaffold based on SpringBoot+MyBatis-Plus, with complete permission management functions, can be connected to the Vue front-end, out of the box. link: https://github.com/macrozheng/mall-tiny
Copyright: false footer: MIT Licensed | copyright © 2019 - present macrozheng -Copy the code

Blog’s front page

  • vuepress-theme-hopeThemes can be used not only as project documentation sites, but also as blog sites. Let’s take a look at the style of the blog home page it generates.

  • To implement the style above, modifyREADME.mdModify the file as follows.
-- Home: true layout: Blog icon: home title: home heroImage: /logo.png True Tagline: This guy is lazy and doesn't write anything... projects:  - icon: project
Name: Mall Desc: Mall project is a set of e-commerce system, including the front mall system and background management system, based on SpringBoot+MyBatis, Docker container deployment. link: https://github.com/macrozheng/mall
  - icon: link
Name: mall-admin-web desc: mall-admin-Web is a front-end project of e-commerce background management system, based on Vue+Element. link: https://github.com/macrozheng/mall-admin-web
  - icon: book
Name: Mall-swarm DESC: Mall-swarm is a set of micro service mall system, using Spring Cloud Hoxton & Alibaba, Spring Boot 2.3, Docker, Kubernetes and other core technologies. link: https://github.com/macrozheng/mall-swarm
  - icon: article
Name: mall-Tiny DESC: Mall-Tiny is a fast development scaffold based on SpringBoot+MyBatis-Plus, with complete rights management functions, can connect to Vue front-end, out of the box. link: https://github.com/macrozheng/mall-tiny
Footer: Customize your footer text
Copy the code

The code style

  • Of course if you thinkvuepress-theme-hopeThe default code theme is not cool, you can also customize it, the default isone-lightandone-darkThemes, as many as a dozen dark and light themes to choose from;

  • Need to modifyconfig.scssFile, I’ll change it tomaterialThe theme of the series;
$codeLightTheme: material-light;
$codeDarkTheme: material-dark;
Copy the code
  • The code looks like this in light-colored mode;

  • In dark mode, the code looks like this, which is pretty cool!

Classification and labelling

  • vuepress-theme-hopeBuilt-in classification and tagging functions make our project documents more structured and easier to view the content, added directly at the top of the articlecategoryandtagCan be realized;
-- Integrating SpringBoot+MyBatis to build basic skeleton  -Mall Learning Tutorial  -Architecture piece tag:  - SpringBoot
  - MyBatis
---
Copy the code
  • After the successful addition, categories and labels will appear under the title of our article;

  • Click the category to view all articles under the category;

  • Click the TAB to see all related articles, much more efficient than Docsify for finding articles!

conclusion

Vuepress-theme-hope is a great tool for building project documentation and blog sites! Especially its classification, tag function, so that our documents can be more structured, more convenient to find!

If you want to learn more about SpringBoot, you can try the full SpringBoot program (50K+Star) at github.com/macrozheng/…

The project address

Github.com/vuepress-th…