溫馨提示×
您好，登錄后才能下訂單哦！
點(diǎn)擊 登錄注冊(cè) 即表示同意《億速云用戶服務(wù)條款》
您好，登錄后才能下訂單哦！
這篇文章主要介紹怎么使用Docsify和GitHub Pages創(chuàng)建一個(gè)文檔網(wǎng)站，文中介紹的非常詳細(xì)，具有一定的參考價(jià)值，感興趣的小伙伴們一定要看完！
使用 Docsify 創(chuàng)建文檔網(wǎng)頁(yè)并發(fā)布到 GitHub Pages 上。
文檔是幫助用戶使用開(kāi)源項(xiàng)目一個(gè)重要部分，但它并不總是開(kāi)發(fā)人員的首要任務(wù)，因?yàn)樗麄兛赡芨P(guān)注的是使他們的應(yīng)用程序更好，而不是幫助人們使用它。對(duì)開(kāi)發(fā)者來(lái)說(shuō)，這就是為什么讓發(fā)布文檔變得更容易是如此有價(jià)值的原因。在本教程中，我將向你展示一個(gè)這樣做的方式：將 Docsify 文檔生成器與 GitHub Pages 結(jié)合起來(lái)。
默認(rèn)情況下，GitHub Pages 會(huì)提示用戶使用 Jekyll，這是一個(gè)支持 HTML、CSS 和其它網(wǎng)頁(yè)技術(shù)的靜態(tài)網(wǎng)站生成器。Jekyll 可以從以 Markdown 格式編碼的文檔文件中生成一個(gè)靜態(tài)網(wǎng)站，GitHub 會(huì)自動(dòng)識(shí)別它們的 .md 或 .markdown 擴(kuò)展名。雖然這種設(shè)置很好，但我想嘗試一下其他的東西。
幸運(yùn)的是，GitHub Pages 支持 HTML 文件，這意味著你可以使用其他網(wǎng)站生成工具（比如 Docsify）在這個(gè)平臺(tái)上創(chuàng)建一個(gè)網(wǎng)站。Docsify 是一個(gè)采用 MIT 許可證的開(kāi)源項(xiàng)目，其具有可以讓你在 GitHub Pages 上輕松創(chuàng)建一個(gè)有吸引力的、先進(jìn)的文檔網(wǎng)站的功能。
Docsify
安裝 Docsify 有兩種方法：
鴻蒙官方戰(zhàn)略合作共建——HarmonyOS技術(shù)社區(qū)
通過(guò) NPM 安裝 Docsify 的命令行界面（CLI）。
手動(dòng)編寫(xiě)自己的 index.html。
Docsify 推薦使用 NPM 方式，但我將使用第二種方案。如果你想使用 NPM，請(qǐng)按照快速入門(mén)指南中的說(shuō)明進(jìn)行操作。
我已經(jīng)在該項(xiàng)目的 GitHub 頁(yè)面上發(fā)布了這個(gè)例子的源代碼。你可以單獨(dú)下載這些文件，也可以通過(guò)以下方式克隆這個(gè)存儲(chǔ)庫(kù)。
git clone https://github.com/bryantson/OpensourceDotComDemos
然后 cd 進(jìn)入 DocsifyDemo 目錄。
我將在下面為你介紹這些代碼，它們克隆自我的示例存儲(chǔ)庫(kù)中，這樣你就可以理解如何修改 Docsify。如果你愿意，你也可以從頭開(kāi)始創(chuàng)建一個(gè)新的 index.html 文件，就像 Docsify 文檔中的的示例一樣：
<!-- index.html --> <!DOCTYPE html><html><head> <meta http-equiv="X-UA-Compatible" content="IE=edge,chrome=1"> <meta name="viewport" content="width=device-width,initial-scale=1"> <meta charset="UTF-8"> <link rel="stylesheet" href="//cdn.jsdelivr.net/npm/docsify/themes/vue.css"></head><body> <div id="app"></div> <script> window.$docsify = { //... } </script> <script src="//cdn.jsdelivr.net/npm/docsify/lib/docsify.min.js"></script></body></html>
如果你克隆了我的 GitHub 存儲(chǔ)庫(kù)，并切換到 DocsifyDemo 目錄下，你應(yīng)該看到這樣的文件結(jié)構(gòu)：
File contents in the cloned GitHub
| 文件/文件夾名稱 | 內(nèi)容 |
|---|---|
index.html | 主要的 Docsify 初始化文件，也是最重要的文件 |
_sidebar.md | 生成導(dǎo)航 |
README.md | 你的文檔根目錄下的默認(rèn) Markdown 文件 |
images | 包含了 README.md 中的示例 .jpg 圖片 |
| 其它目錄和文件 | 包含可導(dǎo)航的 Markdown 文件 |
index.html 是 Docsify 可以工作的唯一要求。打開(kāi)該文件，你可以查看其內(nèi)容：
<!-- index.html --> <!DOCTYPE html><html><head> <meta http-equiv="X-UA-Compatible" content="IE=edge,chrome=1"> <meta name="viewport" content="width=device-width,initial-scale=1"> <meta charset="UTF-8"> <link rel="stylesheet" href="//cdn.jsdelivr.net/npm/docsify/themes/vue.css"> <title>Docsify Demo</title></head><body> <div id="app"></div> <script> window.$docsify = { el: "#app", repo: 'https://github.com/bryantson/OpensourceDotComDemos/tree/master/DocsifyDemo', loadSidebar: true, } </script> <script src="//cdn.jsdelivr.net/npm/docsify/lib/docsify.min.js"></script></body></html>這本質(zhì)上只是一個(gè)普通的 HTML 文件，但看看這兩行：
<link rel="stylesheet" href="//cdn.jsdelivr.net/npm/docsify/themes/vue.css">... 一些其它內(nèi)容 ...<script src="//cdn.jsdelivr.net/npm/docsify/lib/docsify.min.js"></script>
這些行使用內(nèi)容交付網(wǎng)絡(luò)（CDN）的 URL 來(lái)提供 CSS 和 JavaScript 腳本，以將網(wǎng)站轉(zhuǎn)化為 Docsify 網(wǎng)站。只要你包含這些行，你就可以把你的普通 GitHub 頁(yè)面變成 Docsify 頁(yè)面。
<body> 標(biāo)簽后的第一行指定了要渲染的內(nèi)容：
<div id="app"></div>
Docsify 使用單頁(yè)應(yīng)用（SPA）的方式來(lái)渲染請(qǐng)求的頁(yè)面，而不是刷新一個(gè)全新的頁(yè)面。
最后，看看 <script> 塊里面的行：
<script> window.$docsify = { el: "#app", repo: 'https://github.com/bryantson/OpensourceDotComDemos/tree/master/DocsifyDemo', loadSidebar: true, }</script>在這個(gè)塊中：
el 屬性基本上是說(shuō)：“嘿，這就是我要找的 id，所以找到它并在那里呈現(xiàn)?！?/p>
改變 repo 值，以確定當(dāng)用戶點(diǎn)擊右上角的 GitHub 圖標(biāo)時(shí)，會(huì)被重定向到哪個(gè)頁(yè)面。
將 loadSideBar 設(shè)置為 true 將使 Docsify 查找包含導(dǎo)航鏈接的 _sidebar.md 文件。
你可以在 Docsify 文檔的配置部分找到所有選項(xiàng)。
接下來(lái)，看看 _sidebar.md 文件。因?yàn)槟阍?nbsp;index.html 中設(shè)置了 loadSidebar 屬性值為 true，所以 Docsify 會(huì)查找 _sidebar.md 文件，并根據(jù)其內(nèi)容生成導(dǎo)航文件。示例存儲(chǔ)庫(kù)中的 _sidebar.md 內(nèi)容是：
<!-- docs/_sidebar.md --> * [HOME](./) * [Tutorials](./tutorials/index) * [Tomcat](./tutorials/tomcat/index) * [Cloud](./tutorials/cloud/index) * [Java](./tutorials/java/index) * [About](./about/index) * [Contact](./contact/index)
這會(huì)使用 Markdown 的鏈接格式來(lái)創(chuàng)建導(dǎo)航。請(qǐng)注意 “Tomcat”、“Cloud” 和 “Java” 等鏈接是縮進(jìn)的；這意味著它們被渲染為父鏈接下的子鏈接。
像 README.md 和 images 這樣的文件與存儲(chǔ)庫(kù)的結(jié)構(gòu)有關(guān)，但所有其它 Markdown 文件都與你的 Docsify 網(wǎng)頁(yè)有關(guān)。
根據(jù)你的需求，隨意修改你下載的文件。下一步，你將把這些文件添加到你的 GitHub 存儲(chǔ)庫(kù)中，啟用 GitHub Pages，并完成項(xiàng)目。
創(chuàng)建一個(gè)示例的 GitHub 存儲(chǔ)庫(kù)，然后使用以下 GitHub 命令檢出、提交和推送你的代碼：
$ git clone 你的 GitHub 存儲(chǔ)庫(kù)位置$ cd 你的 GitHub 存儲(chǔ)庫(kù)位置$ git add .$ git commit -m "My first Docsify!"$ git push
設(shè)置你的 GitHub Pages 頁(yè)面。在你的新 GitHub 存儲(chǔ)庫(kù)中，點(diǎn)擊 “Settings”：
Settings link in GitHub
向下滾動(dòng)直到看到 “GitHub Pages”：
GitHub Pages settings
查找 “Source” 部分：
GitHub Pages settings
點(diǎn)擊 “Source” 下的下拉菜單。通常，你會(huì)將其設(shè)置為 “master branch”，但如果你愿意，也可以使用其他分支：
Setting Source to master branch
就是這樣！你現(xiàn)在應(yīng)該有一個(gè)鏈接到你的 GitHub Pages 的頁(yè)面了。點(diǎn)擊該鏈接將帶你到那里，然后用 Docsify 渲染：
Link to GitHub Pages docs site
它應(yīng)該像這樣：
以上是“怎么使用Docsify和GitHub Pages創(chuàng)建一個(gè)文檔網(wǎng)站”這篇文章的所有內(nèi)容，感謝各位的閱讀！希望分享的內(nèi)容對(duì)大家有幫助，更多相關(guān)知識(shí)，歡迎關(guān)注億速云行業(yè)資訊頻道！
免責(zé)聲明：本站發(fā)布的內(nèi)容（圖片、視頻和文字）以原創(chuàng)、轉(zhuǎn)載和分享為主，文章觀點(diǎn)不代表本網(wǎng)站立場(chǎng)，如果涉及侵權(quán)請(qǐng)聯(lián)系站長(zhǎng)郵箱：is@yisu.com進(jìn)行舉報(bào)，并提供相關(guān)證據(jù)，一經(jīng)查實(shí)，將立刻刪除涉嫌侵權(quán)內(nèi)容。
億速云公眾號(hào)
手機(jī)網(wǎng)站二維碼