如何写出优雅的开源项目文档

最新推荐文章于 2024-08-31 07:35:35 发布

macrozheng

最新推荐文章于 2024-08-31 07:35:35 发布

阅读量1.8k

点赞数 1

本文链接：https://blog.csdn.net/zhenghongcs/article/details/99311956

版权

摘要

mall项目是我去年写的SpringBoot实战电商项目，现在在Github上面已经有18k+star。去年12月份的时候，mall项目只有一些必要的说明文档和部署文档。mall项目涉及到的技术栈比较广泛，业务也比较复杂，却没有系统的学习教程。今年5月份的时候，我开始完善整套学习教程，目前已经更新了三十余篇。最近使用docsify搭建了一个小型的文档网站，希望大家能有更好的阅读体验。本文将介绍如何使用docsify来写开源项目文档。

项目文档演示

使用docsify来写项目文档

docsify简介

docsify是一个动态生成网站的工具，它不会将.md文件转化为.html文件从而污染你的Github提交记录，所有转化都将在运行时完成。如果你需要快速搭建一个小型文档网站，这将非常实用。

初始化项目

安装nodejs

安装docsify-cli工具

npm i docsify-cli -g

初始化项目结构

docsify init ./docs

  -| docs/    -| .nojekyll    -| index.html    -| README.md
    -| index.html
    -| README.md

实时预览

docsify serve docs

定制侧边栏

  <script>    window.$docsify = {      loadSidebar: true,      maxLevel: 2,      subMaxLevel: 4,      alias: {        '/.*/_sidebar.md': '/_sidebar.md'//防止意外回退      }    }  </script>  <script src="//unpkg.com/docsify/lib/docsify.min.js"></script>
window.$docsify = {
loadSidebar: true,
maxLevel: 2,
subMaxLevel: 4,
alias: {
'/.*/_sidebar.md': '/_sidebar.md'//防止意外回退
      }
    }
</script>
<script src="//unpkg.com/docsify/lib/docsify.min.js"></script>

  * 序章    * [mall架构及功能概览](foreword/mall_foreword_01.md)    * [mall学习所需知识点](foreword/mall_foreword_02.md)  * 架构篇    * [mall整合SpringBoot+MyBatis搭建基本骨架](architect/mall_arch_01.md)    * [mall整合Swagger-UI实现在线API文档](architect/mall_arch_02.md)    * [mall架构及功能概览](foreword/mall_foreword_01.md)
    * [mall学习所需知识点](foreword/mall_foreword_02.md)
  * 架构篇
    * [mall整合SpringBoot+MyBatis搭建基本骨架](architect/mall_arch_01.md)
    * [mall整合Swagger-UI实现在线API文档](architect/mall_arch_02.md)

定制导航栏

  <script>    window.$docsify = {      loadNavbar: true,      alias: {        '/.*/_navbar.md': '/_navbar.md'//防止意外回退      }    }  </script>
window.$docsify = {
loadNavbar: true,
alias: {
'/.*/_navbar.md': '/_navbar.md'//防止意外回退
      }
    }
</script>

  * 演示    * [后台管理](http://39.98.190.128/index.html)    * [移动端](http://39.98.190.128/mall-app/mainpage.html)  * 项目地址    * [后台项目](https://github.com/macrozheng/mall)    * [前端项目](https://github.com/macrozheng/mall-admin-web)    * [学习教程](https://github.com/macrozheng/mall-learning)    * [后台管理](http://39.98.190.128/index.html)
    * [移动端](http://39.98.190.128/mall-app/mainpage.html)
  * 项目地址
    * [后台项目](https://github.com/macrozheng/mall)
    * [前端项目](https://github.com/macrozheng/mall-admin-web)
    * [学习教程](https://github.com/macrozheng/mall-learning)

定制封面页

  <script>    window.$docsify = {      coverpage: true    }  </script>
window.$docsify = {
coverpage: true
    }
</script>

  ![logo](images/mall.svg)  # mall-learning  > mall学习教程，架构、业务、技术要点全方位解析。  此处填写详细简介。  [GitHub](https://github.com/macrozheng/mall-learning)  [Get Started](README.md)images/mall.svg)
  # mall-learning
  > mall学习教程，架构、业务、技术要点全方位解析。

  此处填写详细简介。
  [GitHub](https://github.com/macrozheng/mall-learning)
  [Get Started](README.md)

添加全文搜索

  <script>    window.$docsify = {      search: {        placeholder: '搜索',        noData: '找不到结果!',        depth: 3      },    }  </script>  <script src="//unpkg.com/docsify/lib/plugins/search.js"></script>
window.$docsify = {
search: {
placeholder: '搜索',
noData: '找不到结果!',
depth: 3
      },
    }
</script>
<script src="//unpkg.com/docsify/lib/plugins/search.js"></script>

添加代码高亮

  <script src="//unpkg.com/prismjs/components/prism-bash.js"></script>  <script src="//unpkg.com/prismjs/components/prism-java.js"></script>  <script src="//unpkg.com/prismjs/components/prism-sql.js"></script></script>
<script src="//unpkg.com/prismjs/components/prism-java.js"></script>
<script src="//unpkg.com/prismjs/components/prism-sql.js"></script>

添加一键拷贝代码

  <script src="//unpkg.com/docsify-copy-code"></script></script>

在Github上部署文档

文档地址

https://macrozheng.github.io/mall-learning/

项目源码地址

https://github.com/macrozheng/mall-learning