Jekyll/Liquid Grammar"

Jekyll/Liquid常用語法記錄。

What is Jekyll

Jekyll是一個靜態網站生成器。
通過標記語言Markdown或textile和模版引擎liquid轉換生成網頁。
Jekyll依賴於ruby開發平台。

目錄結構

通過$ jekyll new SiteName目錄可以迅速在當前目錄下生成一個基本的Jekyll結構目錄。

.
|-- _config.yml
|-- _includes/
|   |-- footer.html
|   |-- head.html
|-- _layouts/
|-- _posts/
|   |-- 2016-01-01-title.markdown
|   |-- 2016-01-02-title.markdown
|-- _drafts/
|   |-- title.markdown
|-- _data/
|   |-- feed.yml
|-- _site/
|-- index.html

_config.yml

全局配置文件，其中包含網站所有基礎信息，便於需要時調用。

_drafts

存放未發佈的文章。

_includes

存放關於網站header, footer, sidebar等公共部分，便於需要時調用。

_layouts

存放頁面基礎配置文件，如page, post頁面第一層設置，使用html語法編寫。
頁面設置可以多層嵌套。

在使用第一層配置時，使用layout來指定:

---
layout: page
---

_posts

存放已發佈內容，命名必須按照Y-M-D-title.markdown來命名。
語法必須使用Markdown, HTML或texile。

_data

存放.yml, yaml, json, csv等文件。用於設置全局變量。

_site

Jekyll用於生成網站的文件，需要在.gitignore中屏蔽。

index.html

主頁文件。

所有存放在根目錄下並且不以下划線開頭的文件夾中有格式的文件都會被處理成page。

全局變量配置

全局配置擁有默認配置，可以手動配置需要修改的地方。

時區

# timezone: America/Argentina/San_Luis
timesone: Timesone

鏈接格式

Post中的URL格式通過permalink來配置。

# /2016/01/01/title.html
permalink: /:year/:month/:day/:title.html

# /01-01-2016/title.html
permalink: /:month-:day-:year/:title.html

同時也有已有配置可以直接設置。

# /:category/:year/:month/:day/:title.html
permalink: date

# /:category/:year/:month/:day/:title.html
permalink: pretty

# /:category/:title.html
permalink: none

分頁

文章分頁變量：paginate, paginate_path。

paginate: 5
paginate_path: "blog/page:num/"

其中/blog/目錄為baseurl目錄。page是字符常量，變量是:num分頁頁碼，自動從第二頁開始編碼。

默認值設定

設置author, layout等默認值。
在設定後可以隨時通過post題頭覆蓋這些默認值。

# in _cofig.yml
defaults:
 - 
  scope:
    path: ""  # empty means all files in the project
    type: "posts"  
  values:
    layout: "post"
    author: "Ben"

  -
   scope:
    path: "project"
    type: "pages"
   values: 
     layout: "project"

Jekyll模版、變量

Jekyll模版分為兩部分，頭部定義以及Liquid語法。

頭部定義

定義制定模版的變量，這裡的所有設置都可以覆蓋全局變量中的基礎配置。

---
layout: post
title: title
subtitle: subtitle
date: date
category: category
decription: description
published: true
permalink: none
---

所有的變量都是樹節點，連接全局變量配置根節點。

全局根節點有：

• site: config_yml全局配置信息
• page: 頁面配置信息。
• content: 包含頁面子視圖，用於引入子節點內容，不能在post和page文件中使用。
• paginator: 分頁信息。

post變量僅作用於for循環內部。

site 變量

page 變量

paginator 變量

Liquid 語法

Liquid是Ruby的一個模版引擎庫，Jekyll中用到Liquid標記有兩種：輸出和標籤。

• Output標記：變成文本輸出，被2層成對花括號包住。
• Tag標記：執行命令，被成對的花括號和百分號包住。

Jekyll 輸出 Output

Hello  { { name } }
Hello  { { user.name } }
Hello  { { 'Ben' } }

Output標記可以使用過濾器Filters對輸出內容進行簡單處理。 多個Filters間用竪線隔開，從左到右依次執行，Filter左邊總是輸入，返回值為下一個Filter的輸入或最終結果。

Hello { { 'Ben' | upcase } }  # 轉換為大寫輸出
Hello Ben has { { 'Ben' | size } } letters. # 字符串長度
Hello { { '*Ben*' | markdownify | upcase } }  # 將Markdown字符串轉換成HTML大寫文本輸出
Hello { { 'now' | date: "%Y %M %D" } }  # 按照指定格式輸出當前時間

過濾器Filters

下面是常用的過濾器方法，更多API需要查閱源碼，一般主要看兩個Ruby Plugin文件：filters.rb（Jekyll）和standardfilters.rb（Liquid）。

• date - 將時間戳轉化為另一種格式
• capitalize - 輸入字符串首字母大寫
• downcase - 輸入字符串轉換為小寫
• upcase - 輸入字符串轉換為大寫
• first - 返回數組中第一個元素
• last - 返回數組數組中最後一個元素
• join - 用特定的字符將數組連接成字符串輸出
• sort - 對數組元素排序
• map - 輸入數組元素的一個屬性作為參數，將每個元素的屬性值映射為字符串
• size - 返回數組或字符串的長度
• escape - 將字符串轉義輸出
• escape_once - 返回轉義後的HTML文本，不影響已經轉義的HTML實體
• strip_html - 刪除 HTML 標籤
• strip_newlines - 刪除字符串中的換行符(\n)
• newline_to_br - 用HTML<br/> 替換換行符 \n
• replace - 替換字符串中的指定內容
• replace_first - 查找並替換字符串中第一處找到的目標子串
• remove - 刪除字符串中的指定內容
• remove_first - 查找並刪除字符串中第一處找到的目標子串
• truncate - 截取指定長度的字符串，第2個參數追加到字符串的尾部
• truncatewords - 截取指定單詞數量的字符串
• prepend - 在字符串前面添加字符串
• append - 在字符串後面追加字符串
• slice - 返回字符子串指定位置開始、指定長度的子串
• minus - 減法運算
• plus - 加法運算
• times - 乘法運算
• divided_by - 除法運算
• split - 根據匹配的表達式將字符串切成數組
• modulo - 求模運算

Jekyll Tag

標籤用於模版中的執行語句。下面是目前Jekyll/Liquid標準標籤庫：

Comments

起到注釋Liquid代碼作用。

This is Benjamin. { % comment % } Comments { % endcomment % }

Raw

臨時禁止執行Jekyll Tag命令。

{ % raw % }
 This is a raw line. { % includ head % } will not show.
{ % endraw % }

If/Else

條件語句，可以使用關鍵字有：if, unless, elseif, else。

Case

適用於條件實例很多的情況。

{ % case template % }
{ % when 'label' % }
{ % when 'product' % }
{ % else % }
{ % endcase % }

Cycle

經常需要在相似的任務間選擇時，可以使用cycle標籤。

{ % cycle 'one', 'two', 'three' % }
{ % cycle 'one', 'two', 'three' % }

同時可以指定循環名稱進行分組處理。

{ % cycle 'group1': 'one', 'two', 'three' % }

For loops

循環遍歷數組。

{ % for item in array % }
{ { item } }
{ % endfor % }

循環迭代Hash散列，item[0]是鍵，item[1]是值。

{ % for item in hash % }
{ { item[0] } }: { { item[1] } }
{ % endfor % }

每個循環週期，提供下面幾個可用的變量：

forloop.length  # => length of the entire for loop
forloop.index  # => index of the current iteration
forloop.index0  # => index of the current iteration (zero based)
forloop.rindex  # => how many items are still left? 
forloop.rindex0  # => how many items are still left? (zero based)
forloop.first  # => is this the first iteration? 
forloop.last  # => is this the last iteration?

還有幾個屬性用來限定循環過程：

limit:int：限制循環迭代次數
offset:int：從第n個item開始迭代
reversed：反轉循環順序

Variable Assignment

為變量賦值，用於輸出或其他Tag。

{ % assign index = 1 % }
{ % assign name = 'freestyle' % }

{ % for t in collections.tags % }{ % if t == name % }
  Freestyle!
{ % endif % }{ % endfor % }


/ 變量是布爾類型 /

{ % assign freestyle = false % } 

{ % for t in collections.tags % }{ % if t == 'freestyle' % }
  { % assign freestyle = true % }
{ % endif % }{ % endfor % }

{ % if freestyle % }
  Freestyle!
{ % endif % }

capture允許將大量字符串合併為單個字符串並賦值給變量，而不會輸出顯示。

其他模版語句

格式化時間

{ { site.time | date_to_xmlschema } }     # => 2008-11-07T13:07:54-08:00
{ { site.time | date_to_rfc822 } }        # => Mon, 07 Nov 2008 13:07:54 -0800
{ { site.time | date_to_string } }        # => 07 Nov 2008
{ { site.time | date_to_long_string } }   # => 07 November 2008

代碼語法高亮

安裝pygments.rb的gem組件和Python 2.x後，配置文件添加highlighter:pygmnts，就可以使用語法高亮了。

{ % highlight ruby linenos % }
# some ruby codes
{ % endhighlight % }

參數
ruby：指定語言
linenos：顯示行號

在給代碼著色時，需配置相對應的CSS文件。

生成摘要

配置文件中設定excerpt_separator取值，每篇post都會自動截取從開始到這個值間的內容作為這篇文的摘要post.excerpt使用。
如果要禁用某篇文章的摘要，可以在該篇文章YAML頭部設定excerpt_separator: ""。

{ % for post in site.posts % }
<a href="{ { post.url } }">{ { post.title } }</a>
{ { post.exceerpt | remove: 'test' } }
{ % endfor % }

刪除HTML標籤

這個在摘要作為head標籤里的meta="description"內容輸出時很有用。

{ { post.excerpt | strp_html } }

刪除指定文本

過濾器remove可以刪除變量中的指定內容。

{ { post.url | remove: 'http' } }

CGI Escape

通常用於將URL中的特殊字符轉義為%xx形式。

{ { "foo.bar;baz?" | cgi_escape } }  # => foo%2Cbar%3Bbaz%3F

排序

# Sort an array. Optional arguments for hashes:
#   1. property name
#   2. nils order ('first' or 'last')

{ { site.pages | sort: 'title', 'last' } }

Assets 樣式文件

Jekyll支持Sass和CoffeeScript，通過新建.sass, .scss, .coffee格式文件，並在開頭添加一堆---來使用這個功能。