关于java:秒建炫酷的开源项目文档这款神器用起来够优雅

36次阅读

共计 6382 个字符,预计需要花费 16 分钟才能阅读完成。

学习过我的开源我的项目 mall 的敌人应该晓得,我有一个应用 Docsify 搭建的我的项目文档网站。应用 Docsify 搭建文档网站尽管简略,然而短少分类、标签、SEO 这类性能,随着文档越来越多,查找起来有点不不便!明天给大家举荐一个炫酷的文档主题vuepress-theme-hope,用来搭建我的项目文档网站正合适!

SpringBoot 实战电商我的项目 mall(50k+star)地址:https://github.com/macrozheng/mall

vuepress-theme-hope 简介

vuepress-theme-hope是一个具备弱小性能的 VuePress 主题,为 Markdown 增加了更多加强语法,可用于搭建我的项目文档和博客网站。反对分类和标签性能,能够让你的文档更加结构化!内置多种插件,功能强大,值得一试!

演示成果

咱们先来看下应用 vuepress-theme-hope 搭建的网站演示成果,还是挺炫酷的!

装置

应用 vuepress-theme-hope 搭建文档网站非常简单,根本就是开箱即用,咱们先来装置它。

  • 首先在装置目录下创立 docs 目录,而后应用如下命令初始化我的项目;
npm init vuepress-theme-hope@next docs
  • 初始化过程中会装置所有依赖,还须要对我的项目进行一些设置,具体参考下图;

  • 装置实现后能够抉择立即启动,也能够应用如下命令启动;
npm run docs:dev
  • 启动胜利后即可拜访,上面是我曾经配置实现的效果图,拜访地址:http://localhost:8080/

  • 咱们能够发现该主题不仅反对多种主题色的切换,还反对深色模式和浅色模式,还是挺炫酷的!

应用

接下来介绍下 vuepress-theme-hope 主题的应用,次要是一些界面组件的应用和自定义配置。

目录构造

首先咱们来理解下我的项目的整体目录构造,这对咱们之后应用该主题会有很大帮忙。

这里须要留神的是,如果运行过程中呈现谬误,能够尝试删除 .cache.temp两个长期文件夹。

导航栏

  • 一般来说咱们都有批改顶部导航栏的需要,例如咱们想要按如下款式定制下导航栏;

  • 能够批改 navbar.ts 文件,批改内容如下,批改后的导航栏可反对子级目录,既能够导航到本站,也能够导航到内部链接。
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",
            }
        ],
    },
]);

侧边栏

  • 批改侧边栏也是个常见需要,例如给我的项目文档配置下目录,不便查看,比方我的 mall 学习教程的侧边栏;

  • 实现下面的成果须要批改 sidebar.ts 文件,值得一提的是 vuepress-theme-hope 反对针对不同门路实现不同的侧边栏,这样就不必把所有文档侧边栏糅合在一起了;
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"]
});
  • 看下配置好的 SpringCloud 学习教程的侧边栏,和 mall 学习教程的是离开的,构造更加清晰的了,这是应用 Docsify 无奈做到的。

图标

  • vuepress-theme-hope主题默认反对应用 iconfont 上的图标,咱们能够在我的项目文档中间接应用,以下是一些精选图标;

  • 因为在 themeConfig.ts 中配置了图标前缀,在应用时须要去除 icon- 前缀。
export default defineThemeConfig({iconPrefix: "iconfont icon-",})

信息定制

在应用 vuepress-theme-hope 搭建本人的我的项目文档网站时,须要定制一些本人的信息,比方作者名称、文档链接、logo 等信息,能够在 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",
    },
  },
});

文档首页

  • 首页信息能够在 home.md 中进行批改,比方上面款式的我的项目文档首页:

  • 批改内容如下,反对在首页上增加多个自定义模块。
---
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
---

博客首页

  • vuepress-theme-hope主题不仅能够做我的项目文档网站,也能够做博客网站,咱们先来看下它生成的博客首页款式;

  • 要实现下面的款式,批改 README.md 文件即可,批改内容如下。
---
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: 自定义你的页脚文字
---

代码款式

  • 当然如果你感觉 vuepress-theme-hope 默认的代码主题不够炫酷,也能够自定义一下,默认是 one-lightone-dark主题,还有多达十几种深浅色主题可供选择;

  • 须要批改下 config.scss 文件,这里改为了 material 系列的主题;
$codeLightTheme: material-light;
$codeDarkTheme: material-dark;
  • 浅色模式下代码款式如下;

  • 深色模式下代码款式如下,还是挺炫酷的!

分类及标签

  • vuepress-theme-hope内置了分类和标签性能,能够让咱们的我的项目文档更加结构化,查看内容也更不便,间接在文章顶部增加 categorytag即可实现;
---
title: mall 整合 SpringBoot+MyBatis 搭建根本骨架
date: 2021-08-19 16:30:11
category:
  - mall 学习教程
  - 架构篇
tag:
  - SpringBoot
  - MyBatis
---
  • 增加胜利后咱们的文章题目下方会呈现分类和标签;

  • 点击分类能够查看该分类下所有文章;

  • 点击标签能够查看所有相干文章,比起 Docsify 查找文章效率大大提高了!

总结

vuepress-theme-hope的确是一款好用的工具,用来搭建我的项目文档网站和博客网站正合适!尤其是它的分类、标签性能,让咱们的文档可能更加结构化,查找也更加不便!

我的项目地址

https://github.com/vuepress-t…

正文完
 0