配置

Jekyll 帮你轻松的搭建你的网站,这很大程度上归功于灵活强大的配置功能。既可以在网站根目录下的 _config.yml 文件中进行配置,也可以作为命令行参数来配置。

配置设置

全局配置

下表中列举了所有 Jekyll 可用的设置,和多种多样的 配置项 (配置文件中) 及 参数 (命令行中)。

设置 配置项参数

Site Source

改变 Jekyll 读取文件的目录

source: DIR

-s, --source DIR

Site Destination

改变 Jekyll 写入文件的目录

destination: DIR

-d, --destination DIR

Safe

禁用 自定义插件

safe: BOOL

--safe

Exclude

转换时排除某些文件夹或文件。被排除的文件或文件夹的路径是相对于网站源码目录的,源码目录以外不受影响。

exclude: [DIR, FILE, ...]

Include

转换时强制包含某些文件、文件夹。 .htaccess 是个典型的例子,因为默认排除 .(dot,英文中的句号) 开头的文件。

include: [DIR, FILE, ...]

Time Zone

设置时区,这个设置作用于 TZ 变量, Ruby 用它来处理日期和时间。 IANA Time Zone Database 里边的都有效,比如 America/New_York 。默认值为操作系统的时区。

timezone: TIMEZONE

Encoding

设置文件的编码,仅 Ruby 1.9 以上可用。默认值为 nil ,使用 Ruby 默认的 ASCII-8BIT。可以用命令 ruby -e 'puts Encoding::list.join("\n")' 查看 Ruby 可用的编码。

encoding: ENCODING

编译选项

设置 配置项参数

Regeneration

允许文件修改时自动重新生成网站。

-w, --watch

Configuration

手动设置配置文件并替代_config.yml,可设置多个,且后边的设置会覆盖前边的。

--config FILE1[,FILE2,...]

Drafts

处理草稿

--drafts

Future

用将来的日期发布文章

future: BOOL

--future

LSI

为相关文章生成索引

lsi: BOOL

--lsi

Limit Posts

限制文章的数量

limit_posts: NUM

--limit_posts NUM

服务选项

除了下边的选项, serve 命令还可以接收 build 的选项,当运行网站服务之前的编译时候使用。

设置 配置项参数

Local Server Port

监听所给的端口

port: PORT

--port PORT

Local Server Hostname

监听所给的主机名

host: HOSTNAME

--host HOSTNAME

Base URL

网站的根路径

baseurl: URL

--baseurl URL

Detach

从终端命令行中分离出来

detach: BOOL

-B, --detach

不要在配置文件中使用 tab 制表符

这将造成解析错误,或倒回到默认设置。请使用空格替代。

默认配置

Jekyll 默认使用以下的配置。除非在配置文件中存在相同的配置项或在命令行中指定参数,否则 Jekyll 将使用以下配置运行。

有两个 kramdown 的选项不被支持

注意 Jekyll 目前不支持 remove_block_html_tagsremove_span_html_tags ,因为没有被包含到 kramdown HTML 转换器中。

source:      .
destination: ./_site
plugins:     ./_plugins
layouts:     ./_layouts
include:     ['.htaccess']
exclude:     []
keep_files:  ['.git','.svn']
gems:        []
timezone:    nil
encoding:    nil

future:      true
show_drafts: nil
limit_posts: 0
highlighter: pygments

relative_permalinks: true

permalink:     date
paginate_path: 'page:num'
paginate:      nil

markdown:      maruku
markdown_ext:  markdown,mkd,mkdn,md
textile_ext:   textile

excerpt_separator: "\n\n"

safe:        false
watch:       false    # deprecated
server:      false    # deprecated
host:        0.0.0.0
port:        4000
baseurl:     /
url:         http://localhost:4000
lsi:         false

maruku:
  use_tex:    false
  use_divs:   false
  png_engine: blahtex
  png_dir:    images/latex
  png_url:    /images/latex
  fenced_code_blocks: true

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
  use_coderay: false

  coderay:
    coderay_wrap: div
    coderay_line_numbers: inline
    coderay_line_numbers_start: 1
    coderay_tab_width: 4
    coderay_bold_every: 10
    coderay_css: style

redcloth:
  hard_breaks: true

Markdown 选项

Jekyll 支持的 Markdown 渲染器中有的有额外的选项。

Redcarpet

Redcarpet支持设置 extensions ,值为一个字符串数组,每个字符串都是 Redcarpet::Markdown 类的扩展,相应的扩展就会设置为 true

Jekyll handles two special Redcarpet extensions:

  • no_fenced_code_blocks — 默认的, Jekyll 设置扩展 fenced_code_blocks (用三个波浪线或重音线标记代码区间) 为 true ,这或许是跟 GitHub 积极的采用有关。当使用Jekyll的时候, Redcarpet 的扩展 fenced_code_blocks 无效,作为替代方案,你可以这样做:

    注意你还可以这样来配置语言以支持语法高亮:

      ```ruby
      # ...ruby code
      ```

    有了 both fenced code blocks 和 pygments ,就会直接高亮代码了;如果没有 pygments,将增加一个 class="LANGUAGE" 属性到 <code> 元素,用于给不同的 JavaScript 代码高亮库做后续处理。

  • smart — 打开 SmartyPants ,将引号转为 " 、连字符转为 em (---) 和 en (--) 破折号。

Redcarpet 所有其他扩展保持他们本来的名字,并且在 Jekyll 中不能给 smart 加渲染选项。 Redcarpet 的 README 中有可用扩展的列表。 确保你看的 README 是正确的版本: Jekyll 当前用的是 v2.2.x ,其中 footnoteshighlight 在 3.0.0 以后才会支持。最常用的扩展是如下:

  • tables
  • no_intra_emphasis
  • autolink

Kramdown

除了上述提到的默认配置,你还可以给 Kramdown 传递值为 “GFM” 的 input 选项,从而启用 Github 扩展的 Markdown 语法。

例如,在 _config.yml 文件中加入以下配置项:

kramdown:
  input: GFM