如何寫出優雅的開源項目文檔

摘要

mall項目是我去年寫的SpringBoot實戰電商項目，如今在Github上面已經有18k+star。去年12月份的時候，mall項目只有一些必要的說明文檔和部署文檔。mall項目涉及到的技術棧比較普遍，業務也比較複雜，卻沒有系統的學習教程。今年5月份的時候，我開始完善整套學習教程，目前已經更新了三十餘篇。最近使用docsify搭建了一個小型的文檔網站，但願你們能有更好的閱讀體驗。本文將介紹如何使用docsify來寫開源項目文檔。

項目文檔演示

使用docsify來寫項目文檔

docsify簡介

docsify是一個動態生成網站的工具，它不會將.md文件轉化爲.html文件從而污染你的Github提交記錄，全部轉化都將在運行時完成。若是你須要快速搭建一個小型文檔網站，這將很是實用。

初始化項目

安裝nodejs

• 下載地址：nodejs.org/dist/v8.9.4…
• 下載完成後直接安裝便可。

安裝docsify-cli工具

• 在命令行中執行以下命令：

npm i docsify-cli -g
複製代碼

• 安裝完成後能夠方便地在本地實時預覽所編輯的文檔。

初始化項目結構

• 新建一個docs文件夾，而後執行以下命令：

docsify init ./docs
複製代碼

• docsify會建立以下結構的目錄：

-| docs/
    -| .nojekyll
    -| index.html
    -| README.md
複製代碼

實時預覽

• 在命令行中輸入以下命令：

docsify serve docs
複製代碼

• 訪問該地址便可查看效果：http://localhost:3000/

定製側邊欄

• 在index.html中添加側邊欄的配置：

<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>
複製代碼

• 添加_sidebar.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)
複製代碼

• 這樣就能夠生成一個二級的側邊欄：

定製導航欄

• 在index.html中添加導航欄的配置：

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

• 添加_navbar.md文件來配置導航欄：

* 演示
 * [後臺管理](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)
複製代碼

• 這樣就能夠在右上角生成兩個導航欄：

定製封面頁

• 在index.html中添加封面頁的配置：

<script> window.$docsify = { coverpage: true } </script>
複製代碼

• 添加_coverpage.md文件來配置封面頁：

![logo](images/mall.svg)
  # mall-learning
  > mall學習教程，架構、業務、技術要點全方位解析。

  此處填寫詳細簡介。
  [GitHub](https://github.com/macrozheng/mall-learning)
  [Get Started](README.md)
複製代碼

• 查看封面頁效果：

添加全文搜索

• 在index.html中添加全文搜索的配置：

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

• 查看全文搜索效果：

添加代碼高亮

• 在index.html中添加代碼高亮的配置：

<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>
複製代碼

• 其餘支持高亮語言請參考：github.com/PrismJS/pri…
• 查看代碼高亮效果：

添加一鍵拷貝代碼

• 在index.html中添加一鍵拷貝代碼的配置：

<script src="//unpkg.com/docsify-copy-code"></script>
複製代碼

• 查看一鍵拷貝代碼效果：

在Github上部署文檔

• 首先將你的代碼提交到Github上去；
• 而後點擊項目的Settings按鈕：

• 開啓GitHub Pages服務：

文檔地址

macrozheng.github.io/mall-learni…

項目源碼地址

github.com/macrozheng/…

公衆號

mall項目全套學習教程連載中，關注公衆號第一時間獲取。