改进此页面

主题

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 的主题文件的位置。例如，在 macOS 上，Minima 主题的文件可能位于 /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 提供即可。

捆绑修改主题行为的数据被认为是一种反模式，强烈不建议使用。确保主题的使用者可以轻松覆盖提供的每项数据（如果他们希望的话）完全取决于主题的作者。

将基于 gem 的主题转换为常规主题

假设你想摆脱基于 gem 的主题并将其转换为常规主题，其中所有文件都存在于你的 Jekyll 网站目录中，而主题 gem 中没有任何存储。

为此，将文件从主题 gem 的目录复制到你的 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 和配置中对主题 gem 的引用。例如，要删除 minima

• 打开 Gemfile 并删除 gem "minima", "~> 2.5"。
• 打开 _config.yml 并删除 theme: minima。

现在 bundle update 将不再获取主题 gem 的更新。

安装基于 gem 的主题

jekyll new <PATH> 命令并不是创建带有基于 gem 的主题的新 Jekyll 站点的唯一方法。您还可以在线查找基于 gem 的主题，并将它们合并到您的 Jekyll 项目中。

例如，在 RubyGems 上搜索 jekyll 主题 以查找其他基于 gem 的主题。（请注意，并非所有主题都使用 jekyll-theme 作为主题名称中的惯例。）

要安装基于 gem 的主题

1. 将主题 gem 添加到您网站的 Gemfile 中

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

   或者，如果您已使用 jekyll new 命令开始，请用您想要的 gem 替换 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 文件，并且一个页面的 front matter 中有 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 的默认设置无法被主题配置覆盖。用户仍然有权决定。
• 无论 安全模式 如何，主题配置文件都不能是符号链接，并且符号链接指向的文件不能是主题 gem 中的合法文件。
• 主题配置应为一组键值对。空配置文件、仅在键下列出项目的配置文件或仅包含简单文本字符串的配置文件将被直接忽略。用户不会收到任何警告或日志输出，说明此差异。
• 用户可以覆盖主题配置定义的任何设置。

虽然此功能是为了更容易采用主题，但这些限制确保主题配置不会以令人担忧的方式影响构建。主题所需的任何插件都必须由用户手动列出或由主题的 gemspec 文件提供。

此功能将使主题 gem 能够开箱即用地处理主题特定配置变量。

记录你的主题

你的主题应包含一个 /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。我们建议您在提升主题版本时遵循 语义版本控制。