用jekyll制作高大上的網站（二）——實際應用

最近公司要制作個文檔庫，直接就可以將jekyll應用到實際中。

模版使用了Jekyll Clean，這么模版相對內部簡單一點，學習成本不會很大，而復雜的Minimal Mistakes就當作參考。

模版使用的CSS是Bootstrap v3.2.0版本的。為了省時點，我就直接將Bootstrap官網中的CSS和JS拉了下來。

 

一、全局配置

在_config.yml文件中可以有多種設置，包括全局配置、編譯選項等。

#網站根目錄
baseurl: /docs

# 生成的文件路徑
destination: ../../dist/docs

# 分頁
permalink: /:year/:month/:day/:title.html
paginate: 1
paginate_path: "article/:num"

# 轉換
markdown: kramdown
highlighter: rouge
excerpt_separator: <!--excerpt-->

gems: ['jekyll-paginate']

exclude: ['open.bat','Gemfile','Gemfile.lock','Guardfile', 'gulpfile.js']

# Collections
collections:
 common:
  output: true
  permalink: /:collection/:title
 ui:
  output: true
  permalink: /:collection/:title

1）你網站可能會放在域名的某個文件夾下面，那么根目錄就要帶着那個文件夾，有了“baseurl”的配置，就能方便拼接了。

2）生成的文件路徑“destination”，默認是在_site文件夾中，現在放到了我自定義的文件夾下面。

3）分頁中為了方便演示，每頁僅顯示1條記錄，文章保存方式是年月日+標題，分頁的目錄會在“article”，分頁比較特殊，下面會詳解。

4）markdown就是文章編輯語言，使用了kramdown，kramdown是markdown的超級。highlighter就是代碼高亮的方式，使用了rouge。

5）excerpt_separator與文章摘要相關，后面也會詳解。

6）collections就是定義一種新的文檔類型，例如上面定義了“common”，那么在最終生成的文件中，會專門有一個文件夾，這個后面也會說明下。

 

 

 

二、集合（Collections）

1）與文章的區別

在結構中有一個_post文件夾，這個文件夾內放的就是文章列表，文件名就是按年月日+標題的方式起的，最終生成的將是年月日的文件夾。

 

如果把所有各種類型的文章都放在這個里面，管理會比較混亂，例如我有隨筆、UI庫、工具庫等要放在網站展示。

隨筆的話就可以都放在_post文件夾里，但是UI庫等其他類型的文章展示的格式與其不一樣、展示的方式也與其不一樣。

下圖是一張UI庫的頁面，左邊放的是分類，右邊放的內容。如果單獨放在文件夾中，那么就可以很方便的編輯分類鏈接。

<h1>基礎樣式</h1>
<ul>
    <li><a href="{{ site.baseurl }}/ui/typeface.html">文本</a></li>
    <li><a href="{{ site.baseurl }}/ui/icon.html">圖標</a></li>
    <li><a href="{{ site.baseurl }}/ui/grid.html">網格</a></li>
    <li><a href="{{ site.baseurl }}/ui/border.html">邊框</a></li>
    <li><a href="{{ site.baseurl }}/ui/layout.html">布局</a></li>
</ul>

 

2）_data

在上圖的右邊，還有個頁面內容導航，順便說明下：

kramdown會給h1等自動加上ID，上圖中的“h1-h6”就被自動加了ID，里面有英文就用此英文，如果沒有就自動生成。

原先我是將這些內容放在_include文件夾下面，_include內放的都是些頁面通用部分，后面發現頁面越來越多，但是內容都差不多，僅僅是數據不一樣，每次都是在復制黏貼。

 

后面發現jekyll提供了個_data，可以將數據放入此處，再用for循環來輸出，此文件夾內可以使用 .yml、.yaml、.json、csv 擴展名。

- id: "const"
  name: "普通常量"
  children:
   - id: "cookie"
     name: "cookie"
   - id: "menu"
     name: "menu"
   - id: "to"
     name: "分享回調中設置的TO"
   - id: "jsbridge"
     name: "JSBridge"

在sidenav.html中輸出：

<nav class="bs-docs-sidebar hidden-print hidden-xs hidden-sm affix-top">
    <ul class="nav bs-docs-sidenav">
        {% for data in site.data[page.sidebar][page.sidenav] %}
        {% if forloop.first %}
        <li class="active">
            {% else %}
        <li>
            {% endif %}
            <a href="#{{ data.id }}">{{ data.name }}</a>
            {% if data.children %}
            <ul class="nav">
                {% for sub in data.children %}
                <li><a href="#{{ sub.id }}">{{ sub.name }}</a></li>
                {% endfor %}
            </ul>
            {% endif %}
        </li>
        {% endfor %}
    </ul>
    <a href="#top" class="back-to-top">返回頂部</a>
</nav>

jekyll用的是liquid模版引擎，有自己的語法，基本常規的都有。

 

三、文章

1）分類

現在的文章都會有分類，做了區分后，文章能更有調理，下圖是博客園的自定義文章分類。

jekyll的文章中要做分類，可以在頭信息中設置category或categories。

---
layout: article-detail
title: demo
date: 2016-05-09 08:25:06
sidebar: article
category: tool
author: strick
---

在上圖中會顯示這個分類的名字，並且會輸出這個分類下面文章的個數，點擊這個分類名，能夠跳轉到相應的分類下的文章列表。

要實現這幾個功能，可以通過categories的相關屬性獲取。

<h1>隨筆分類</h1>
{% for category in site.categories %}
<ul>
    <li><a href="{{ site.baseurl}}/category/{{ category.first }}.html">{{category.first}}（{{category.last.size}}）</a></li>
</ul>
{% endfor %}

 

2）文章列表

上面的分類文章列表中，會多個判斷：

{% for category in site.categories %}
    {% if category.first == page.category %}
        {% for post in category.last %}
<div class="article">
    <div class="well">
        <h1 class="none"><a href="{{ site.baseurl}}{{ post.url }}">{{ post.title }} {{ post.date | date: "（%Y年%m月%d日）" }}</a></h1>
        <div class="content">{{ post.excerpt | strip_html }}</div>
    </div>
</div>
        {% endfor %}
    {% endif %}
{% endfor %}

“{{ post.excerpt | strip_html }}”就是在做文章摘要，strip_html是將HTML標簽去除。

“{{ post.date | date: "（%Y年%m月%d日）" }}”是在做格式化時間，上面的頭信息中設置了“date: 2016-05-09 08:25:06”。

 

3）分頁

jekyll的分頁只能在index.html中執行，只能這個文件，其他文件是不能執行，“paginator”對象中的屬性都將為空。

在上面的_config.yml中設置了兩個關於分頁的屬性，一個是每頁顯示的數量，一個是分頁文件輸出的方式。

paginate: 1
paginate_path: "article/:num"

沒有把頁碼1給輸出，我在做分頁的時候，就每次都得多做個判斷。

頁面的樣式就直接用了Bootstrap的分頁。

<ul class="pagination">
        <li>
            <a href="{{ site.baseurl}}/article/">
                <span>首頁</span>
            </a>
        </li>
        <li>
        {% if paginator.page == 1 %}
            <span>&laquo;</span>
        {% else %}
            {% if paginator.previous_page == 1 %}
            <a href="{{ site.baseurl}}/article/">
            {% else %}
            <a href="{{ site.baseurl}}/article/{{ paginator.previous_page }}">
            {% endif %}
                <span>&laquo;</span>
            </a>
        {% endif %}
        </li>
        {% for i in (1..paginator.total_pages) limit:9 offset:{{paginator.page-1}} %}
            {% if paginator.page == i %}
        <li class="active">
            {% else %}
        <li>
            {% endif %}
            {% if i == 1 %}
            <a href="{{site.baseurl}}/article">{{i}}</a>
            {% else %}
            <a href="{{site.baseurl}}/article/{{i}}">{{i}}</a>
            {% endif %}
        </li>
        {% endfor %}
        <li>
            {% if paginator.page == paginator.total_pages %}
            <span>&raquo;</span>
            {% else %}
            <a href="{{ site.baseurl}}/article/{{ paginator.next_page }}">
                <span>&raquo;</span>
            </a>
            {% endif %}
        </li>
        <li>
            <a href="{{ site.baseurl}}/article/{{paginator.total_pages}}">
                <span>末頁</span>
            </a>
        </li>
        <li class="disabled">
            <span>第{{paginator.page}}頁 / 共{{paginator.total_pages}}頁</span>
        </li>
</ul>

 

demo下載：

http://download.csdn.net/download/loneleaf1/9518315

 

參考資料：

Syntax Highlighting in Jekyll With Rouge 

Rouge支持的語言

kramdown語法

Kramdown 語法文檔翻譯

文章分類索引

為Jekyll增加不完美的分頁和文章摘要