【二】jekyll 的使用
本系列有五篇：分別是
【一】Ubuntu14.04+Jekyll+Github Pages搭建靜態博客：主要是安裝方面
【二】jekyll 的使用 ：主要是jekyll的配置
【三】Markdown+jekyll在Gitpages上寫blog的經常使用操做 ：主要Markdown的使用javascript
目錄html
- 什麼是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 .前端
啓動服務器：java
jekyl servegit
而後瀏覽器訪問：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 _deploygithub
目錄結構
（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文件。web
配置
有兩種方式配置，一個是命令行，一個是經過_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" end
Now 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公式一致的，沒有太多難點，能夠參考這個站點
添加評論
一、註冊 多說 帳號，建立站點，獲得short_name （如圖，ww1111就是個人shortname）
二、建立後，就會生成的多說代碼，以下：
能夠詳細看下代碼，其中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來表示不一樣文章的評論子集）
三、渲染結果：
還能夠經過多說的管理員後臺頁面查看記錄
到此已經完成了。不過。。咱們但願把多說作成一個模塊，這樣各個文件能夠經過include導入，因此咱們在作些工做：
一、在_includes 文件下新增文件夾comment，在comment下新增文件duoshuo.html
$ cd _includes; mkdir comment; cd comment; touch duoshuo.html
編輯文件duoshuo.html
將多說的代碼複製到裏面，並修改兩個紅框中的內容：
這些字段的具體值由咱們在不一樣的post中動態給定。
第一個紅框的變量是在具體的post.md文件中給定的，以下圖：
第二個紅框變量是在_config.yml中給定的，以下圖：
二、若是我但願模板post.html中增長評論功能，咱們就修改post.html，編輯文件，在文章增長一行，將duoshuo.html導入進來：
{% include comment/duoshuo.html %}
三、具體的使用
若是在某個md文件中要使用評論功能，咱們就選用post.html這個模塊，就能夠了，而後在配置（_config.yml）中修改變量就能夠了，很是方便。。能夠發現將md文件轉換後的html文件中，變量都被填充了。。。
- 1. Jekyll使用教程筆記 二
- 2. Jekyll中Sass的使用
- 3. jekyll 安裝使用
- 4. jekyll簡單使用
- 5. jekyll : 使用github託管你的博客
- 6. jekyll-admin的搭建和使用
- 7. Github+Jekyll —— 建立我的免費博客（二）Ruby+Jekyll部署
- 8. 用jekyll製做高大上的網站（二）——實際應用
- 9. Jekyll使用教程筆記 六
- 10. Jekyll使用教程筆記 五
- 更多相關文章...
- • Hibernate的二級緩存 - Hibernate教程
- • TortoiseSVN 使用教程 - SVN 教程
- • Composer 安裝與使用
- • 使用Rxjava計算圓周率
-
每一个你不满意的现在，都有一个你没有努力的曾经。