Jekyll

Posted on Jun 30, 2017 By ᵇᵒ

Welcome

Jekyll是一个简单的静态博客站点生成器。它有一个模版目录，其中包含各种格式的原始文件，通过Markdown（或者Textile）以及Liquid转化成一个完整的可发布的静态网站。Jekyll也可以运行在GitHub Page上，你可以使用GitHub的服务来搭建你的项目页面、博客或者网站，完全免费。

Installation

Requirements

  • 操作系统:GNU/Linux, Unix, 或者 macOS. Windows没有正式支持,想尝试可以查看文档.
  • Ruby v2.1及以上, 包括所有依赖.
  • RubyGems
  • GCC & Make (这两个一般系统都会默认有安装,可通过 gcc -v 和 make -v 来确认)

如果是Jekyll 2及之前版本,还需要安装:

Install with RubyGems

官方推荐最好的安装方式是使用RubyGems,Jekyll的所有gem依赖包都会被自动安装
gem install jekyll

如果已经安装有Jekyll,可以使用命令查看:

jekyll --version
gem list jekyll

更新已有的老旧Jekyll版本:
gem update jekyll

Highlighting

Jekyll 3及以上使用Rouge,以前使用的是Pygments.
如果要在Jekyll 2使用Rouge,需要配置:
highlighter : rouge

Quick start

~ $ gem install jekyll
~ $ jekyll new myblog
~ $ cd myblog
~/myblog $ jekyll serve
# => Now browse to http://localhost:4000

系统会生成一个默认Minima主题的模板.

Tips

  • 可以通过安装bundle来管理gems,参考文档
  • 启动Jekyll服务还可以用命令:jekyll server.
    如果安装了bundle,还可以使用bundle exec jekyll serve

Basic Usage

jekyll clean
jekyll build
jekyll serve

很多命令都可以使用help,例如
jekyll help serve
jekyll serve -h
jekyll serve --help

Directory structure

使用tree命令可以得到jekyll模板的树形结构

.
├── _config.yml
├── _data
|   └── members.yml
├── _drafts
|   ├── begin-with-the-crazy-ideas.md
|   └── on-simplicity-in-technology.md
├── _includes
|   ├── footer.html
|   └── header.html
├── _layouts
|   ├── default.html
|   └── post.html
├── _posts
|   ├── 2017-06-30-blog.md
|   └── 2017-06-30-github-pages.md
├── _sass
|   ├── _base.scss
|   └── _layout.scss
├── _site
├── .jekyll-metadata
└── index.html # can also be an 'index.md' with valid YAML Frontmatter

_config.yml
保存配置数据.很多配置选项都会直接从命令行中进行设置，也可以把那些配置写在这儿，就不用非要去记住那些命令.
_drafts
drafts 是未发布的文章.
_includes
你可以部分或者全部加载这些文件到布局或者文章中以方便重用.可以用这个标签 {% include file.ext %} 来把文件 _includes/file.ext 包含进来.
_layouts
layouts 是包裹在文章外部的模板布局,可以在 YAML 头信息中根据不同文章进行选择. 标签 {{ content }} 可以将content插入页面中.
_posts
这里放的就是你的文章。文件格式很重要，必须要符合: YEAR-MONTH-DAY-title.MARKUP. The permalinks 可以在文章中自己定制，但是日期和标记语言都是根据文件名来确定的.
当然也可以自定义为其他格式,前提是必须保证定义出来的链接相互不会冲突.
_data
存放格式化的数据,jekyll引擎会自动加载所有的yaml文件(以.yml, .yaml, .json 或者 .csv等结尾的格式文件).
例如当前路劲下有个members.yml的文件,我们可以通过site.data.members来获取加载好的该文件所有内容.
_site
所有Jekyll完成转换后自动生成的页面都放在这里（默认）.最好将这个目录放进你的 .gitignore 文件中.
index.html and other HTML, Markdown, Textile files 如果这些文件中包含 YAML头信息 部分，Jekyll 就会自动将它们进行转换.当然，其他的如 .html， .markdown， .md，或者 .textile 等在你的站点根目录下或者不是以上提到的目录中的文件也会被转换.
Other Files/Folders
其他一些未被提及的目录和文件如 css 还有 images 文件夹， favicon.ico 等文件都将被完全拷贝到生成的 _site 中.

Jekyll Docs EN
Jekyll Docs CN