如何為你的項(xiàng)目快速搭建文檔網(wǎng)站？（基于GitHub Pages和RunDocs） 如何將基于Github Pages的網(wǎng)頁(yè)映射到自定義域名上？【重要且難纏，歡迎討論】如何處理當(dāng)前境內(nèi)運(yùn)營(yíng)商將*" />

国产成人精品无码青草_亚洲国产美女精品久久久久∴_欧美人与鲁交大毛片免费_国产果冻豆传媒麻婆精东

15158846557 或 在線咨詢 在線咨詢
15158846557 或 在線咨詢
所在位置： 首頁(yè) > 營(yíng)銷資訊 > 網(wǎng)站運(yùn)營(yíng) > 用Github Page快速創(chuàng)建項(xiàng)目文檔網(wǎng)站

用Github Page快速創(chuàng)建項(xiàng)目文檔網(wǎng)站

時(shí)間：2023-08-14 15:54:01 | 來(lái)源：網(wǎng)站運(yùn)營(yíng)

時(shí)間：2023-08-14 15:54:01 來(lái)源：網(wǎng)站運(yùn)營(yíng)

用Github Page快速創(chuàng)建項(xiàng)目文檔網(wǎng)站：本文分為3個(gè)部分：

  1. 如何為你的項(xiàng)目快速搭建文檔網(wǎng)站？（基于GitHub Pages和RunDocs）
  2. 如何將基于Github Pages的網(wǎng)頁(yè)映射到自定義域名上？
  3. 【重要且難纏，歡迎討論】如何處理當(dāng)前境內(nèi)運(yùn)營(yíng)商將*.http://github.io錯(cuò)誤的解析到127.0.0.1導(dǎo)致基于Github Page的網(wǎng)頁(yè)很難在境內(nèi)訪問(wèn)的問(wèn)題（訪問(wèn)報(bào)錯(cuò)*.http://github.io拒絕訪問(wèn)/拒絕連接）



1. 如何為你的項(xiàng)目快速搭建文檔網(wǎng)站？（基于GitHub Pages和RunDocs）

如果你也遇到了下列困難，那么閱讀這一章節(jié)可以幫你省下很多初學(xué)者走彎路的時(shí)間：

基于GitHub Pages（網(wǎng)頁(yè)服務(wù)）和RunDocs（網(wǎng)站模板）可以讓你在5分鐘內(nèi)就建好你的項(xiàng)目文檔網(wǎng)站！??！而且有動(dòng)態(tài)導(dǎo)航欄、支持較復(fù)雜的文檔結(jié)構(gòu)?。?！而且基本沒(méi)有學(xué)習(xí)成本！??！基本上唯一需要的就是熟悉markdown和github的日常使用了。在這里感謝Github Page和RunDocs ！orzzzzz

RunDocs的模板如下圖，這種風(fēng)格在很多知名Python庫(kù)的文檔網(wǎng)頁(yè)上都可以看到，依照本文可以快速生成下面樣式的文檔網(wǎng)站。




建站步驟分成如下幾步：

1.1 Github Page設(shè)置

注意：

首先，在項(xiàng)目的repository新建文件夾`/docs`創(chuàng)建分支`gh-pages`，用于存放網(wǎng)頁(yè)相關(guān)的文件（如果沒(méi)有repo參考github page官網(wǎng)教程）；

隨后，在項(xiàng)目repo的主頁(yè)點(diǎn)擊Settings，進(jìn)入Options界面向下拉，找到"Github Pages"部分，將publishing source設(shè)置為在上一步新建的docs文件夾或gh-pages分支，隨后點(diǎn)擊choose a theme為網(wǎng)頁(yè)選擇主題，隨便選個(gè)默認(rèn)的就好，后面反正會(huì)改成RunDocs的主題，完成后就可以看到只有標(biāo)題的網(wǎng)頁(yè)了~下面的custom domain是用來(lái)設(shè)置github page的自定義域名的，目前先不用理會(huì)。

現(xiàn)在你的Github Page網(wǎng)站就初步建好啦（雖然還沒(méi)內(nèi)容），成功的標(biāo)志是repo的setting/options/Github Pages部分，有一條高亮的消息“Your site is published at ......”，這個(gè)就是目前網(wǎng)頁(yè)的網(wǎng)址了~

1.2 RunDocs設(shè)置

RunDocs和jekyll的官方文檔其實(shí)非常詳細(xì)，使用方法也非常簡(jiǎn)單，但是對(duì)于初學(xué)者而言缺失了0到1的部分（可能作者覺(jué)得這部分太self-explained了），筆者花了些時(shí)間才弄清楚應(yīng)該怎么組織多層級(jí)的網(wǎng)頁(yè)，希望下面的部分能作為官方文檔的補(bǔ)充，讓剛起步的你走的輕松點(diǎn)~

此前介紹了docs文件夾和gh-pages分支兩種存儲(chǔ)網(wǎng)頁(yè)相關(guān)文件的方式，下面均以docs為例介紹。

首先將項(xiàng)目pull到本地方便操作，隨后按RunDocs官方教程，在docs文件夾中創(chuàng)建下面四個(gè)文件（Gemfile和Makefile沒(méi)有后綴），這些文件設(shè)置了網(wǎng)頁(yè)的主題等信息，如果docs已經(jīng)有了同名文件可以直接覆蓋：

（PS, 官方教程Gemfile · RunDocs結(jié)合官方Github示例rundocs.io食用更佳）

這四個(gè)文件的內(nèi)容如下：

Gemfile

source "https://gems.ruby-china.com"gem "jekyll-rtd-theme"gem "github-pages", group: :jekyll_pluginsMakefile

DEBUG=JEKYLL_GITHUB_TOKEN=blank PAGES_API_URL=http://0.0.0.0default: @gem install jekyll bundler && bundle installupdate: @bundle updateclean: @bundle exec jekyll cleanbuild: clean @${DEBUG} bundle exec jekyll build --profile --config _config.yml,.debug.ymlserver: clean @${DEBUG} bundle exec jekyll server --livereload --config _config.yml,.debug.yml_config.yml

title: Your project namelang: endescription: a catchy description for your projectremote_theme: rundocs/jekyll-rtd-themereadme_index: with_frontmatter: trueexclude: - Makefile - CNAME - Gemfile - Gemfile.lock.debug.yml

remote_theme: falsetheme: jekyll-rtd-theme

1.3 文檔層級(jí)設(shè)計(jì)和文檔內(nèi)容文件放置

下面會(huì)結(jié)合實(shí)際案例，介紹一下RunDocs模板的核心玩法~

（如果有不夠直觀的地方，可以閱讀的同時(shí)，參考我的Github Page或RunDocs官方案例）

首先/docs文件夾下，放置一個(gè)README.md文件，訪問(wèn)者一點(diǎn)開(kāi)頁(yè)面，就能看到這個(gè)markdown文檔的內(nèi)容，通?？捎梅乓幌抡麄€(gè)項(xiàng)目的簡(jiǎn)介以及子頁(yè)面的跳轉(zhuǎn)鏈接，鏈接的語(yǔ)法用[文本](鏈接)；




/docs文件夾的子文件夾對(duì)應(yīng)了左側(cè)導(dǎo)航欄的一級(jí)頁(yè)面（下圖紅圈），下面介紹如何創(chuàng)建。

下圖展示了/docs文件夾的全貌，Chinese, English, Notebooks, API均為一級(jí)頁(yè)面，分別對(duì)應(yīng)上圖的四個(gè)一級(jí)頁(yè)面“中文文檔”、“English Document”、“Example Notebooks”、“API Reference”。下面將介紹如何創(chuàng)建一級(jí)頁(yè)面和下屬的二級(jí)頁(yè)面

子文件夾中的README.md文件是一級(jí)頁(yè)面命名和排序的關(guān)鍵：

---sort: 1---為一級(jí)頁(yè)面創(chuàng)建二級(jí)子頁(yè)面

下圖展示了一級(jí)頁(yè)面“中文文檔”文件夾，README.md用于此一級(jí)頁(yè)面的排序和命名，1.intro.md和2.usage.md分別是兩個(gè)子頁(yè)面（文檔開(kāi)頭的sort分別為1和2，代表子頁(yè)面的排序），如果需要，可以去Github查看詳細(xì)文件內(nèi)容 文件夾“中文文檔”




2. 如何將基于Github Pages的網(wǎng)頁(yè)映射到自定義域名上？

首先要有一個(gè)經(jīng)實(shí)名認(rèn)證、配置了DNS解析服務(wù)的域名，可以在騰訊云/阿里云等服務(wù)商注冊(cè)和配置。我注冊(cè)的域名是bubu.blue

為你的項(xiàng)目設(shè)計(jì)一個(gè)二級(jí)域名，我的是scorecard-bundle.bubu.blue,填寫(xiě)到項(xiàng)目的repo的setting/options/Github Pages/custom domain部分，點(diǎn)save, 勾選enforce https使得最終的網(wǎng)站可以通過(guò)https訪問(wèn)。

在docs文件夾下新建CNAME文件，無(wú)后綴，文件內(nèi)容就是二級(jí)域名：scorecard-bundle.bubu.blue。

最后，在域名的服務(wù)商的控制臺(tái)的域名解析頁(yè)面，添加CNAME解析記錄，主機(jī)填二級(jí)域名的名稱（我的例子中是scorecard-bundle)，映射的目標(biāo)是第一步已經(jīng)創(chuàng)建成功的github page的域名 xxxx.github.io. （注意結(jié)尾要跟一個(gè)英文句號(hào)）

然后等最多10分鐘，就可以通過(guò)自定義的域名訪問(wèn)網(wǎng)頁(yè)啦~成功的標(biāo)志跟之前一樣，repo的setting/options/Github Pages部分，有一條高亮的消息“Your site is published at ......”

注意?。。∽罱硟?nèi)訪問(wèn)Github Page有時(shí)候會(huì)有問(wèn)題，解決方法請(qǐng)繼續(xù)往下看~

3.【重要且難纏，歡迎討論】如何處理當(dāng)前境內(nèi)運(yùn)營(yíng)商將*.http://github.io錯(cuò)誤的解析到127.0.0.1導(dǎo)致基于Github Page的網(wǎng)頁(yè)很難在境內(nèi)訪問(wèn)的問(wèn)題（訪問(wèn)報(bào)錯(cuò)*.http://github.io拒絕訪問(wèn)/拒絕連接）


筆者搭了github page后通過(guò)自定義域名解析到了自己的二級(jí)域名上，發(fā)現(xiàn)不用vpn經(jīng)常就訪問(wèn)不了（訪問(wèn)報(bào)錯(cuò)xxxx拒絕訪問(wèn)/拒絕連接），經(jīng)過(guò)查資料和研究，問(wèn)題的原因應(yīng)該是http://xxxx.github.io這個(gè)域名被解析成本地ip 127.0.0.1（雖然網(wǎng)站解析到了自己的域名，但背后還是github page的github.io域名），目前我按下面的方法設(shè)置一下域名解析就解決了，但我在這個(gè)領(lǐng)域比較小白，不確定這么做會(huì)不會(huì)有什么隱患，比如IP過(guò)段時(shí)間會(huì)不會(huì)失效？。。。先分享出來(lái) ，歡迎大家指正。




解決方案：github page自定義域名需要在域名提供商的控制臺(tái)設(shè)置CNAME的解析，但有的運(yùn)營(yíng)商會(huì)吧http://xxxx.github.io解析成127.0.0.1導(dǎo)致無(wú)法訪問(wèn)，我們可以先確定http://xxxx.github.io的真實(shí)ip，為境內(nèi)用戶添加映射到這個(gè)真實(shí)ip的A記錄（線路選境內(nèi)，因?yàn)橹饕蔷硟?nèi)訪問(wèn)有這個(gè)問(wèn)題，境外可以正常訪問(wèn)），然后問(wèn)題就解決了~ 我是通過(guò)站長(zhǎng)之家查詢到我的域名對(duì)應(yīng)了4個(gè)IP，把其中的兩個(gè)設(shè)置成了境內(nèi)的A記錄解析（騰訊云的免費(fèi)DNS解析最多兩個(gè)A記錄）

PS: 原來(lái)的CNAME解析可以保留，所以我現(xiàn)在為這個(gè)二級(jí)域名設(shè)置了3個(gè)解析，一個(gè)CNAME解析到http://xxx.github.io，兩個(gè)針對(duì)境內(nèi)的A解析到http://xxx.github.io對(duì)應(yīng)的兩個(gè)IP上

PPS: 個(gè)人猜想，很多博客正?？赡苁怯捎谟成涞搅艘患?jí)域名上，直接添加了A記錄的解析所以就避開(kāi)了運(yùn)營(yíng)商把http://xxx.github.io錯(cuò)誤的解析為127.0.0.1的問(wèn)題

關(guān)鍵詞：項(xiàng)目,創(chuàng)建

74
73
25
news

版權(quán)所有? 億企邦 1997-2025 保留一切法律許可權(quán)利。

為了最佳展示效果，本站不支持IE9及以下版本的瀏覽器，建議您使用谷歌Chrome瀏覽器。 點(diǎn)擊下載Chrome瀏覽器
關(guān)閉