最近想搭建一個網站:前幾日MarkDown語法已略讀了下,現在看jekyll 先把文檔看了。
只翻譯有用的,廢話就略過。
什麼是jekyll??
簡單說:它是靜態網頁生成器。具體點:包含一些用markdown語法寫的文件的文件夾;通過markdown和Liquid轉換器
生成一個網站。
同時jekyll也是github靜態頁面引擎。意味着你可以用jekyll生成你的頁面,免費託管在github服務器。
快速開始
gem install jekyll{安裝jekyll。gem執行文件可能需要其他依賴,比如ruby}jekyll new myblog{生成博客目錄}
tip::生成博客目錄到本地:jekyll new .
啓動服務器:
jekyl serve
然後瀏覽器訪問:localhost:4000即可(預覽)
基本用法:
通過gem安裝包管理器安裝好jekyll以後,就能夠在windows的命令行中執行jekyll
jekyll build{到項目根目錄,執行編譯後,當前目錄自動生成_site文件夾}
tip::
編譯到指定地方
jekyll build --destination <destination>
編譯指定文件夾
jekyll build --source <source> --destination <destination>
編譯後好自動監聽文件變化 自動編譯
jekyll build --watch
提示:
編譯到的目標文件夾會被清空
預覽:
jekyll serve
訪問:
localhost:4000
tip::
2.4版本以後會自動檢測文件的改變
禁止該行爲:
jekyll serve --no-watch
除了--no-watch等配置項,還有其他很多配置
一般是放在根目錄下面的_config.xml文件下面,前面的放在命令行也是一種方式
調用jekyll命令的時候會自動用_config.xml裏面的配置。
比如:_config.xml裏的
source:_source
destination:_deploy
相當於:
jekyll build --source _source --destination _deploy
目錄結構
jekyll本質上就是文本轉換引擎。。
有很多的文件,用標記語言寫好,放在不同的文件夾裏面,
通過這種形式表現,你想你的網頁長什麼樣,有哪些數據。
_config.yml :存儲配置數據。把配置寫在這個文件裏面,可以讓你不用在命令行中寫。
_drafts:草稿,格式是:沒有日期.md
_includes:包含一些模板,可以重複利用。你可以用通過{% include file.ext %}包含_includes/file.ext文件{這種方式是liquid語法}
_layouts:裏面的文件通過{{ content }}包含_posts裏面的文章。
_posts:存放你要發表的文章。格式YEAR-MONTH-DAY-title.MARKUP。
文件名確定了發表的日期和標記語言。博客的日期格式通過_config.yml的permalink字段設置或者通過YAML FRONT Matter設置
_data:保存數據的。jekyll會自動加載這裏的所有
.jml或者.yaml結尾的文件。
比如你有一個members.yml。那麼你可以通過site.data.members
訪問該文件裏的數據。
_site:
jekyll生成的網站會放在該文件夾下。
最好把它放到.gitignore文件裏面,這樣git就不會管理它了。
index.html:
該文件裏面有一個YAML FRONT Matter。大概就長下面這樣:
---
layout: index
title: FEX
page_id: index
---
jekyll會轉換它。包括所有的根目錄下面的,或者不是以上提到的,目錄。
裏的.html,.markdown,.md,和.textile文件。
除了上面提到的其他文件或者文件夾,會被自動拷貝
到_site文件夾裏面。包括
css和圖片文件夾,favicon.icon文件。
配置
有兩種方式配置,一個是命令行,一個是通過_config.yml文件
source://定義jekyll讀取文件的位置 比如本地就直接用.
destination://定義網站生成的位置,比如_site
safe://是否禁用自定義插件 不理解暫時不管他
encoding://通過名字定義文件的編碼 只ruby1.9以後纔有效
2.0.0以後默認的編碼是utf-8,而之前的默認編碼是ascii-8bit
Front Matter defaults
用這個東東可以具體地配置你的頁面或者發表的文章。
經常你會重複配置一些東西,比如作者,
爲了避免這種情況的解決方案是
在_config.xml中配置defaults字段
默認配置
jekyll默認是用如下的配置:看官網http://jekyllrb.com/docs/configuration/
Front Matter
通過這個可以設置一些變量(甚至可以自定義變量),比如title---
layout: post
title: Blogging Like a Hacker
---
設置好變量以後,
你就可以在當前頁面或者你的頁面依賴的_layouts或者_includes
裏的文件通過Liquid 標記,比如{page.title}訪問了。
tip:::
不允許存在BOM字符
這個頭不寫也是可以的:
比如CSS and RSS feeds!可能不需要
已定義的全局變量:
layout:指定用_layouts下面的文件。
自定義的變量:
在Front Matter定義的變量(不是已定義的全局變量)都會在會話期間綁定數據給Liquid模板引擎。
比如你在定義了title,那你就可以再_layouts裏面的模板使用它{{ page.title }}
寫文章
jekyll有一個最好的特性就是:你寫文章並發表他們只是意味着你只要管理一些文本文件即可。
而不需要配置和維護數據庫以及良好的CMS系統。
發文章的文件夾:
_posts裏面都是些md或者testile文件。只要有yaml front matter,它們就會被轉換爲html格式的靜態頁面。
創建文件:
創建一個文件YEAR-MONTH-DAY-title.mdYEAR是4位數,month和day是兩位數
例子:
2011-12-31-new-years-eve-is-awesome.md
2012-09-12-how-to-write-a-blog.textile
tip::
通過post_url訪問其他的文章,不用擔心鏈接( the site permalink)的樣式改變而訪問不到。
內容的樣式:
所有的文章都必須要有yaml front matter頭。tip::將<meta charset="utf-8">包含在head標籤裏面。
包含圖片和資源
在根目錄下創建文件夾比如assets和downloads然後markdown語法訪問通過這種形式:
![截屏]({{ site.url }}/assets/screenshot.jpg)
說明:
截屏鏈接的文字,()裏面的東西不會顯示,是鏈接到的地址。
site.url可以訪問你配置的(_config.yml)的網站url。
鏈接到pdf閱讀器讓用戶下載:
you can [get the PDF]({{ site.url }}/assets/mydoc.pdf) directly.
顯示一系列的文章:
<ul>
{% for post in site.posts %}
<li>
<a href="{{ post.url }}">{{ post.title }}</a>
</li>
{% endfor %}
</ul>
顯示文章的第一個段
<ul>
{% for post in site.posts %}
<li>
<a href="{{ post.url }}">{{ post.title }}</a>
{{ post.excerpt }}
</li>
{% endfor %}
</ul>
高亮代碼片段
通過Pygments or Rouge,jekyll具有內建的語法高亮能力
{% highlight ruby %}
def show
@widget = Widget(params[:id])
respond_to do |format|
format.html # show.html.erb
format.json { render json: @widget }
end
end
{% endhighlight %}
高亮代碼同時顯示行號:
{% highlight ruby linenos %}def show
@widget = Widget(params[:id])
respond_to do |format|
format.html # show.html.erb
format.json { render json: @widget }
end
end
{% endhighlight %}
_drafts文件夾工作方式
_drafts裏面的文章是你暫時不想發表的
通過jekyll serve --drafts預覽
jekyll build --drafts編譯
創建頁面
主頁
即使是主頁也可以用_layouts和_includes裏面的東西
其他的增加的額外頁面
一般方式:
|-- _config.yml
|-- _includes/
|-- _layouts/
|-- _posts/
|-- _site/
|-- about.html # => http://example.com/about.html
|-- index.html # => http://example.com/
└── contact.html # => http://example.com/contact.html
乾淨的url方式(不帶有文件後綴)
├── _config.yml
├── _includes/
├── _layouts/
├── _posts/
├── _site/
├── about/
| └── index.html # => http://example.com/about/
├── contact/
| └── index.html # => http://example.com/contact/
└── index.html # => http://example.com/
變量
jekyll要遍歷所有的文件,只要帶有yaml front matter的文件
都可以通過Liquid 模板系統訪問一些變量。
全局變量
site:包含了網站信息和_config.yml裏面的信息
page:在yaml front matter的自定義的變量通過page訪問
content:_layouts裏面,不定義在_post和其他頁面中。包含了post和其他頁面裏面的文章內容。
paginator:paginate在_config_yml裏面配置以後,這個變量就可以用了。
site變量
site.time:當前運行jekyll的時間
site.pages:所有的頁面
site.posts:以時間逆序排序的所有的文章
site.data:包含從目錄_data裏面加載的數據列表
page變量
page.content:頁面內容
page.title:文章標題
page.urL:頁面地址:比如/2008/12/14/my-post.html
page.date:頁面的日期。可以在front matter重寫:2008-12-14 10:30:00 +0900或者YYYY-MM-DD HH:MM:SS
page.id:頁面id。比如/2008/12/14/my-post 在RSS feeds裏面有用。
tip::
front matter裏面可以自己定義變量:比如custom_css: true
然後你可以通過page.custom_css訪問
Paginator變量
paginator.per_page:每一頁的文章數
paginator.posts:那一頁可用的文章
paginator.page:當前頁的值
tip::
Paginator只在index.html(或者/blog/index.html)中有效
Data文件夾
通過Liquid模板系統可以自定義數據
jekyll支持從位於_data的yaml,json,csv文件中加載數據,(csv必須包含一個header row)
通過site.data訪問裏面的數據
例子:
比如定義一個文件_data/members.yml
- name: Tom Preston-Werner
github: mojombo
- name: Parker Moore
github: parkr
- name: Liu Fengyun
github: liufengyun
然後可以通過site.data.members訪問該文件(文件名決定了字段名)
<ul>
{% for member in site.data.members %}
<li>
<a href="https://github.com/{{ member.github }}">
{{ member.name }}
</a>
</li>
{% endfor %}
</ul>
定義組織(包含子文件)
_data/orgs/jekyll.yml中:
username: jekyll
name: Jekyll
members:
- name: Tom Preston-Werner
github: mojombo
- name: Parker Moore
github: parkr
_data/orgs/doeorg.yml中:
username: doeorg
name: Doe Org
members:
- name: John Doe
github: jdoe
使用:
<ul>
{% for org_hash in site.data.orgs %}
{% assign org = org_hash[1] %}
<li>
<a href="https://github.com/{{ org.username }}">
{{ org.name }}
</a>
({{ org.members | size }} members)
</li>
{% endfor %}
</ul>