改善此頁面

主題

Jekyll 有一個廣泛的主題系統，允許你利用社群維護的範本和樣式來自訂你的網站呈現方式。Jekyll 主題指定外掛程式，並將資源、版面、包含和樣式表打包起來，你的網站內容可以覆寫這些設定。

挑選一個主題

你可以在不同的畫廊中尋找和預覽主題

• GitHub.com #jekyll-theme 存放庫
• jamstackthemes.dev
• jekyllthemes.org
• jekyllthemes.io
• jekyll-themes.com

另請參閱：資源。

了解基於 gem 的主題

當你 建立一個新的 Jekyll 網站（執行 jekyll new <PATH> 命令），Jekyll 會安裝一個使用名為 Minima 的基於 gem 的主題的網站。

對於基於 gem 的主題，網站的某些目錄（例如 assets、_data、_layouts、_includes 和 _sass 目錄）會儲存在主題的 gem 中，隱藏在你目前的檢視中。然而，所有必要的目錄都會在 Jekyll 的建置過程中讀取和處理。

在 Minima 的情況下，您只會在 Jekyll 網站目錄中看到下列檔案

.
├── Gemfile
├── Gemfile.lock
├── _config.yml
├── _posts
│   └── 2016-12-04-welcome-to-jekyll.markdown
├── about.markdown
└── index.markdown

Gemfile 和 Gemfile.lock 檔案由 Bundler 使用，以追蹤建立 Jekyll 網站所需的 gem 和 gem 版本。

基於 gem 的佈景主題讓佈景主題開發人員能更輕鬆地對擁有佈景主題 gem 的任何人提供更新。當有更新時，佈景主題開發人員會將更新推送到 RubyGems。

如果您有佈景主題 gem，您可以（如果您願意）執行 bundle update 來更新專案中的所有 gem。或者，您可以執行 bundle update <THEME>，將 <THEME> 替換為佈景主題名稱，例如 minima，以僅更新佈景主題 gem。佈景主題開發人員所做的任何新檔案或更新（例如樣式表或包含）都會自動拉進您的專案。

基於 gem 的佈景主題的目標是讓您獲得強大且持續更新的佈景主題的所有好處，而不用讓佈景主題的所有檔案阻礙您，或讓您在建立內容這個主要目標上變得過於複雜。

覆寫佈景主題預設值

Jekyll 佈景主題設定預設資料、版面、包含和樣式表。不過，您可以用您自己的網站內容覆寫任何佈景主題預設值。

若要取代佈景主題中的版面或包含，請在 _layouts 或 _includes 目錄中複製您想要修改的特定檔案，或從頭建立檔案，並給予與您想要覆寫的檔案相同的名稱。

例如，如果所選主題具有 page 版面配置，您可以在 _layouts 目錄（也就是 _layouts/page.html）中建立自己的 page 版面配置，以覆寫主題的版面配置。

在電腦上尋找主題檔案

1. 執行 bundle info --path，後接主題 gem 的名稱，例如，Jekyll 預設主題的 bundle info --path minima。

   這會傳回基於 gem 的主題檔案位置。例如，Minima 主題的檔案可能位於 macOS 上的 /usr/local/lib/ruby/gems/2.6.0/gems/minima-2.5.1。

2. 在 Finder 或檔案總管中開啟主題目錄

   # On MacOS
   open $(bundle info --path minima)
   
   # On Windows
   # First get the gem's installation path:
   #
   #   bundle info --path minima
   #   => C:/Ruby26-x64/lib/ruby/gems/3.1.3/gems/minima-2.5.1
   #
   # then invoke explorer with above path, substituting `/` with `\`
   explorer C:\Ruby26-x64\lib\ruby\gems\3.1.3\gems\minima-2.5.1
   
   # On Linux
   xdg-open $(bundle info --path minima)
   

   Finder 或檔案總管視窗會開啟，顯示主題的檔案和目錄。Minima 主題 gem 包含這些檔案

   .
   ├── LICENSE.txt
   ├── README.md
   ├── _includes
   │   ├── disqus_comments.html
   │   ├── footer.html
   │   ├── google-analytics.html
   │   ├── head.html
   │   ├── header.html
   │   ├── icon-github.html
   │   ├── icon-github.svg
   │   ├── icon-twitter.html
   │   └── icon-twitter.svg
   ├── _layouts
   │   ├── default.html
   │   ├── home.html
   │   ├── page.html
   │   └── post.html
   ├── _sass
   │   ├── minima
   │   │   ├── _base.scss
   │   │   ├── _layout.scss
   │   │   └── _syntax-highlighting.scss
   │   └── minima.scss
   └── assets
       └── main.scss
   

清楚了解主題檔案後，您現在可以透過在 Jekyll 網站目錄中建立一個名稱類似的檔案，來覆寫任何主題檔案。

舉個第二個例子，假設您想要覆寫 Minima 的頁尾。在您的 Jekyll 網站中，建立一個 _includes 資料夾，並在其中新增一個名為 footer.html 的檔案。Jekyll 現在會使用您網站的 footer.html 檔案，而不是 Minima 主題 gem 中的 footer.html 檔案。

若要修改任何樣式表，您必須執行額外步驟，將主 sass 檔案（Minima 主題中的 _sass/minima.scss）也複製到您網站原始碼中的 _sass 目錄。

在下列資料夾中，Jekyll 會先尋找您網站的內容，然後再尋找主題的預設值，以取得任何要求的檔案

• /assets
• /_data
• /_layouts
• /_includes
• /_sass

請注意，複製佈景主題檔案會讓您無法收到這些檔案的任何佈景主題更新。另一種方法是，在您自己額外、原始命名的 CSS 檔案中使用較高優先順序的 CSS 選擇器，以繼續在所有樣式表上取得佈景主題更新。

請參閱您所選佈景主題的文件和原始存放庫，以取得更多關於您可以覆寫哪些檔案的資訊。

具有 _data 目錄的佈景主題4.3.0

從 4.3.0 版開始，Jekyll 也會考量佈景主題的 _data 目錄。這允許資料在佈景主題之間進行分配。

一個典型的範例是設計元素中使用的文字。

想像一個佈景主題提供包含檔案 testimonials.html。這個設計元素在頁面上建立一個新的區段，並在見證清單上放置一個 h3 標題。

佈景主題開發人員可能會以英文撰寫標題，並直接將其放入 HTML 原始碼中。

佈景主題的使用者可以將包含的檔案複製到他們的專案中，並在那裡替換標題。

透過考量 _data 目錄，對於這個標準任務還有另一種解決方案。

設計人員不會將文字直接輸入設計範本，而是新增對文字目錄的參考（例如 site.data.i18n.testimonials.header），並在佈景主題的資料目錄中建立檔案 _data/i18n/testimonials.yml。

在這個檔案中，標題會放在 header 鍵之下，而 Jekyll 會處理其餘部分。

對於主題開發人員來說，這乍看之下當然比以前更費力。

然而，對於主題的使用者來說，自訂變得相當簡單。

想像一下，主題是由一位德國客戶使用的。為了讓她取得見證設計元素的翻譯標題，她只需要在專案目錄中建立一個資料檔案，其金鑰為 site.data.i18n.testimonials.header，將德文翻譯或她選擇的標題放在最上面，設計元素就已經自訂完成了。

她不再需要將包含的檔案複製到她的專案目錄中，在那裡自訂它，而且最重要的是，放棄主題的所有更新，只因為主題開發人員提供她透過文字檔案集中變更文字模組的可能性。

資料檔案提供了高度的彈性。主題開發人員放置文字模組的位置可能與主題使用者的位置不同，這可能會造成無法預見的麻煩！

關於上述範例，來自主題 _data/i18n/testimonials.yml 檔案的覆寫金鑰 site.data.i18n.testimonials.header 可以位於使用者的網站上的三個不同位置

• _data/i18n.yml，金鑰為 testimonials.header
• _data/i18n/testimonials.yml，金鑰為 header（這反映了給定範例的配置）
• _data/i18n/testimonials/header.yml，沒有任何金鑰，標題可以直接放到檔案中

主題開發人員在支援使用者的時候，應該要記住這個模稜兩可之處，這些使用者對於設定主題所提供的設計元素的文字模組感到不知所措。

在使用資料功能時，請自問，你所引用的金鑰是否會在存在或不存在時改變佈景主題的行為，或者它只是會顯示的資料而已。如果它會改變佈景主題的行為，則應該放入 site.config，否則透過 site.data 提供即可。

將會修改佈景主題行為的資料打包被視為反模式，強烈不建議使用。確保每個提供的資料都能夠輕易地被佈景主題的使用者覆寫，這是佈景主題作者的唯一責任。

將基於寶石的佈景主題轉換為一般佈景主題

假設你想要擺脫基於寶石的佈景主題，並將它轉換為一般佈景主題，其中所有檔案都存在於你的 Jekyll 網站目錄中，而佈景主題寶石中沒有儲存任何東西。

為此，請將檔案從佈景主題寶石的目錄複製到你的 Jekyll 網站目錄中。（例如，如果你在 /myblog 中建立你的 Jekyll 網站，請將它們複製到 /myblog。請參閱前一節瞭解詳細資訊。）

然後你必須告訴 Jekyll 佈景主題所引用的外掛程式。你可以在佈景主題的 gemspec 檔案中找到這些外掛程式，作為執行時期相依性。例如，如果你正在轉換 Minima 佈景主題，你可能會看到

spec.add_runtime_dependency "jekyll-feed", "~> 0.12"
spec.add_runtime_dependency "jekyll-seo-tag", "~> 2.6"

你應該在 Gemfile 中以兩種方式之一包含這些參考。

你可以在 Gemfile 和 _config.yml 中個別列出它們。

# ./Gemfile

gem "jekyll-feed", "~> 0.12"
gem "jekyll-seo-tag", "~> 2.6"

# ./_config.yml

plugins:
  - jekyll-feed
  - jekyll-seo-tag

或者，你可以將它們明確列為 Gemfile 中的 Jekyll 外掛程式，而不要更新 _config.yml，如下所示

# ./Gemfile

group :jekyll_plugins do
  gem "jekyll-feed", "~> 0.12"
  gem "jekyll-seo-tag", "~> 2.6"
end

不論如何，別忘了執行 bundle update。

如果你要發佈在 GitHub Pages，你應該只更新你的 _config.yml，因為 GitHub Pages 並不會透過 Bundler 來載入外掛。

最後，移除 Gemfile 和設定檔中對佈景主題寶石的參照。例如，要移除 minima

• 開啟 Gemfile 並移除 gem "minima", "~> 2.5"。
• 開啟 _config.yml 並移除 theme: minima。

現在 bundle update 將不會再取得佈景主題寶石的更新。

安裝基於寶石的佈景主題

使用 jekyll new <PATH> 指令並不是建立一個使用基於寶石的佈景主題的新 Jekyll 網站的唯一方法。你也可以在網路上找到基於寶石的佈景主題，並將它們納入你的 Jekyll 專案。

例如，在 RubyGems 上搜尋 jekyll theme，以尋找其他基於寶石的佈景主題。（請注意，並非所有佈景主題都使用 jekyll-theme 作為佈景主題名稱中的慣例。）

要安裝基於寶石的佈景主題

1. 將佈景主題寶石加入你網站的 Gemfile

   # ./Gemfile
   
   # This is an example, declare the theme gem you want to use here
   gem "jekyll-theme-minimal"
   

   或者如果你已經使用 jekyll new 指令開始，請用你想要的寶石取代 gem "minima", "~> 2.0"，例如

   # ./Gemfile
   
   - gem "minima", "~> 2.5"
   + gem "jekyll-theme-minimal"
   

2. 安裝佈景主題

   bundle install
   

3. 將以下內容新增至網站的 _config.yml 以啟用佈景主題

   theme: jekyll-theme-minimal
   

4. 建置您的網站

   bundle exec jekyll serve
   

您可以在網站的 Gemfile 中列出多個佈景主題，但只能在網站的 _config.yml 中選擇一個佈景主題。

如果您在 GitHub Pages 上發佈您的 Jekyll 網站，請注意 GitHub Pages 僅支援 部分基於 gem 的佈景主題。GitHub Pages 也支援 使用任何佈景主題，這些佈景主題已在 GitHub 上架，並使用 remote_theme 設定，就好像它是基於 gem 的佈景主題一樣。

建立基於 gem 的佈景主題

如果您是 Jekyll 佈景主題開發人員（而非佈景主題使用者），您可以將您的佈景主題打包在 RubyGems 中，並允許使用者透過 Bundler 安裝它。

如果您不熟悉建立 Ruby gem，不用擔心。Jekyll 將協助您使用 new-theme 指令建立新的佈景主題。執行 jekyll new-theme，並將佈景主題名稱作為引數。

以下是一個範例

jekyll new-theme jekyll-theme-awesome
    create /path/to/jekyll-theme-awesome/_layouts
    create /path/to/jekyll-theme-awesome/_includes
    create /path/to/jekyll-theme-awesome/_sass
    create /path/to/jekyll-theme-awesome/_layouts/page.html
    create /path/to/jekyll-theme-awesome/_layouts/post.html
    create /path/to/jekyll-theme-awesome/_layouts/default.html
    create /path/to/jekyll-theme-awesome/Gemfile
    create /path/to/jekyll-theme-awesome/jekyll-theme-awesome.gemspec
    create /path/to/jekyll-theme-awesome/README.md
    create /path/to/jekyll-theme-awesome/LICENSE.txt
    initialize /path/to/jekyll-theme-awesome/.git
    create /path/to/jekyll-theme-awesome/.gitignore
Your new Jekyll theme, jekyll-theme-awesome, is ready for you in /path/to/jekyll-theme-awesome!
For help getting started, read /path/to/jekyll-theme-awesome/README.md.

將您的範本檔案新增至對應的資料夾中。然後根據您的需求完成 .gemspec 和 README 檔案。

版面配置和包含

佈景主題的版面配置和包含就像在任何 Jekyll 網站中運作一樣。將版面配置放置在佈景主題的 /_layouts 資料夾中，並將包含放置在佈景主題的 /_includes 資料夾中。

例如，如果您的佈景主題有一個 /_layouts/page.html 檔案，且一個頁面在其前置資料中具有 layout: page，Jekyll 會先在網站的 _layouts 資料夾中尋找 page 版面配置，如果沒有找到，則會使用佈景主題的 page 版面配置。

資源

在 /assets 中的任何檔案都會在建置時複製到使用者的網站，除非他們有相對路徑相同的檔案。您可以在此處傳送任何類型的資產：SCSS、影像、網頁字型等。這些檔案的行為就像 Jekyll 中的頁面和靜態檔案

• 如果檔案頂端有 front matter，它將會被渲染。
• 如果檔案沒有 front matter，它將會直接複製到結果網站中。

這允許佈景主題的建立者傳送預設的 /assets/styles.scss 檔案，他們的版面可以依賴它作為 /assets/styles.css。

在 /assets 中的所有檔案都將輸出到已編譯網站中的 /assets 資料夾，就像您預期在您的網站上使用 Jekyll 一樣。

樣式表

您的佈景主題的樣式表應該放在您的佈景主題的 _sass 資料夾中，再次說明，就像您在撰寫 Jekyll 網站時一樣。

_sass
└── jekyll-theme-awesome.scss

您的佈景主題的樣式可以使用 @import 指令包含在使用者的樣式表中。

@import "{{ site.theme }}";

佈景主題寶石依賴項3.5.0

即使您的佈景主題寶石的 runtime_dependencies 沒有明確包含在網站設定檔的 plugins 陣列中，Jekyll 仍會自動需要所有白名單的 runtime_dependencies。（注意：僅在使用 --safe 選項建置或提供服務時才需要白名單。）

有了這個，最終使用者不需要追蹤必須包含在他們的設定檔中的外掛程式，才能讓他們的佈景主題寶石按預期運作。

預先設定佈景主題寶石4.0

Jekyll 會讀取主題寶石根目錄中的 _config.yml，並將其資料合併到網站現有的設定檔資料中。

但是，與從主題內部載入的其他實體不同，載入設定檔會有一些限制，如下總結

• Jekyll 的預設設定無法被主題設定檔覆寫。這個球仍然在使用者的場上。
• 主題設定檔不能是符號連結，不論 安全模式 為何，以及符號連結指向的檔案是否為主題寶石中的合法檔案。
• 主題設定檔應為一組金鑰值對。一個空的設定檔、一個僅在金鑰下列出項目的設定檔，或一個僅包含簡單文字字串的設定檔，將會被靜默忽略。使用者不會收到任何警告或任何關於此差異的記錄輸出。
• 主題設定檔定義的任何設定都可以被使用者覆寫。

雖然此功能可以讓使用者更容易採用主題，但這些限制確保主題設定檔無法以令人擔憂的方式影響建置。主題所需的任何外掛程式都必須由使用者手動列出，或由主題的 gemspec 檔案提供。

此功能將讓主題寶石開箱即用主題特定設定檔變數。

記錄您的主題

您的佈景主題應該包含一個 /README.md 檔案，說明網站作者如何安裝和使用您的佈景主題。包含哪些版面配置？包含哪些內容？他們是否需要在網站的設定檔中新增任何特殊內容？

新增截圖

佈景主題是視覺化的。透過在佈景主題的儲存庫中包含一個截圖，讓使用者知道您的佈景主題長什麼樣子，截圖檔案為 /screenshot.png，可以在程式中擷取。您也可以在佈景主題的文件中包含這個截圖。

預覽您的佈景主題

在撰寫佈景主題時，若要預覽佈景主題，建議在範例中加入虛擬內容，例如 /index.html 和 /page.html 檔案。這會讓您可以使用 jekyll build 和 jekyll serve 指令預覽您的佈景主題，就像預覽 Jekyll 網站一樣。

如果您在本地預覽您的佈景主題，請務必將 /_site 新增到佈景主題的 .gitignore 檔案，以防止編譯後的網站也在您散佈佈景主題時一併包含。

發佈您的佈景主題

佈景主題透過 RubyGems.org 發佈。您需要一個 RubyGems 帳戶，您可以 免費建立。

1. 首先，您需要將它放在 git 儲存庫中

   git init # Only the first time
   git add -A
   git commit -m "Init commit"
   

2. 接著，封裝您的佈景主題，執行以下指令，將 jekyll-theme-awesome 替換成您的佈景主題名稱

   gem build jekyll-theme-awesome.gemspec
   

3. 最後，將您封裝好的佈景主題推送到 RubyGems 服務，執行以下指令，一樣將 jekyll-theme-awesome 替換成您的佈景主題名稱

   gem push jekyll-theme-awesome-*.gem
   

4. 若要發佈新版本的佈景主題，請更新 gemspec 檔案中的版本號碼（在此範例中為 jekyll-theme-awesome.gemspec），然後重複上述步驟 1 - 3。建議您在提升佈景主題版本時遵循 語意化版本管理。