本系列有五篇：分別是
【一】Ubuntu14.04+Jekyll+Github Pages搭建靜態博客：主要是安裝方面
【二】jekyll 的使用 ：主要是jekyll的配置
【三】Markdown+jekyll在Gitpages上寫blog的常用操作 ：主要Markdown的使用
目錄
- 什么是jekyll
- 快速開始
- 目錄結構
- 配置
- 默認配置
- Front Matter
- 寫文章
- 發文章的文件夾
- 創建文件
- 內容的樣式
- 包含圖片和資源
- 顯示一系列的文章
- 顯示文章的第一個段
- 高亮代碼片段
- 高亮代碼同時顯示行號
- _drafts文件夾工作方式
- 創建頁面
- 主頁
- 變量
- 全局變量
- site變量
- page變量
- Paginator變量
- 通過Liquid模板系統可以自定義數據
- 添加評論
什么是jekyll??
簡單說：它是靜態網頁生成器。具體點：包含一些用markdown語法寫的文件的文件夾；通過markdown和Liquid轉換器
生成一個網站。
同時jekyll也是github靜態頁面引擎。意味着你可以用jekyll生成你的頁面，免費托管在github服務器。
快速開始
假設已經已經安裝完Jekyll【安裝方法 Ubuntu14.04+Jekyll+Github Pages搭建靜態博客 】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
用這個東東可以具體地配置你的頁面或者發表的文章。
Instead of repeating this configuration each time you create a new post or page, Jekyll provides a way to set these defaults in the site configuration. To do this, you can specify site-wide defaults using the
defaults key in the
_config.yml file in your projects root directory.
為了避免這種情況的解決方案是在 _config.yml中配置defaults字段）
my-site layout. Any html files that exist in the projects/ folder will use the project layout, if it exists. Those files will also have the page.author
liquid variable
set to Mr. Hyde as well as have the category for the page set to project.
默認配置
jekyll默認是用如下的配置：
# Where things are source: . destination: ./_site plugins_dir: ./_plugins layouts_dir: ./_layouts data_dir: ./_data includes_dir: ./_includes collections: null # Handling Reading safe: false include: [".htaccess"] exclude: [] keep_files: [".git", ".svn"] encoding: "utf-8" markdown_ext: "markdown,mkdown,mkdn,mkd,md" # Filtering Content show_drafts: null limit_posts: 0 future: false unpublished: false # Plugins whitelist: [] gems: [] # Conversion markdown: kramdown highlighter: rouge lsi: false excerpt_separator: "\n\n" incremental: false # Serving detach: false port: 4000 host: 127.0.0.1 baseurl: "" # does not include hostname # Outputting permalink: date paginate_path: /page:num timezone: null quiet: false defaults: [] # Markdown Processors rdiscount: extensions: [] redcarpet: extensions: [] kramdown: auto_ids: true footnote_nr: 1 entity_output: as_char toc_levels: 1..6 smart_quotes: lsquo,rsquo,ldquo,rdquo enable_coderay: false coderay: coderay_wrap: div coderay_line_numbers: inline coderay_line_number_start: 1 coderay_tab_width: 4 coderay_bold_every: 10 coderay_css: style
---
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 }}
<!DOCTYPE HTML>
<html>
<head>
<title>{{ page.title }}</title>
</head>
<body>
...
寫文章
jekyll有一個最好的特性就是：你寫文章並發表他們只是意味着你只要管理一些文本文件即可。
而不需要配置和維護數據庫以及良好的CMS系統。
發文章的文件夾：
里面都是些Markdown或者HTML文件。只要有yaml front matter，它們就會被轉換為html格式的靜態頁面。
創建post文件：
以下兩種也是有效的例子：
2011-12-31-new-years-eve-is-awesome.md
2012-09-12-how-to-write-a-blog.textile
tip::
通過post_url訪問其他的文章，不用擔心鏈接（ the site permalink）的樣式改變而訪問不到。
【備注】Markdown和Textile
鏈接： https://www.zhihu.com/question/20912653/answer/16591103
來源：知乎
Markdown 和 Textile 都是如今輕量級標記文本風潮下的產物，基本設計思路差異不大，所以我不打算糾技術細節。有興趣者請參考我文后的鏈接。以下我只說一些個人的感受。
先聲明，這兩者都不是我的首選工具，只是之前選擇時比較過。所以結果可能不完善。如有不同意見請與我聯系，要求刪貼也無妨。
=== Markdown 的優點 ===
Markdown 的主要優點是有大量的第三方編輯器支持。首先 GitHub 的在線文檔編輯器就能很好地支持它，而 Mac App Store 或 Windows Marketplace 上搜索 Markdown editor 也是一抓一大把。很多編輯器都支持所見即所得編輯，非常方便。相比之下支持 Textile 的編輯器數量就很少。但 Markdown 在做復雜的內容編輯時能力有限，要求編寫者最好具備一定的 HTML 基礎，比如插入表格。對不熟悉 HTML 的朋友來說，這種操作未免麻煩了些。
——但需要注意的是，這不算是 Markdown 的問題，而是設計者有意為之的。本來 Markdown 的設計目的是為了「簡化」而非「替代」HTML。
=== Textile 的優點 ===
Textile 的優勢是不需要過多的 HTML 基礎（當然如果確實需要，用戶也可以用）。比如表格，它提供了 [Table] 標志而不是要求直接上 HTML 段落；又比如 == 號可用來阻止解釋器解釋，而不是像 Markdown 那樣需要直接用 <div>。Textile 的另一個好處是它提供了一些復雜字符的內建支持，比如：(r) == ®, (tm) == ™, (c) == ©，放在 Markdown 里就麻煩一些。第三個好處，也是我很喜歡 Textile 的一點：它提供的標記更容易閱讀。比如標題標記，Textile 用 .h1 .h2，級別一目了然，和 Markdown 用「#」和「##」的標識相比，可讀性更好。
=== 一些共同的特性 ===
如果把討論限制在方便性上，Textile 和 Markdown 只能說各有千秋。比如在處理逐條記錄（itemization）時 Textile 統一用「#」，而不像 Markdown 那樣要求使用 1，2，3，4。應該說 Textile 的設計便於用戶變更條目順序時避免多處修改；反過來，Markdown 處理腳注時可以使用無記名腳注，而 Textile 則必須使用 [1] 和 fn1 的組合。如果腳注順序需要修正則會麻煩許多。
---- 得 @Jesse Luo 指點：Markdown 的逐條記錄可以在編譯時自動將 11223調整為12345，所以不要誤會，Markdown 事實上可以相對方便地處理逐條記錄。特此感謝。不過如果為了照顧純文本的可讀性，寫作者最好還是得在正文里調整數字的順序。這一點上看，Textile 還是方便。
如果把討論限制在功能上，我只能說兩者都不怎么樣。這兩者都適合相對非正式的文本，比如 blog 或網頁。兩者相對單一的 HTML 輸出也證明了這一點。如果需要更復雜的功能，恐怕用戶還得考慮更復雜的選項，比如我用得最順手的 reStructuredText。
綜合考慮，我傾向於認為 Textile 更適合我這種 HTML 基礎較差的用戶；而 Markdown 在前端程序員手里適應性更好。另外，對「所見即所得」有要求的朋友可能會在編輯器支持的問題上有所傾向。但既然這些都是純文本編輯，多數情況下我不認為這一點非常重要，畢竟對我來說，一個 vim 足以解決所有問題。
參考：
Markdown：Daring Fireball: Markdown
Textile：Textile (Markup Language) Reference Manual for RedCloth
內容的樣式：
tip::將<meta charset="utf-8">包含在head標簽里面。
包含圖片和資源
assets or
downloads, into which any images, downloads or other resources are placed. Then, from within any post, they can be linked to using the site’s root as the path for the asset to include. Again, this will depend on the way your site’s (sub)domain and path are configured, but here some examples (in Markdown) of how you could do this using the
site.url variable in a post.
然后markdown語法訪問通過這種形式：
[]為圖片鏈接的文字，
site.url可以訪問你配置的（_config.yml）的網站url。
鏈接到pdf閱讀器讓用戶下載：
you can [get the PDF]({{ site.url }}/assets/mydoc.pdf) directly.
比如：
就會顯示以下圖片：
更具體可以參考：【CSDN-markdown語法之如何插入圖片】
顯示一系列的文章：
<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 %}
高亮代碼同時顯示行號：
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編譯
創建頁面
主頁
index.html
其他的增加的額外頁面
一般方式：
|-- _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 variable availability：These are only available in index files, however they can be located in a subdirectory, such as /blog/index.html.
Paginator只在index.html(或者/blog/index.html)中有效
）
Data Files（詳見官網）
In addition to the built-in variables available from Jekyll, you can specify your own custom data that can be accessed via the Liquid templating system.
通過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>
Plugins（插件）
Jekyll has a plugin system with hooks that allow you to create custom generated content specific to your site. You can run custom code for your site without having to modify the Jekyll source itself.
Plugins on GitHub Pages
GitHub Pages is powered by Jekyll. However, all Pages sites are generated using the --safeoption to disable custom plugins for security reasons. Unfortunately, this means your plugins won’t work if you’re deploying to GitHub Pages.
You can still use GitHub Pages to publish your site, but you’ll need to convert the site locally and push the generated static files to your GitHub repository instead of the Jekyll source files.
Installing a plugin（安裝插件）
You have 3 options for installing plugins:（有三種方法）
- In your site source root, make a
_pluginsdirectory. Place your plugins here. Any file ending in*.rbinside this directory will be loaded before Jekyll generates your site. -
In your
_config.ymlfile, add a new array with the keygemsand the values of the gem names of the plugins you’d like to use. An example:gems: [jekyll-coffeescript, jekyll-watch, jekyll-assets] # This will require each of these gems automatically.Then install your plugins using
gem install jekyll-coffeescript jekyll-watch jekyll-assets -
Add the relevant plugins to a Bundler group in your
Gemfile. An example:group :jekyll_plugins do gem "my-jekyll-plugin" gem "another-jekyll-plugin" endNow you need to install all plugins from your Bundler group by running single command
bundle install
tip::
_plugins, _config.yml and Gemfile can be used simultaneously
You may use any of the aforementioned plugin options simultaneously in the same site if you so choose. Use of one does not restrict the use of the others.
插件列表可查看官網鏈接
【附】使用MathJax顯示公式
- 修改html頭部
在需要使用的頁面開頭加上這么一句，在Jekyll下可以通過修改default.html加上。
<script type="text/javascript"
src="https://cdn.mathjax.org/mathjax/latest/MathJax.js?config=TeX-AMS-MML_HTMLorMML">
</script>
2. 然后直接調用 公式和Latex公式一致的，沒有太多難點，可以參考這個站點
添加評論
1、注冊 多說 賬號，創建站點，得到short_name （如圖，ww1111就是我的shortname）
2、創建后，就會生成的多說代碼，如下：
可以詳細看下代碼，其中short_name就是ww1111，
<!-- 多說評論框 start -->
<div class="ds-thread" data-thread-key="請將此處替換成文章在你的站點中的ID" data-title="請替換成文章的標題" data-url="請替換成文章的網址"></div>
<!-- 多說評論框 end -->
<!-- 多說公共JS代碼 start (一個網頁只需插入一次) -->
<script type="text/javascript">
var duoshuoQuery = {short_name:"ww1111"};
(function() {
var ds = document.createElement('script');
ds.type = 'text/javascript';ds.async = true;
ds.src = (document.location.protocol == 'https:' ? 'https:' : 'http:') + '//static.duoshuo.com/embed.js';
ds.charset = 'UTF-8';
(document.getElementsByTagName('head')[0]
|| document.getElementsByTagName('body')[0]).appendChild(ds);
})();
</script>
<!-- 多說公共JS代碼 end -->
參數介紹：
data-thread-key string 推薦 文章在原站點中的id或其他唯一標識。通用代碼中，將您站點中的文章id告知我們，是區分文章，解決分頁問題的好方法，評論回流時，也以此來定位原站點文章，同id的文章，顯示的是相同的評論內容。data-thread-key中:和,即冒號和逗號有特別的用途，請不要使用url或其他有這兩個符號的內容作為data-thread-key。同時也請盡量避免將data-thread-key設作0、空字符串或中文。示例：在typecho建站系統中，data-thread-key="<?php echo $this->cid;?>",phpcms中data-thread-key="{id_encode("content_$catid",$id,$siteid)}"，如果您在獨立靜態頁中使用，可以自己設置合適的值，例如首頁使用data-thread-key="index"，我們在管理后台的“工具”選項卡里提供了更多建站類型的示例。 data-title string 推薦 您的文章標題。對於通用代碼，沒有提前同步文章數據。如果您在后台管理看到的文章標題不正確，加入這個參數，讓您在后台管理時更加便利 data-image string 推薦 文章圖片地址，將用於轉發時的附圖。 data-url string 文章的url。第一次顯示評論框時，我們會按這個參數標記文章。 如果您改變了域名，或者希望幾篇文章顯示同一評論框，傳遞data-url即可解決 例如之前一篇文章是鏈接地址是"http://abc.com/101.html" ，上面已經有100個評論，之后這篇文章有了分頁，在這分頁里加上data-url="http://abc.com/101.html" ，兩個頁面就都會顯示相同的評論內容了。 注意：在沒有設置data-url項目時，我們優先采用頁面中canonical標簽值，如果沒有設置canonical標簽，則會使用頁面的url。頁面url會自動過濾#之后的參數。對於設置了不同的data-thread-key之后，還發現多篇文章出現相同評論的情況，請確認一下頁面中的canonical標簽是否重復。 關於canonical標簽，可以參考以下介紹：<a name="test" href="http://www.chinaz.com/web/2011/0630/192530.shtml" target="_blank" rel="no-follow">http://www.chinaz.com/web/2011/0630/192530.shtml</a> data-author-key string 推薦 作者在本站中的id。對於wordpress插件，文章如果填寫該id，可以識別作者，在收到評論時，會對該作者發出郵件提醒。通用代碼用戶及其他插件，如果需要通過這種方式獲取郵件，請通過 http://dev.duoshuo.com/docs/51435552047fe92f490225de 這個接口導入用戶並且要有郵箱信息，指定的user_key就是此處要填的data-author-key data-form-position string 該頁面中評論框的位置，取值top(評論框在頂端顯示),bottom(評論框在底端顯示) data-limit int 單頁顯示評論數，取值范圍:1～200 data-order string //排序方式，取值：asc(從舊到新),desc(從新到舊) 這些參數，將覆蓋站點的設定值，並且只對含該參數頁面有效。當然，您在動態生成的頁面中插入帶參數的代碼，則都是動態評論框了。
將代碼復制，找到倉庫的_layouts文件夾下的post.html文檔，使用編輯器打開，將多說代碼粘貼到 </div> 的后面；
然后將data-thread-key的內容 替換成 “{{data-thread-key}}”，如下：然后可以在不同post中隔離各自的評論（即一個data-thread-key來表示不同文章的評論子集）
3、渲染結果：
還可以通過多說的管理員后台頁面查看記錄
到此已經完成了。不過。。我們希望把多說做成一個模塊，這樣各個文件可以通過include導入，所以我們在做些工作：
1、在_includes 文件下新增文件夾comment，在comment下新增文件duoshuo.html
$ cd _includes; mkdir comment; cd comment; touch duoshuo.html
編輯文件duoshuo.html
將多說的代碼復制到里面，並修改兩個紅框中的內容：
這些字段的具體值由我們在不同的post中動態給定。
第一個紅框的變量是在具體的post.md文件中給定的，如下圖：
第二個紅框變量是在_config.yml中給定的，如下圖：
2、如果我希望模板post.html中增加評論功能，我們就修改post.html，編輯文件，在文章增加一行，將duoshuo.html導入進來：
{% include comment/duoshuo.html %}
3、具體的使用
如果在某個md文件中要使用評論功能，我們就選用post.html這個模塊，就可以了，然后在配置（_config.yml）中修改變量就可以了，非常方便。。可以發現將md文件轉換后的html文件中，變量都被填充了。。。
