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教程