使用docsify 寫開源文檔

使用docsify 寫開源文檔

官網:https://docsify.js.org/#/

docsify 是一個動態生成文檔網站的工具。不同於 GitBook、Hexo 的地方是它不會生成將 .md 轉成 .html 文件,所有轉換工作都是在運行時進行。

這將非常實用,如果只是需要快速的搭建一個小型的文檔網站,或者不想因為生成的一堆 .html 文件「污染」 commit 記錄,只需要創建一個 index.html 就可以開始寫文檔而且直接部署在 GitHub Pages

mark

一、初始化項目

1.1 安裝Node.js

1.2 安裝docsify-cli工具

命令行執行:

npm i docsify-cli -g  

會在這個路徑下

​ C:UsersAdministratorAppDataRoamingnpmnode_modules

生成 docsify-cli 文件夾

mark

1.3 初始化文檔結構

先創建一個本地文件夾docs,然後執行命令

docsify init ./docs  

會生成如下目錄:

 -| docs/      -| .nojekyll 用於阻止 GitHub Pages 會忽略掉下劃線開頭的文件      -| index.html 入口文件      -| README.md 會做為主頁內容渲染  

直接編輯 docs/README.md 就能更新網站內容

遇到的問題:

  1. 初始化docsify文檔不成功

    升級node.js之後就成功了

mark

1.4 本地實時預覽

docsify serve docs  

默認訪問 http://localhost:3000

  • README文件:
# Headline  > An awesome project.  
  • 預覽效果:

mark

二、訂製導航欄

2.1 訂製導航欄

<script>      window.$docsify = {        name: 'PassJava-Learning',        repo: 'https://github.com/Jackson0714/PassJava-Platform',        loadNavbar: true,        loadSidebar: true, // 載入自定義側邊欄        maxLevel: 2, // 默認情況下會抓取文檔中所有標題渲染成目錄,可配置最大支援渲染的標題層級。        subMaxLevel: 4, // 生成目錄的最大層級        mergeNavbar: true, // 小屏設備下合併導航欄到側邊欄        alias: { // 定義路由別名,可以更自由的定義路由規則。 支援正則          '/.*/_sidebar.md': '/_sidebar.md',//防止意外回退          '/.*/_navbar.md': '/_navbar.md'        }      }    </script>  
  • 添加_sidebar.md文件來配置側邊欄
* 介紹      * [PassJava 功能介紹](introduction/PassJava_introduction_01.md)      * [PassJava 必備知識](introduction/PassJava_introduction_02.md)  * PassJava 架構篇    * SpringBoot 學習篇      * [SpringBoot整合JDBC](springboot-tech/spring-boot-05-data-jdbc.md)      * [SpringBoot整合Druid](springboot-tech/spring-boot-06-data-druid.md)      * [SpringBoot整合MyBatis](springboot-tech/spring-boot-07-data-mybatis.md)    * 工具篇      * [圖床神器配置](tools/圖床神器配置.md)      * [使用docsify寫開源文檔](tools/使用docsify寫開源文檔.md)      * [我的常用工具](tools/我的常用工具.md)    * 想法      * [打造一款刷Java知識的小程式2](idea/打造一款刷Java知識的小程式2.md)  
  • 添加_navbar.md文件來配置頂部導航欄
* 演示    * [後台管理]()    * [小程式端]()    * 項目地址    * [後台平台](https://github.com/Jackson0714/PassJava-Platform)    * [後台管理](https://github.com/Jackson0714/PassJava-Portal)    * [學習教程](https://github.com/Jackson0714/PassJava-Learning)  
  • 查看導航欄效果

    mark

三、訂製封面頁

  • 在index.html中添加封面頁的配置
<script>      window.$docsify = {        coverpage: true      }   </script>  
  • 添加_coverpage.md文件來配置封面頁
![logo](images/logo.png)    # PassJava-Learning    > PassJava 學習教程,架構、業務、技術要點全方位解析。    PassJava 是一款幫助Java面試的開源系統,  可以用零碎時間利用小程式查看常見面試題,夯實Java基礎。  採用流行的技術,如 SpringBoot、MyBatis、Redis、 MySql、  MongoDB、 RabbitMQ、Elasticsearch,採用Docker容器化部署。    [GitHub](https://github.com/jackson0714/PassJava-Learning)  [Get Started](README.md)  
  • 查看封面效果

    mark

四、添加全文搜索

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

<script>      window.$docsify = {        search: {          placeholder: '搜索',          noData: '找不到結果!',          depth: 3        },      }   </script>  

mark

五、添加程式碼高亮

在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>  

六、添加一鍵拷貝程式碼

在index.html中添加一鍵拷貝程式碼的配置

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

七、在Github上部署文檔

八、部署到雲伺服器

1.添加nginx配置文件

  • 執行命令
sudo vim /etc/nginx/conf.d/pass_java_learning.conf  
  • 更新配置資訊
server {      listen       80;      server_name  tech.jayh.club;        location / {          root   /home/ubuntu/jay/passjava/passjava-learning/PassJava-Learning/docs;          index  index.html;      }  }  

2.域名解析

主機記錄:tech

記錄類型:A

線路類型:默認

記錄值:主機IP地址

mark

3.訪問 tech.jay.club

4. 遇到的問題

  • 404 未找到頁面

    可以通過命令查看錯誤日誌

    cat /var/log/nginx/error.log  

    原因:docs 路徑配置錯誤,下面三種路徑都報404

    ​ /home/jay/passjava/passjava-learning/PassJava-Learning/docs;

    ​ /jay/passjava/passjava-learning/PassJava-Learning/docs;

    ​ ~/jay/passjava/passjava-learning/PassJava-Learning/docs;

    解決方案:

    改成 /home/ubuntu/jay/passjava/passjava-learning/PassJava-Learning/docs

  • 403 限制訪問

    修改nginx.conf文件

    sudo vim nginx.conf  

    user www-data 改為 user root

    重啟 nginx 服務

    sudo service nginx restart  

公眾號

mark