還記得我在上週發的《V2.0 版本的 JavaGuide 面試突擊版來啦!帶着它的在線閱讀版本來啦!》這篇文章中答應手把手教大家搭建一下下面一樣的文檔類型網站不?
這篇文章 Guide 哥就手把手教大家搭建一個像下面這樣的文檔類型的網站,你可以用來當做項目的說明文檔,也還可以當做自己專屬的知識小倉庫。
官網教程的也很詳細了,地址在這裏:https://docsify.js.org/#/zh-cn/quickstart ,不過我的這篇教程比較貼合實際使用。
下面演示的所有內容的源文件在這裏:https://github.com/Snailclimb/docsify-demo
最終效果展示地址:https://snailclimb.gitee.io/docsify-demo/#/
一.前置條件
- 確保自己電腦下載安裝了 NPM 並且使用這個命令:
npm i docsify-cli -g
安裝了 docsify-cli 這個工具 。 - 確保自己有一個 Github 賬號(碼雲賬號爲非必選項,有的話更好)。
二.初始化項目並預覽
1.新建一個文件夾:mkdir docsify-demo
2.進入文件夾並運行 docsify 初始化命令:cd docsify-demo
-> docsify init ./
你會發現 docsify-demo 文件夾下面多了下面這些文件,一一爲你解釋一下它們是幹嘛的!
3.本地預覽網站:docsify serve ./
然後訪問:http://localhost:3000/
三.給我們的項目增加點顏色
建議 clone 一下我的倉庫: https://github.com/Snailclimb/docsify-demo ,在本地運行一下 ,這是一個比較典型的使用 docsify 搭建的網站,可以作爲參考。如果你們想搭建一個不錯的文檔網站的話,可以在我的這個基礎上去改。
3.1 修改配置文件 index.html
主要配置了文檔網站的名字以及開啓了一些配置選項。
<!DOCTYPE html>
<html lang="en">
<head>
<meta charset="UTF-8">
<title>docsify-demo</title>
<meta http-equiv="X-UA-Compatible" content="IE=edge,chrome=1" />
<meta name="description" content="Description">
<meta name="viewport"
content="width=device-width, user-scalable=no, initial-scale=1.0, maximum-scale=1.0, minimum-scale=1.0">
<link rel="stylesheet" href="//unpkg.com/docsify/lib/themes/vue.css">
</head>
<body>
<div id="app"></div>
<!-- docsify-edit-on-github -->
<script src="//unpkg.com/docsify-edit-on-github/index.js"></script>
<script>
window.$docsify = {
name: 'docsify-demo',
repo: 'https://github.com/Snailclimb/JavaGuide-Interview',
maxLevel: 5,//最大支持渲染的標題層級
subMaxLevel: 3,
homepage: 'README.md',
coverpage: true,
loadSidebar: true,
auto2top: true,//切換頁面後是否自動跳轉到頁面頂部
}
</script>
<script src="//unpkg.com/docsify/lib/docsify.min.js"></script>
</body>
</html>
3.2 添加側邊欄文件
在第一步中,我們在已經開啓了側邊欄選項:
loadSidebar: true
但是,僅僅這樣還不行,我們需要定義一個名爲 _sidebar.md
的文件,文件的內容就是我們側邊欄的內容。
如下圖所示,我們定義了一個側邊欄,並且爲它添加了一些內容:
一般建議將文檔放進 docs 文件下面,可以參考我的倉庫:https://github.com/Snailclimb/docsify-demo
修改完成之後,你就會發現我們的文檔網站多了側邊欄,你點擊側邊欄對應的內容在右邊顯示。
3.3 修改主頁內容
修改 REDME.md,內容如下:
然後我們的文檔網站的主頁就變成了這樣:
3.4 添加一個封面
第一步中,我們在已經開啓了封面選項:
coverpage: true
爲了能讓我們的文檔網站有封面,我們還需要新建一個名字爲 _coverpage.md
的文件,內容如下
然後,我們再打開網站的時候,就有了封面,如下圖所示:
四.一些有用的插件
我下面簡單介紹幾個我覺得比較實用的插件,更多插件的話在這裏:https://docsify.js.org/#/zh-cn/plugins 。
4.1 增加 Java 代碼高亮
手動引入 Java 代碼高亮的插件:
<!--Java代碼高亮-->
<script src="//unpkg.com/prismjs/components/prism-java.js"></script>
4.2 增加全文搜索功能
引入插件:
<!--全文搜索,直接用官方提供的無法生效-->
<script src="https://cdn.bootcss.com/docsify/4.5.9/plugins/search.min.js">
配置一下:
<script>
window.$docsify = {
......
//全文搜索
search: {
maxAge: 86400000, // 過期時間,單位毫秒,默認一天
paths: 'auto',
placeholder: '搜索',
noData: '找不到結果',
// 搜索標題的最大程級, 1 - 6
depth: 3,
},
}
</script>
然後我們的文檔網站就有全文搜索功能了:
4.3 複製代碼到剪切板
引入插件即可!
<!-- 複製代碼到剪貼板 -->
<script src="//unpkg.com/docsify-copy-code"></script>
4.4 圖片縮放和字數統計
引入下面兩個插件即可!
<!-- 圖片縮放 -->
<script src="//unpkg.com/docsify/lib/plugins/zoom-image.js"></script>
<!-- 字數統計 -->
<script src="//unpkg.com/docsify-count/dist/countable.js"></script>
4.5 edit on github
做如下配置,注意修改爲你自己的路徑。
<script>
window.$docsify = {
......
plugins: [
EditOnGithubPlugin.create('https://github.com/Snailclimb/JavaGuide-Interview/blob/master/')
],
}
</script>
然後我們的每個頁面都出來了 "Edit on github" 選項,你點擊之後就會跳到 Github 對應的頁面編輯。
五.部署
5.1 部署到 Github
1.Github 新建一個倉庫,這一步就不說了。
2.把項目提交上去
3.開啓 Github Pages
然後你的項目就能在線訪問了!
5.2 同步到碼雲提高國內訪問速度
1.導入 Github 項目
注意把下面的是否開源勾選爲公開,不然別人無法訪問。
2.選擇 Gitee Pages 服務
3.收穫喜悅的成果
作者介紹: Github 70k Star 項目 JavaGuide(公衆號同名) 作者。每週都會在公衆號更新一些自己原創乾貨。公衆號後臺回覆“1”領取Java工程師必備學習資料+面試突擊pdf。