Jekyll使用教程筆記一

時間 2019-11-16

標籤 jekyll 使用教程筆記简体版

原文原文鏈接

目錄css

簡介

Jekyll是一個簡單的，博客感知的靜態站點生成器。html

你將內容建立爲文本文件（Markdown），並將其放到到文件夾中。而後，使用Liquid-enhanced HTML模板構建網站。Jekyll自動將內容和模板聯繫在一塊兒，生成徹底由靜態資源組成的網站，它適合上傳到任何服務器。git

Jekyll剛好是GitHub Pages的引擎，所以你能夠在GitHub的服務器上免費託管項目的Jekyll頁面/博客/網站。github

快速開始

若是你已經安裝了包含全部頭文件和RubyGems的完整的Ruby開發環境（請參閱Jekyll的要求），你能夠經過執行如下操做來建立一個新的Jekyll站點：json

# 經過RubyGems安裝Jekyll和Bundler gems
gem install jekyll bundler
# 若是沒法安裝請嘗試：sudo gem install jekyll bundler
# 上面兩個命令都沒法安裝，請嘗試：sudo gem install -n /usr/local/bin jekyll bundler
# 若是仍沒法解決，請嘗試關閉SIP

# 在./myblog建立一個新的Jekyll站點
jekyll new myblog

# 進入到生成的文件夾中
cd myblog

# 在本地預覽服務中編譯站點
bundle exec jekyll serve

# 瀏覽器裏面打開 http://localhost:4000
複製代碼

若是你在上述過程當中遇到任何意外錯誤，好比可能缺乏開發頭文件或其餘先決條件，請參閱故障排除頁面或前面提到的需求頁面。瀏覽器

關於Bundler

gem install bundler命令將經過RubyGems安裝bundler gem。你只須要安裝一次便可——不用每次建立一個Jekyll項目的時候都安裝一次。這裏有一些額外的細節：sass

bundler是一個管理其餘Ruby gems的gem。它確保你的gems和gem版本兼容，而且確保包含每一個gem須要的必須依賴。ruby
Gemfile和Gemfile.lock文件將告知Bundler有關於你的站點中的gem依賴。若是你的站點沒有這些Gemfile文件，則能夠省略bundle exec命令，直接運行jekyll serve命令。bash
當你運行bundle exec jekyll serve時，Bundler使用Gemfile.lock中指定的gem和版原本確保你的Jekyll站點沒有兼容性或依賴衝突。服務器

有關如何在Jekyll項目中使用Bundler的更多信息，這個教程能夠爲最多見的問題提供答案，並解釋如何快速啓動和運行。

使用Jekyll建立一個新的站點的選項

jekyll new <PATH>在指定的路徑（相對於當前目錄）安裝一個新的Jekyll站點。在上面列出的命令行的狀況下，Jekyll將被安裝在當前目錄下的名爲myblog的目錄中。這裏有一些額外的細節：

要將Jekyll站點安裝到你當前所在的目錄中，請運行jekyll new .。若是現有的目錄不是空的，你可使用jekyll new . --force傳遞--force選項。
jekyll new會自動啓動bundle install以安裝所需的依賴關係。（若是你不想讓Bundler安裝gem，請使用jekyll new myblog --skip-bundle。）
默認狀況下，由jekyll new安裝的Jekyll站點使用一個叫作爲Minima的基於gem的主題。使用基於gem的主題，一些目錄和文件存儲在gem主題中，隱藏在你的即時視圖中。
咱們建議你將Jekyll設置爲基於gem的主題，但若是你想從空白的模版開始，請使用jekyll new myblog --blank。
要了解其餘參數，你可使用jekyll new，輸入jekyll new --help便可。

若是有疑問，請使用help命令來提示你全部可用的選項和用法，它也適用於new和build以及serve命令，例如，jekyll help new或jekyll help build。

基本用法

Jekyll gem在終端窗口中爲你提供了一個jekyll可執行文件。你能夠經過多種方式使用此命令：

jekyll build
# => 當前文件夾中的內容將被生成到./_site

jekyll build --destination <destination>
# => 當前文件夾中的內容將被生成到<destination>

jekyll build --source <source> --destination <destination>
# => <source>文件夾中的內容將被生成到<destination>

jekyll build --watch
# => 當前文件夾中的內容將被生成到./_site,
# 檢查改動，並自動從新生成。
複製代碼

重寫默認開發配置

開發環境的默認預覽地址是http://localhost:4000。[3.3.0]

若是你想爲你的生產環境構建：

在_config.yml中設置你的生產環境URL。例如：https://example.com。
運行JEKYLL_ENV=production bundle exec jekyll build。

注意: _config.yml的更改並不會在自動生成更新過程當中生效。

_config.yml主要配置文件會在執行時讀取一次全局配置和變量定義。在下次執行以前，不會加載在自動生成更新期間對_config.yml所作的更改。

注意，自動生成更新過程當中會對Data Files從新加載。

警告：目標文件夾在網站構建的時候會被清空

默認狀況下，當網站構建的時候，<destination>中的內容會被自動的清空。不是被你的網站構建時所建立的文件和文件夾都會被刪除。能夠在<keep_files>配置指令中指定你但願保留在中的文件和文件夾。

不要設置爲重要本地路徑；相反，應該將其用做暫存區域並將文件從那裏複製到你的Web服務器。

Jekyll還附帶了一個內置的開發服務器，可讓你在本地瀏覽中瀏覽生成的網站。

jekyll serve
# => 開發服務將會運行在http://localhost:4000/
# 自動生成更新會被開啓，若是不想開啓請使用`--no-watch`。

jekyll serve --no-watch
# => 等同於`jekyll serve`，可是內容更改時不會自動生成新的。

jekyll serve --livereload
# LiveReload將在更新後刷新瀏覽器頁面。

jekyll serve --incremental
# Incremental將會匹配更改部分，執行部分構建以減小自動生成更新時間。

jekyll serve --detach
# => 等同於`jekyll serve`，可是不會再當前終端中顯示運行狀態，而是轉爲後臺模式。
# 若是你須要關閉服務，你能夠`kill -9 1234`，這裏的"1234"是PID。
# 若是你不知道PID，那麼就執行`ps aux | grep jekyll`並關閉這個實例。
複製代碼

這些只是幾個可用的配置選項。許多配置選項能夠在命令行中指定爲flags，或者（更常見）它們能夠在源目錄的根目錄下的_config.yml文件中指定。運行時，Jekyll會自動使用該文件中的選項。例如，若是將如下行放在_config.yml文件中：

source:      _source
destination: _deploy
複製代碼

那麼如下兩個命令將是等效的：

jekyll build
# 上面的命令添加過配置後等於下面的命令沒加配置
jekyll build --source _source --destination _deploy
複製代碼

有關配置選項的更多信息，請參閱配置頁面。

注意：尋求幫助

help命令老是在這裏提示你全部可用的選項和用法，它也適用於new和build以及serve命令，例如，jekyll help new或jekyll help build。

若是你有興趣想要隨時瀏覽這些文檔，請安裝jekyll-docsgem，並在你的終端中運行jekyll docs。

目錄結構

Jekyll的核心是一個文本轉換引擎。這個系統的大概是：你給它的內容能夠用你最喜歡的標記語言編寫，能夠是Markdown，是Textile或者是純粹的HTML，而後Jekyll經過一個或一系列佈局文件混合它們。在整個過程當中，你能夠調整網站URL的樣式，佈局中顯示的數據等等。這一切都是經過編輯文本文件完成的，而靜態網站就是它的最終產品。

基本的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
|   ├── 2007-10-29-why-every-programmer-should-play-nethack.md
|   └── 2009-04-26-barcamp-boston-4-roundup.md
├── _sass
|   ├── _base.scss
|   └── _layout.scss
├── _site
├── .jekyll-metadata
└── index.html # can also be an 'index.md' with valid YAML Frontmatter
複製代碼

注意：使用基於gem的主題的Jekyll網站的目錄結構

始於Jekyll 3.2，一個使用jekyll new建立的基於gem的主題來定義網站外觀的新的Jekyll項目，會有一個比較簡單的默認目錄結構：默認狀況下，_layouts，_includes和_sass會被存儲在theme-gem中，而不是放在項目目錄中。

minima是當前的默認主題，bundle show minima會告訴你minima主題的文件存儲在計算機上的哪一個位置。

目錄結構說明：

文件/文件夾	說明
`_config.yml`	存儲配置數據。這些配置中的許多選項均可以從命令行中指定，但在這裏指定它們更加容易，而且你沒必要記住它們。
`_drafts`	草稿是未發佈的文章。這些文件的命名格式是沒有日期的：`title.MARKUP`。瞭解如何使用草稿。
`_includes`	These are the partials that can be mixed and matched by your layouts and posts to facilitate reuse. The liquid tag {% include file.ext %} can be used to include the partial in _includes/file.ext.
`_layouts`	這些是包裝文章的模板。在YAML Front Matter中逐層選擇佈局，這將在下一節中介紹。 The liquid tag `{{ content }}`用於將內容注入網頁。
`_posts`	能夠這麼說，這裏是你的動態內容。這些文件的命名約定很重要，而且必須遵循如下格式：`YEAR-MONTH-DAY-title.MARKUP`。能夠爲每篇文章指定固定連接，但日期和MARKUP語言徹底由文件名決定。
`_data`	格式良好的網站數據應該放在這裏。Jekyll引擎將自動加載該目錄中的全部數據文件（使用`.yml`，`.yaml`，`.json`或`.csv`格式和擴展名），而且能夠經過`site.data`訪問它們。若是目錄下有文件`members.yml`，則能夠經過`site.data.members`訪問該文件的內容。
`_sass`	些是能夠導入到`main.scss`中的sass部分，而後將它們處理成一個樣式表`main.css`，該樣式表定義了你的網站使用的樣式。
`_site`	這是Jekyll完成轉換後，生成的網站將被存放的（默認）位置。建議將它添加到`.gitignore`文件中。
`.jekyll-metadata`	臨時文件，這些將幫助Jekyll追蹤自上次構建站點後哪些文件未被修改，以及哪些文件須要在下一個版本中從新生成。該文件不會包含在生成的網站中。建議將它添加到.gitignore文件中。
`index.html`或`index.md`或其餘HTML、Markdown文件	假設該文件具備YAML Front Matter部分，它將由Jekyll進行轉換。網站根目錄中的任何`.html`，`.markdown`，`.md`或`.textile`文件或上面未列出的目錄也會發生一樣的狀況。
其餘文件/文件夾	除了上面列出以外的其餘文件夾和文件（例如`css`和`images`文件夾，`favicon.ico`文件等），將會被逐字複製到生成的網站中。若是你想知道它們是如何佈置的，有不少網站已經在使用Jekyll。