整合營銷服務商
電腦端+手機端+微信端=數據同步管理
免費咨詢熱線：
電腦端+手機端+微信端=數據同步管理
免費咨詢熱線：
用 Docsify 創建文檔網頁并發布到 GitHub Pages 上。
? 來源：linux.cn ? 作者：Bryant Son ? 譯者：Xingyu.Wang ?
（本文字數：5192，閱讀時長大約：6 分鐘）
文檔是幫助用戶使用開源項目一個重要部分，但它并不總是開發人員的首要任務，因為他們可能更關注的是使他們的應用程序更好，而不是幫助人們使用它。對開發者來說，這就是為什么讓發布文檔變得更容易是如此有價值的原因。在本教程中，我將向你展示一個這樣做的方式：將 Docsify 文檔生成器與 GitHub Pages 結合起來。
默認情況下，GitHub Pages 會提示用戶使用 Jekyll ，這是一個支持 HTML、CSS 和其它網頁技術的靜態網站生成器。Jekyll 可以從以 Markdown 格式編碼的文檔文件中生成一個靜態網站，GitHub 會自動識別它們的 .md 或 .markdown 擴展名。雖然這種設置很好，但我想嘗試一下其他的東西。
幸運的是，GitHub Pages 支持 HTML 文件，這意味著你可以使用其他網站生成工具（比如 Docsify）在這個平臺上創建一個網站。Docsify 是一個采用 MIT 許可證的開源項目，其具有可以讓你在 GitHub Pages 上輕松創建一個有吸引力的、先進的文檔網站的 功能 。
Docsify
安裝 Docsify 有兩種方法：
Docsify 推薦使用 NPM 方式，但我將使用第二種方案。如果你想使用 NPM，請按照 快速入門指南 中的說明進行操作。
我已經在 該項目的 GitHub 頁面 上發布了這個例子的源代碼。你可以單獨下載這些文件，也可以通過以下方式 克隆這個存儲庫 。
git clone https://github.com/bryantson/OpensourceDotComDemos
然后 cd 進入 DocsifyDemo 目錄。
我將在下面為你介紹這些代碼，它們克隆自我的示例存儲庫中，這樣你就可以理解如何修改 Docsify。如果你愿意，你也可以從頭開始創建一個新的 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 存儲庫 ，并切換到 DocsifyDemo 目錄下，你應該看到這樣的文件結構：
File contents in the cloned GitHub
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">
<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>
這本質上只是一個普通的 HTML 文件，但看看這兩行：
<link rel="stylesheet" href="//cdn.jsdelivr.net/npm/docsify/themes/vue.css">
... 一些其它內容 ...
<script src="//cdn.jsdelivr.net/npm/docsify/lib/docsify.min.js"></script>
這些行使用內容交付網絡（CDN）的 URL 來提供 CSS 和 JavaScript 腳本，以將網站轉化為 Docsify 網站。只要你包含這些行，你就可以把你的普通 GitHub 頁面變成 Docsify 頁面。
<body> 標簽后的第一行指定了要渲染的內容：
<div id="app"></div>
Docsify 使用 單頁應用 （SPA）的方式來渲染請求的頁面，而不是刷新一個全新的頁面。
最后，看看 <script> 塊里面的行：
<script>
window.$docsify = {
el: "#app",
repo: 'https://github.com/bryantson/OpensourceDotComDemos/tree/master/DocsifyDemo',
loadSidebar: true,
}
</script>
在這個塊中：
你可以在 Docsify 文檔的 配置 部分找到所有選項。
接下來，看看 _sidebar.md 文件。因為你在 index.html 中設置了 loadSidebar 屬性值為 true，所以 Docsify 會查找 _sidebar.md 文件，并根據其內容生成導航文件。示例存儲庫中的 _sidebar.md 內容是：
<!-- 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)
這會使用 Markdown 的鏈接格式來創建導航。請注意 “Tomcat”、“Cloud” 和 “Java” 等鏈接是縮進的；這意味著它們被渲染為父鏈接下的子鏈接。
像 README.md 和 images 這樣的文件與存儲庫的結構有關，但所有其它 Markdown 文件都與你的 Docsify 網頁有關。
根據你的需求，隨意修改你下載的文件。下一步，你將把這些文件添加到你的 GitHub 存儲庫中，啟用 GitHub Pages，并完成項目。
創建一個示例的 GitHub 存儲庫，然后使用以下 GitHub 命令檢出、提交和推送你的代碼：
$ git clone 你的 GitHub 存儲庫位置
$ cd 你的 GitHub 存儲庫位置
$ git add .
$ git commit -m "My first Docsify!"
$ git push
設置你的 GitHub Pages 頁面。在你的新 GitHub 存儲庫中，點擊 “Settings”：
Settings link in GitHub
向下滾動直到看到 “GitHub Pages”：
GitHub Pages settings
查找 “Source” 部分：
GitHub Pages settings
點擊 “Source” 下的下拉菜單。通常，你會將其設置為 “master branch”，但如果你愿意，也可以使用其他分支：
Setting Source to master branch
就是這樣！你現在應該有一個鏈接到你的 GitHub Pages 的頁面了。點擊該鏈接將帶你到那里，然后用 Docsify 渲染：
Link to GitHub Pages docs site
它應該像這樣：
Example Docsify site on GitHub Pages
通過編輯一個 HTML 文件和一些 Markdown 文本，你可以用 Docsify 創建一個外觀精美的文檔網站。你覺得怎么樣？請留言，也可以分享其他可以和 GitHub Pages 一起使用的開源工具。
via: opensource.com
作者： Bryant Son 選題： lujun9972 譯者： wxy 校對： wxy
本文由 LCTT 原創編譯， Linux中國 榮譽推出
頁設計，是一項處理小型網站的絕佳技巧，甚至有些網站你可能認為一張頁面搞不定，也同樣適用。從易于維護，到減少帶寬占用，使用單頁網站的好處不勝枚舉。
假如你應對的是個小型網站，通常只有幾個頁面的那種，可以考慮使用單頁設計，看看它是否能簡化項目，對用戶更加友好。繼續閱讀，你將了解它的益處，何時使用（或不該使用），還有一些你該遵循的絕佳慣例。
很顯然，單頁設計并非所有項目的理想選擇。但假如可能的話，有一大堆理由使用它。
默認情況下，用戶要瀏覽單頁網站，只要知道如何滾動就行。你也可以加入箭頭或其他瀏覽暗示，但除了少數例外，其實滾動就足以讓用戶在各部分間穿行。
完全不用擔心用戶身陷多層導航中，無休止地尋找他們所要的東西。如果頁面上有多個部分，頁頭或其他導航鏈接通常很有幫助，不過即使沒有它們，網站仍然是可用的。
這點并非既成事實，編碼良好的單頁網站，或許編寫起來比多頁網站更快。設計過程有時可以花更少的時間，盡管這取決于單頁網站的復雜程度。
一旦你腦海中有基本的布局，單頁網站還能利用某些特定的設計約束來加快進程。尤其較之于多頁網站而言，單頁網站各個部分要保持無縫銜接。如果你已經明確哪些能做哪些不能，這類約束的確能加速頁面開發。
維護也更簡單。當你只需要處理一個頁面，維護工作就大大簡化了，只要網站本身編碼良好。
這條構筑了上面一點。當你只有一個頁面要處理，你不得不把一切簡化為它們最基本的形態。不再需要一頁頁毫無用處的市場宣傳。你必須直截了當、開門見山。
高質量的站內鏈接，是網站在搜索引擎中的表現的重要組成部分。盡管搜索引擎并不是很多網站必須的最大流量源，它們仍然重要。
單頁網站的鏈接總是指向自己。搜索引擎抓取時，這可以增加網站的權重。
單頁網站往往從敘事角度出發，這點多頁網站可不擅長。這可以促進轉換，激發用戶采取行動。
人們習慣于聆聽故事，不論在線上還是線下，所以這點有著顯而易見的用戶體驗優勢。我們兒時就開始閱讀和聽故事，于我們而言，這是自然而然的事情。
再也不需要組織一列列數不清的頁面和子頁面了。無需多慮每個頁面是父級還是子級。也沒有龐雜的導航菜單和子菜單。所有都在一頁上。是要包含導航鏈接，還是讓用戶滾動，這取決于你，就看是否有助于提升用戶體驗。網站如果有多個頁面，是絕對不會這么考慮的。
盡管不像從前，對服務器而言已經不成問題，不過想想近年來有多少用戶通過移動設備訪問你的網站。減少網站的帶寬占用，會贏得流量有限的用戶的感激。
當然，響應式設計不只限于單頁網站。但即使采用了響應式設計，網站越復雜，讓它適應小屏幕還是愈發困難。單頁網站并不復雜，這是必然的。運用響應式設計總體來說更容易。簡化導航和類似改變，也更容易成就適用于小屏幕的設計。
視覺差滾動可能是互聯網中發生過的最美妙的事情，也可能是個被濫用的噱頭，來蹂躪我們瀏覽器，這取決于你怎么看。無論你站在哪一方，它似乎近期并不會消失。
就我而言，我希望有時間和地方來實現視覺差滾動。這個效果對于某些單頁網站大有裨益，而對于另一些則是噱頭，甚至更糟：難以使用。關鍵是要明確一點，你使用視覺差滾動真的能提升網站的易用性嗎，還是因為你覺得它看起來很酷？
如果要使用視覺差滾動，還要考慮一件事，使用Javascript還是純CSS技術來實現。關于這兩個選擇，請參見資源部分了解更多信息。
雖然有單頁網站大有益處，但它們也不是完美的全尺寸適配方案。雖然很多時候單頁網站比多頁網站更合理，但也有很多時候不應該使用單頁設計。
總之，假如你的網站只有少數頁面，單頁網站或許是最佳選擇。將一切濃縮在一個頁面上，能讓網站整體具有更現代的外觀，如果內容精簡，那么單頁網站可以讓它看起來更豐富。
單頁網站的另一個普遍案例，就是發布預告頁面。它們通常是單頁網站，帶有新聞郵件的注冊表單。多數情況下，發布預告期間面向大眾的信息很容易組織在一個頁面上，所以，設計這些頁面時優先考慮這種風格是很合理的。
產品單一的電商網站，也是單頁網站表現優秀的領域。如果你只賣一種產品，無論它是實體或是虛擬的，何必勞煩使用多個頁面呢？一個簡單的單頁網站才是更好的銷售工具。
可能你覺得更復雜的電商網站不適合用單頁網站，但它仍然可行。當然，有十多種產品的網站中我會避免使用，不過單張頁面也足以輕易支撐一個簡單的在線商店，通過彈出窗口來承載產品詳情和支付流程。
不該使用單頁網站的情況十分明確：龐大、復雜，或必須保有海量信息的網站不適合做成單頁網站。在這些情況下，使用相對傳統的網站結構更加明智。
雖然有大量的單頁網站存在，但也有很多混合型網站。它們給人印象是個單頁網站，但通過ajax、彈出窗和類似技術，它們事實上包含了多頁內容。
網站Dang & Blast就是這方面的絕佳案例。
如果無法讓所有東西徹底融入單個頁面，這會是和很好的解決方案。
說到單頁網站，某些站點用了某種“取巧”的辦法。它們的主站是個單頁網站，但在其他域名下也有個博客（有時是Tumblr或托管在WordPress.com的網站）。這么做沒有問題，它能突出主站的信息，也不用舍棄博客帶來的好處。
優秀設計的多數準則，在單頁網站中仍然適用，其實也適用于任何網站設計。還有一些額外的東西需要牢記，其中有些之前已經提到了。
設計如果對于你試圖表現的內容而言過于復雜，對你和你的用戶都沒有任何好處。相反，要盡可能簡化設計和內容，還能表達出你要的信息。
正因為用戶可以通過滾動來瀏覽你的網站，但并不意味著這是最友好的方式。如果你的網站很長，有很多部分，這點尤其正確。除非有特別好的理由，還是應該加入直達特定部分的鏈接，來使你的網站更加友好。
單個頁面不代表一整個冗長部分。實際上也不該如此。將內容根據邏輯劃分為幾大塊，用戶才能更容易找到他們所需。
單頁網站常常有大幅背景。當然，有時候這些背景很樸素，或帶有平鋪紋理；不過也有單頁網站利用所有的空間來揮灑創意。前面提到了，這也有助于劃分內容。背景未必要是單一的圖片。可以是一系列圖片，如果這樣做與內容更相符的話。
單頁網站的資源成百上千，還包括模版；我們這里重點關注表現突出的幾個。
PureCSSParallax Scrolling：Keith Clark的這篇文章闡釋了如何通過純CSS打造視覺差滾動效果。如果你不想用JavaScript（或者不懂）的話，這是個很好的選擇。
Skrollr：“為剩下的人準備的視覺差滾動”。這是個獨一無二的庫，適用于移動端和桌面。不需要jQuery，只有原生JavaScript。
Stellar.js：Stellar.js是另一個簡單易用的視覺差滾動庫。它提供了很多設置選項和iOS支持。
One Page Website Wireframes：如果你不確定如何構建你的網站，這個單頁網站線框圖集是很好的出發點。免費下載。這里還有第二集可供下載。
One Page Love：One Page Love是首屈一指的單頁網站集合，里面有超過5000個網站案例，并且一直在更新。他們還主打大量模版和其他資源。
Start Bootstrap：Start Bootstrap集成了海量的免費單頁網站Bootstrap主題。主題適合機構、自由職業者、作品集、著陸頁等等。
One Page Love Templates：除了豐富的網站集合，One Page Love也提供免費和收費的模版。
One Page Mania：One Page Mania提供獨特的網站和模版集合，供你下載或購買。
對各種網站來說，單頁設計都是非常棒的選擇。盡管它們不是小型網站的唯一設計方案，對很多項目而言它都是值得考慮的。思考使用單頁設計的理由，然后也思考不用的理由，再做決定。
譯者：可樂橙；譯文地址：http://colachan.com/post/3418
可樂橙，微信公眾號：可樂橙（colachangreen）。UI/UX設計師，關注互聯網，關注科技?，F居杭州，與小伙伴們正在創業途中?；蛟S不是一名優秀的設計師，至少是個快樂的設計師。
前面的章節中，我們介紹了基于page頁面的wordpress網站導航菜單的函數——wp_list_pages()。今天，我們再來介紹第二種導航菜單的方式——基于wordpress網站的文章分類目錄的導航菜單，這種wordpress導航菜單是通過wp_list_categories()函數來實現的，它可以將wordpress網站的分類目錄展示在wordpress網站前臺的導航菜單中。下面，我們一起來看看如何使用wp_list_categories()來創建wordpress網站導航菜單吧。
wp_list_categories( string|array $args = '' );
這個函數有一個參數，它的參數既可以是字符串類型的數據，也可以是一個數組類型的數據，這點跟wp_list_pages()函數類似。
$args = array('show_option_all' => '',//是否列出分類鏈接；'orderby' => 'name',//按名稱排列；'order' => 'ASC',//分類目錄的排序。升、降序；'style' => 'list',//是否用列表（ul>li）標簽；'show_count' => 0,//是否顯示文章數量；'hide_empty' => 1,//是否顯示沒有文章的分類；'use_desc_for_title' => 1,//是否顯示分類描述；'child_of' => 0,//是否限制子分類 ；'exclude' => '',//排除分類的ID，多個用',（英文逗號）'分隔；'exclude_tree' => '',//排除分類樹，即父分類及其下的子分類；'include' => '',//包括哪些分類的ID；'title_li' => 'Categories',//導航菜單的列表標題名稱；'show_option_none' =>'No categories',//網站沒有分類時顯示的標題；'number' => null,//顯示分類的數量；'echo' => 1,//是否打印到前臺頁面顯示，1顯示，0不顯示而是返回字符串；'hierarchical' => true,//是否將子、父分類分級；'depth' => 0,//層級限制；'current_category' => 0,//指定分類ID，在前臺頁面鏈接添加current-cat的CSS類，方便修改樣式；'pad_counts' => 0,//計算包括子分類的鏈接或文章數；'taxonomy' => 'category',//使用的文章分類類型；'walker' => null//生成列表 Walker 類；);
以上，我們列舉了wp_list_categories()函數的主要的參數，以及它們都代表什么。其實，在我們的實際使用中，并不是每一個參數都會用到，一般情況下，我們只會使用其中的某幾個。我們會在下面的案例中具體解說。
案例1：分類目錄導航列表按層級來排列。
$menu = array( 'depth' =>0, 'title_li'=>'', 'echo'=>1,);wp_list_categories($menu);
如下圖，子分類會按層級的關系，縮進去2格；并且沒有顯示列表的標題。
案例2：只顯示頂級分類，不顯示子分類，并顯示列表標題。
$menu = array( 'depth' =>1, 'title_li'=>'這是分類列表的標題', 'echo'=>1,);wp_list_categories($menu);
這里，我們把depth參數的值設成1，就表示只顯示一級分類目錄，子分類就不會顯示；如果設成2，就會顯示2級分類，子分類就會顯示；如果設成3，就會顯示3級分類，子分類和子分類的子分類都會顯示出來；以此類推。設成0，表示所有分類都顯示，并且按層級顯示。另外，我們這里也添加了分類菜單的列表標題，這樣，如果在側邊伴，這個標題還是非常管用的；如果是頂部導航菜單，這個標題還是省略比較好。效果如下圖：
案例3：排除某些分類。也就是不讓某些分類顯示出來。代碼如下：
$menu = array( 'depth' =>1, 'title_li'=>'', 'echo'=>1, 'exclude' => '52,81,103',);wp_list_categories($menu);
這里，我們設置了排除3個分類，它們的ID號分別是：52（親子）,81（養生）,103（家居）。這樣，我們在wordpress網站的前臺頁面的導航菜單中就看不到這幾個分類目錄。如下圖，可以對比一下上圖：
?好了，關于wordpress網站分類目錄導航菜單函數wp_list_categories()，這里我們就只舉這幾個案例，在實際應用中，我們可以根據不同的需求，來設置不同的參數，要做到靈活多變。這些參數還是很好理解的，只需多練習，就可輕松掌握。
*請認真填寫需求信息，我們會在24小時內與您取得聯系。
