【转】jekyll 的使用

时间：2016-01-09 22:53:04 阅读：457 评论：0 收藏：0 [点我收藏+]

以下关于Jekyll的使用说明参考 Jekyll 官方文档和博客【 jekyll 官网文档部分翻译】，Jekyll的安装详见【Ubuntu14.04+Jekyll+Github Pages搭建静态博客】

什么是jekyll
快速开始
目录结构
配置
默认配置
Front Matter
写文章
1. 发文章的文件夹
2. 创建文件
3. 内容的样式
4. 包含图片和资源
显示一系列的文章
显示文章的第一个段
1. 高亮代码片段
2. 高亮代码同时显示行号
_drafts文件夹工作方式
创建页面
主页
变量
全局变量
1. site变量
2. page变量
3. Paginator变量
通过Liquid模板系统可以自定义数据

什么是jekyll??

简单说：它是静态网页生成器。
具体点：包含一些用markdown语法写的文件的文件夹；通过markdown和Liquid转换器
生成一个网站。
同时jekyll也是github静态页面引擎。意味着你可以用jekyll生成你的页面，免费托管在github服务器。

快速开始

假设已经已经安装完Jekyll【安装方法 Ubuntu14.04+Jekyll+Github Pages搭建静态博客】

接下来创建本地静态博客，并进行操作（在Ubuntu14.04上试验）。

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 is, at its core, a text transformation engine. The concept behind the system is this: you give it text written in your favorite markup language, be that Markdown, Textile, or just plain HTML, and it churns that through a layout or series of layout files. Throughout that process you can tweak how you want the site URLs to look, what data gets displayed in the layout, and more. This is all done through editing text files, and the static web site is the final product.
（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字段）

如下，可以在config中配置不同范围（scope，即某个path下某个type的文件）下的默认值。这样子的话：

With these defaults, all posts would use the 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

Front Matter

Any file that contains a YAML front matter block will be processed by Jekyll as a special file. The front matter must be the first thing in the file and must take the form of valid YAML set between triple-dashed lines. Here is a basic example:（注意冒号后面至少要空一个空格，不然会出错）

通过这个可以设置一些变量（甚至可以自定义变量），比如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 }}

<!DOCTYPE HTML>
<html>
  <head>
    <title>{{ page.title }}</title>
  </head>
  <body>
    ...

post预定义的变量：date

写文章

jekyll有一个最好的特性就是：你写文章并发表他们只是意味着你只要管理一些文本文件即可。
而不需要配置和维护数据库以及良好的CMS系统。

发文章的文件夹：

_posts
里面都是些Markdown或者HTML文件。只要有yaml front matter，它们就会被转换为html格式的静态页面。

All posts must have YAML Front Matter, and they will be converted from their source format into an HTML page that is part of your static site.

创建post文件：

命名规范比较严格，

创建一个文件，其格式为：YEAR-MONTH-DAY-title.MARKUP

YEAR是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）的样式改变而访问不到。

【备注】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

内容的样式：

所有的文章都必须要有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>

【转】jekyll 的使用

原文：http://www.cnblogs.com/mo-wang/p/5117408.html

踩

(0)

评论一句话评论（0）

分享档案

更多>

2021年09月23日 (328)
2021年09月24日 (313)
2021年09月17日 (191)
2021年09月15日 (369)
2021年09月16日 (411)
2021年09月13日 (439)
2021年09月11日 (398)
2021年09月12日 (393)
2021年09月10日 (160)
2021年09月08日 (222)