Jekyll使用教程笔记 二

时间  2019-11-16
标签 jekyll 使用 教程 笔记 繁體版
原文   原文链接

目录css

配置

Jekyll容许你用任何你能够想象的方式调试你的网站，这要感谢这些强大而灵活的配置选项。这些选项能够在放置在站点根目录中的_config.yml文件中指定，也能够在终端中指定为jekyll的flags。html

配置设置

全局配置

下表列出了Jekyll的可用设置，以及控制它们的各类options（在配置文件中指定）和flags（在命令行中指定）。前端

设置 options flags
网站源文件
改变Jekyll读取文件的文件夹		 source: DIR -s, --source DIR
网站生成位置
改变Jekyll写入文件的文件夹		 destination: DIR d, --destination DIR
安全
禁用自定义插件，并忽略符号连接。		 safe: BOOL --safe
排除
在转换过程当中排除目录和/或文件。这些排除的文件必须在网站的源目录以内，不能在源目录以外。		 exclude: [DIR, FILE, ...]
包含
在转换过程当中强制包含目录和/或文件。 .htaccess是一个很好的例子，由于默认状况下dotfiles是被排除的。		 include: [DIR, FILE, ...]
时区
设置网站生成的时区。这设置了TZ环境变量，Ruby用它来处理时间和日期的建立和操做。IANA时区数据库中的全部条目均有效，例如，America/New_York。全部可用值均可以在这个列表中找到。在本地机器上运行时，默认时区是你的操做系统设置的时区。可是，当在远程主机/服务器上时，默认时区取决于服务器的设置或位置。		 timezone: TIMEZONE
编码格式
按名称设置文件的编码格式（仅适用于Ruby 1.9或更高版本）。 缺省值是从2.0.0开始的utf-8，在2.0.0以前为nil，这将使用默认的ASCII-8BIT。可用的编码能够经过命令ruby -e 'puts Encoding::list.join("\n")'展现。		 encoding: ENCODING
默认
为YAML Front Matter变量设置默认值。		 见下文

警告：目标文件夹在网站构建的时候会被清空node

默认状况下，当网站构建的时候，<destination>中的内容会被自动的清空。不是被你的网站构建时所建立的文件和文件夹都会被删除。能够在<keep_files>配置指令中指定你但愿保留在中的文件和文件夹。git

不要设置为重要本地路径；相反，应该将其用做暂存区域并将文件从那里复制到你的Web服务器。github

构建（编译）配置选项

设置 options flags
生成更新
修改文件时启用站点的自动生成更新。		 -w, --[no-]watch
构造
指定配置文件而不是使用默认的_config.yml。后设置的文件中的设置会覆盖以前文件中的设置。		 --config FILE1[,FILE2,...]
草稿
处理并渲染草稿文章。		 show_drafts: BOOL --drafts
环境
使用指定的环境构建。		 JEKYLL_ENV=production
将来
发布还没有到达日期的文章或文集。		 future: BOOL --future
未公开
渲染未公开的文章。		 unpublished: BOOL --unpublished
LSI
生成相关文章的索引。须要classifier-reborn插件。		 lsi: BOOL --lsi
限制文章数量
限制解析和发布文章的数量。		 limit_posts: NUM --limit_posts NUM
强制轮询
强制使用轮询检测更新		 --force_polling
输出详情
打印详细的输出		 -V, --verbose
静默输出
在构建过程当中让Jekyll保持正常输出		 -q, --quiet
增量构建
启用增量构建的试验功能。增量构建仅从新构建已更改的文章和页面，从而显着改善大型网站的性能，但也可能在某些状况下破坏网站生成。		 incremental: BOOL -I, --incremental
Liquid分析
生成Liquid渲染配置文件以帮助你识别性能瓶颈		 profile: BOOL --profile
严格格式模式
若是页面前端存在YAML语法错误，则会致使构建失败。		 strict_front_matter: BOOL --strict_front_matter

服务命令选项

除了如下选项以外，serve子命令还能够接受build子命令的全部选项，而后将这些选项应用于在站点提供以前发生的站点构建。web

设置 options flags
本地服务器端口
监听给定的端口号		 port: PORT --port PORT
本地服务器主机名
监听给定的主机名		 host: HOSTNAME --host HOSTNAME
基本地址
从给定的基本网址提供网站		 baseurl: URL --baseurl URL
分离
从终端分离服务器		 detach: BOOL -B, --detach
跳过最初的网站构建
跳过服务器启动以前发生的初始站点构建。		 --skip-initial-build
X.509 (SSL) 私钥
SSL私钥		 --ssl-key
X.509 (SSL) 证书
SSL公共证书		 --ssl-cert

警告：不要在配置文件中使用tab数据库

这将致使解析错误，或者Jekyll将恢复使用默认设置。请改用空格。数组

自定义WEBrick标题

你能够经过添加它们到_config.yml来为你的网站提供自定义标头缓存

# File: _config.yml
webrick:
 headers:
 My-Header: My-Value
 My-Other-Header: My-Other-Value
复制代码

默认

咱们默认提供Content-Type和Cache-Control响应头文件：一个动态为了指定被服务的数据的性质，另外一个静态为了禁用缓存。因此当你处于开发模式时，你没必要与Chrome的缓存做斗争。

在构建时指定一个Jekyll环境

在build（或serve）参数中，你能够指定Jekyll环境和值。而后，build将在你的内容中的全部条件语句中应用此值。

例如，假设你在代码中设置了这个条件语句：

{% if jekyll.environment == "production" %}
   {% include disqus.html %}
{% endif %}
复制代码

当你构建Jekyll站点时，除非你在build命令中指定production环境，不然if语句内的内容将不会运行，以下所示：

JEKYLL_ENV=production jekyll build
复制代码

指定环境值可以让你仅在特定环境中使某些内容可用。

JEKYLL_ENV的默认值是development。所以，若是你从构建参数中省略JEKYLL_ENV，则会使用默认值为JEKYLL_ENV=development。那么{% if jekyll.environment == "development" %}标签中的全部内容都会自动出如今构建中。

构建环境的值能够是你想要的任何值（不仅是development或production）。你可能但愿在开发环境中隐藏一些元素，好比说Disqus评论表单或Google Analytics。相反，你也可能想在开发环境中展现“在GitHub中编辑我”的按钮，但不想将其展现在生产环境中。

经过在build命令中指定选项，可避免在从一个环境转换到另外一个环境时必须更改配置文件中的值。

Front Matter defaults

使用YAML Front Matter是使你能够在网站的页面和文章中指定配置的一种方式。设置默认布局或自定义标题，或为文章指定更精确的日期/时间等均可以添加到你的页面或文章中。

不少时候，你会发现你重复了不少配置选项。好比在每一个文件中设置相同的布局，将相同的一个或多个类别添加到文章等。你甚至能够添加自定义变量，如做者姓名，这些可能与博客上大多数文章中的相同。

Jekyll提供了一种在网站配置中设置这些默认值的方法，而不是每次建立新文章或页面时重复此配置。为此，你可使用项目根目录中的_config.yml文件中的defaults指定站点范围的默认值。

defaults包含一个由scope/values对组成的数组，用于定义应为特定文件路径设置哪些默认值，以及可选的文件类型。

假设你想要将默认布局添加到网站中的全部页面和文章中。你能够将它添加到你的_config.yml文件中：

defaults:
 -
 scope:
 path: "" # 这里的空字符串表示项目中的全部文件
 values:
 layout: "default"
复制代码

注意：请中止并从新运行jekyll serve命令。

_config.yml主要配置文件会在执行时读取一次全局配置和变量定义。在下次执行以前，不会加载在自动生成更新期间对_config.yml所作的更改。

注意，自动生成更新过程当中会对Data Files从新加载。

在这里，咱们将values设定到scope路径中存在的全部文件。因为路径设置为空字符串，所以它将应用于项目中的全部文件。你可能不但愿在项目中的每一个文件上设置一样的布局——好比css文件，那么你还能够在scope下指定一个type。

defaults:
 -
 scope:
 path: "" # 这里的空字符串表示项目中的全部文件
 type: "posts" # previously `post` in Jekyll 2.2.
 values:
 layout: "default"
复制代码

如今，只会为类型为posts的文件设置布局。你可使用的类型有pages，posts，drafts或你网站中的任何合集。虽然type是可选的，但你在建立一个scope/values对时必须为path指定一个值。

如前所述，你能够将多个scope/values对设置为defaults。

defaults:
 -
 scope:
 path: ""
 type: "pages"
 values:
 layout: "my-site"
 -
 scope:
 path: "projects"
 type: "pages" # previously `page` in Jekyll 2.2.
 values:
 layout: "project" # 覆盖以前的默认布局
 author: "Mr. Hyde"
复制代码

使用这些默认值，全部页面都将使用my-site布局。存在于projects/文件夹中的全部html文件（若是存在）都将使用project布局，这些文件还将具备设置为Mr. Hyde的page.author liquid variable。

collections:
 my_collection:
 output: true

defaults:
 -
 scope:
 path: ""
 type: "my_collection" # a collection in your site, in plural form
 values:
 layout: "default"
复制代码

在这个例子中，名称为my_collection的合集中的layout被设置为default。

Glob patterns in Front Matter defaults

当匹配默认值时，也可使用glob模式（当前仅限于包含*的模式）。例如，能够为section文件夹的任何子文件夹中的每一个special-page.html设置特定的布局。[3.7.0]

collections:
 my_collection:
 output: true

defaults:
 -
 scope:
 path: "section/*/special-page.html"
 values:
 layout: "specific-layout"
复制代码

警告：Globbing and Performance

请注意，已知使用glob模式会对性能产生负面影响，目前还没有优化，尤为是在Windows上。使用glob模式将按照关联的合集目录的多少增长构建时间。

优先权

Jekyll将应用你在_config.yml文件的defaults部分中指定的全部配置设置。可是，你能够选择经过为scope指定更具体的path来覆盖其余scope/values对中的设置。

你能够在上面的倒数第三个例子中看到。首先，咱们将默认页面布局设置为my-site。而后，使用更具体的路径，咱们将projects/路径中的页面的默认布局设置为project。这能够经过你在页面或后置事项中设置的任何值来完成。

最后，若是你经过向_config.yml文件添加默认部分来在网站配置中设置默认值，则能够经过文章或页面文件中的这些设置进行覆盖。你须要作的就是在文章或页面front matter中指定设置。例如：

# In _config.yml
...
defaults:
 -
 scope:
 path: "projects"
 type: "pages"
 values:
 layout: "project"
 author: "Mr. Hyde"
 category: "project"
...
# In projects/foo_project.md
---
author: "John Smith"
layout: "foobar"
---
The post text goes here...
复制代码

projects/foo_project.md布局将被设置为foobar而不是project，而且在构建站点时将author设置为John Smith而不是Mr. Hyde。

默认选项

Jekyll默认运行下列配置选项。能够在配置文件或命令行中明确指定来替换对应的这些选项的设置。

警告：有两个不支持的kramdown选项

请注意，在Jekyll中，remove_block_html_tags和remove_span_html_tags目前都不受支持，由于它们不包含在kramdown HTML转换器中。

# Where things are
source:          .
destination:     ./_site
collections_dir: .
plugins_dir:     _plugins
layouts_dir:     _layouts
data_dir:        _data
includes_dir:    _includes
collections:
 posts:
 output:   true

# Handling Reading
safe:                false
include:             [".htaccess"]
exclude:             ["Gemfile", "Gemfile.lock", "node_modules", "vendor/bundle/", "vendor/cache/", "vendor/gems/", "vendor/ruby/"]
keep_files:          [".git", ".svn"]
encoding:            "utf-8"
markdown_ext:        "markdown,mkdown,mkdn,mkd,md"
strict_front_matter: false

# Filtering Content
show_drafts: null
limit_posts: 0
future:      false
unpublished: false

# Plugins
whitelist: []
plugins:   []

# 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
show_dir_listing: false

# Outputting
permalink:     date
paginate_path: /page:num
timezone:      null

quiet:    false
verbose:  false
defaults: []

liquid:
 error_mode:       warn
 strict_filters:   false
 strict_variables: false

# Markdown Processors
rdiscount:
 extensions: []

redcarpet:
 extensions: []

kramdown:
 auto_ids:      true
 entity_output: as_char
 toc_levels:    1..6
 smart_quotes:  lsquo,rsquo,ldquo,rdquo
 input:         GFM
 hard_wrap:     false
 footnote_nr:   1
 show_warnings: false
复制代码

Liquid选项

Liquid对错误的响应能够经过设置error_mode进行配置。选项是

  • lax — 忽略全部错误。
  • warn — 在控制台中输出每个错误的警告。
  • strict — 遇到错误打印并中止构建。

你还能够配置Liquid的渲染器，经过分别将strict_variables和/或strict_filters设置为true来捕获未分配的变量和不存在的过滤器。[3.8.0]

请注意，尽管error_mode配置了Liquid的解析器，但strict_variables和strict_filters选项配置了Liquid的渲染器，所以是互不干扰的。

Markdown选项

Jekyll支持的各类Markdown渲染器有时会提供额外的选项。

Redcarpet

能够经过提供extensions子设置来配置Redcarpet，其值应该是一个字符串数组。每一个字符串都应该是Redcarpet::Markdown类的扩展名之一;若是存在于数组中，它会将相应的扩展名设置为true。

Jekyll处理两个特殊的Redcarpet扩展：

  • no_fenced_code_blocks —— 默认状况下，Jekyll将fenced_code_blocks扩展名（用于将具备```或三个反引号的代码块）设置为true，多是由于GitHub急于采用它们开始使它们成为不可避免的。与Jekyll一块儿使用时，Redcarpet的正常fenced_code_blocks扩展是惰性的; 相反，你可使用此反向版本的扩展来禁用代码块。

请注意，你也能够在第一个分隔符以后指定一种突出显示的语言：

```ruby
    # ...ruby code
    ```
复制代码

同时启用代码块和荧光笔，这将静态突出显示代码;若是没有任何语法高亮显示，它会向<code>元素添加class="LANGUAGE"属性，该元素可用做各类JavaScript代码高亮显示库的提示。

  • smart —— 这个伪扩展打开SmartyPants，它将直引号转换为卷曲引号和连字符运行到em（---）和en（--）破折号。

全部其余扩展名保留了来自Redcarpet的一般名称，而且在Jekyll中不能指定除smart以外的渲染器选项。可用的扩展名列表能够在Redcarpet README文件中找到。确保你正在查看适合版本的Redcarpet的README：Jekyll目前使用v3.2.x. 最经常使用的扩展名是：

  • tables
  • no_intra_emphasis
  • autolink

自定义Markdown处理器

若是你有兴趣建立自定义Markdown处理器，那么你很幸运！在Jekyll::Converters::Markdown命名空间中建立一个新类：

class Jekyll::Converters::Markdown::MyCustomProcessor
  def initialize(config)
    require 'funky_markdown'
    @config = config
  rescue LoadError
    STDERR.puts 'You are missing a library required for Markdown. Please run:'
    STDERR.puts ' $ [sudo] gem install funky_markdown'
    raise FatalException.new("Missing dependency: funky_markdown")
  end

  def convert(content)
    ::FunkyMarkdown.new(content).convert
  end
end
复制代码

一旦你建立了你的类，而且正确地将它设置为_plugins文件夹中的一个插件或一个gem，请在_config.yml中指定它：

markdown: MyCustomProcessor
复制代码

Incremental Regeneration

警告：Incremental regeneration还是一个实验性的功能

尽管Incremental regeneration将适用于最多见的状况，但它在任何状况下都有可能没法正常工做。请谨慎使用该功能，并经过在GitHub上打开问题来报告如下未列出的任何问题。

Incremental regeneration有助于缩短构建时间，只生成自上一次构建后更新的文档和页面。它经过跟踪文件修改时间和.jekyll-metadata文件中的文档间依赖关系来实现这一点。

在当前的实现下，Incremental regeneration只会生成文档或页面（若是它或其某个依赖项被修改）。目前，跟踪的依赖类型有引用（使用{% include %}标记）和布局。这意味着对其余文档的简单引用（例如，在文章列表页面上迭代 site.posts的常见状况）将不会被检测为依赖项。

为了弥补这些不足之处，在文档的前端添加regenerate: true将迫使Jekyll从新生成它，不管它是否已被修改。请注意，这只会生成指定的文档;对其余文档的内容的引用将不起做用，由于它们不会被从新渲染。

能够经过命令行中的--incremental标志（简称-I）或经过在配置文件中设置incremental: true来启用Incremental regeneration。

相关文章
相关标签/搜索
每日一句
    每一个你不满意的现在，都有一个你没有努力的曾经。
本站公众号
   欢迎关注本站公众号,获取更多信息
联系我们 最近搜索 最新文章 沪ICP备13005482号-10 MyBatis教程 SQL 教程 MySQL教程 Java 教程 Thymeleaf 教程 Hibernate教程 Spring教程 Redis教程