Jekyll中文文档__Themes

Jekyll有一个广泛的主题系统，允许您利用社区维护的模板和样式来定制网站的展示。Jekyll主题指定插件，并以一种可以被网站内容覆盖的方式打包 assets, layouts, includes, 和 stylesheets 。

Pick up a theme

您可以在不同的库中查找和预览主题：

• GitHub.com #jekyll-theme repos
• jamstackthemes.dev
• jekyllthemes.org
• jekyllthemes.io
• jekyll-themes.com

See also: resources.

Understanding gem-based themes

当您创建一个新的Jekyll站点时（通过运行 jekyll new <PATH> 命令），Jekyll会安装一个名为 Minima 的 gem-based 主题的站点。

对于 gem-based 主题，站点的一些目录（如 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

Bundler 使用 Gemfile 和 Gemfile.lock 文件来跟踪构建 Jekyll 网站所需的 gems 和 gem 版本。

Gem-based 主题使主题开发人员更容易向任何拥有主题 Gem 的人提供更新。当有更新时，主题开发人员会将更新推送到RubyGems。

如果您有主题 gem ，您可以（如果您愿意）运行 bundle update 来更新项目中的所有 gems 。或者，您可以运行 bundle update <THEME>，将 <THEME> 替换为主题名称，例如 minima ，来仅更新主题 gem 。主题开发人员所做的任何新文件或更新（如 stylesheets 或 includes ）都将自动拉入您的项目中。

gem-based 主题的目标是让你能够获得一个健壮的、不断更新的主题的所有好处，而不会让所有主题的文件都妨碍你，也不会让你的主要关注点："创建内容"变得过于复杂。

Overriding theme defaults

Jekyll 主题设置 default data, layouts, includes, 和 stylesheets 。但是，您可以使用自己的网站内容覆盖任何主题默认值。

要替换主题中的 layouts 或 includes ，请在 _layouts 或 _includes 目录中复制要修改的特定文件，或者从头开始创建文件，使其与要覆盖的文件同名。

例如，如果所选主题具有 page 布局，则可以通过在 _layouts 目录（即 _layouts/page.html ）中创建自己的 page 布局来覆盖主题的布局。

要在计算机上查找主题的文件，请执行以下操作：

1. 运行 bundle info --path 后面跟着主题 gem 的名称，例如 bundle info --path minima ，Jekyll默认主题。

   这将返回 gem-based 主题文件的位置。例如，Minima 主题的文件在 macOS上可能位于 /usr/local/lib/ruby/gems/2.6.0/gems/minima-2.5.1 。

2. 在 Finder 或 Explorer 中打开主题的目录：

   # 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/{{ site.data.ruby.current_version }}/gems/minima-2.5.1
   #
   # then invoke explorer with above path, substituting `/` with `\`
   explorer C:\Ruby26-x64\lib\ruby\gems\{{ site.data.ruby.current_version}}\gems\minima-2.5.1
   
   # On Linux
   xdg-open $(bundle info --path minima)
   

   一个 Finder 或 Explorer 窗口将会打开，显示主题的文件和目录。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 )复制到站点 source 中的 _sass 目录中。

Jekyll将首先查看您的网站内容，然后在以下文件夹中查找任何请求文件的主题默认值：

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

请注意，复制主题文件将阻止您接收这些文件的任何主题更新。为了继续在所有样式表上获得主题更新，另一种选择是在您自己的附加的、最初命名的CSS文件中使用更高的特异性CSS选择器。

注意：
有关可以覆盖哪些文件的详细信息，请参阅所选主题的文档和 source 存储库。

Themes with _data directory 4.3.0

从4.3.0版本开始，Jekyll还考虑了主题的 _data 目录。这允许 data 跨主题分布。

一个典型的例子是在设计元素中使用的文本。

想象一下，一个主题提供了 include 文件 testimonials.html 。这个设计元素在页面上创建了一个新的 section ，并在推荐列表上放了一个h3标题。

主题开发人员可能会用英语制定标题，并将其直接放入HTML源代码中。

主题的使用者可以将已经包含进来的文件复制到他们的项目中，并替换其中的标题。

考虑到 _data 目录，这个标准任务还有另一个解决方案。

设计师没有直接将文本输入到设计模板中，而是添加了对文本目录的引用（例如site.data.i18n.testimonials.header ），并在主题的 data 目录中创建了一个文件_data/i18n/testimonials.yml 。

在这个文件中，header 被放在 header "键"下，其余的由 Jekyll 负责。

对于主题开发人员来说，乍一看，这当然比以前付出了更大的努力。

然而，对于主题的消费者来说，定制被大大简化了。

想象一下，这个主题是由一位来自德国的客户使用的。为了让她获得推荐设计元素的翻译标题，她只需要在项目目录中创建一个 data 文件，其中包含"键" site.data.i18n.testimonials.header ，将德语的翻译或她选择的标题放在上面，设计元素就已经自定义好了。

她不再需要将已经包含进来的文件复制到她的项目目录中，在那里进行自定义，最重要的是，放弃主题的所有更新，因为主题开发人员为她提供了通过文本文件集中更改文本模块的可能性。

注意：
Data 文件提供了高度的灵活性。主题开发人员放置文本模块的位置可能与主题消费者的位置不同，这可能会导致无法预见的麻烦！

与上面的例子相关，消费者网站上主题的 _data/i18n/testimonials.yml 文件中的覆盖"键" site.data.i18n.testimonials.header 可以位于三个不同的位置：

• _data/i18n.yml with key testimonials.header
• _data/i18n/testimonials.yml with key header (这反映了给定示例的layout)
• _data/i18n/testimonials/header.yml without any key, the headline can go straight into the file

主题开发人员在支持那些在为主题提供的设计元素设置文本模块这一过程中感到迷失的消费者时，应该考虑到这种模糊性。

注意：
当使用 data 功能时，问问自己，是引入一些东西来改变主题的行为的那个"键"，无论主题是否存在，还是只是显示的 data 。如果它正在改变主题的行为，它应该进入 site.config ，否则可以通过 site.data提供。

修改主题行为的绑定数据被认为是一种反模式，强烈反对使用这种模式。这完全取决于主题的作者，以确保所提供的每一个 data 都可以很容易地被主题的消费者覆盖，如果他们愿意的话。

Converting gem-based themes to regular themes

假设您想去掉 gem-based 主题，并将其转换为常规主题，其中所有文件都存在于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 ：

• Open Gemfile and remove gem "minima", "~> 2.5".
• Open _config.yml and remove theme: minima.

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

Installing a gem-based theme

jekyll new <PATH> 命令并不是创建一个基于 gem-based 主题的新jekyll站点的唯一方法。你也可以在网上找到 gem-based 主题，并将它们融入你的Jekyll项目中。

例如，搜索 jekyll theme on RubyGems 可以找到其他 gem-based 主题。（请注意，并非所有主题都使用 jekyll-theme 作为主题名称中的约定。）

要安装 gem-based 主题：

1. 将主题 gem 添加到您的网站的 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" 替换为您想要的 gem ，例如：

   # ./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 只支持一些 some gem-based themes 。GitHub Pages 还支持通过使用 remote_theme 配置来 using any theme hosted on GitHub ，就好像它是一个 gem-based 主题一样。

Creating a gem-based theme

如果你是Jekyll主题开发人员（而不是主题消费者），你可以将你的主题打包到 RubyGems 中，并允许用户通过 Bundler 进行安装。

如果您不熟悉创建 Ruby gems ，请不要担心。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 文件。

Layouts and includes

主题的 layouts 和 includes 的工作方式，就像它们在任何 Jekyll 网站上的工作方式一样。将 layouts 放置在主题的 /_layouts 文件夹中，并将 includes 放置在主题 /_includes 文件夹中。

例如，如果您的主题有一个 /_layouts/page.html 文件，并且页面的 front matter 中有 layout: page ，那么 Jekyll 将首先查找网站的 _layouts 文件夹中的 page layout ，如果不存在，则使用主题的 page layout 。

Assets

/assets 中的任何文件都将在生成时复制到用户的站点，除非它们有一个具有相同相对路径的文件。您可以在这里运送任何类型的asset：SCSS、图像、网络字体等。这些文件的行为类似于Jekyll中的页面和静态文件：

• 如果文件的顶部有 front matter ，则会对其进行渲染。
• 如果文件没有 front matter ，它将被简单地复制到生成的站点中。

这允许主题创建者发送默认的 /assets/styles.scss 文件，他们的 layouts 可以依赖该文件作为 /assets/styles.css 。

/assets 中的所有文件都将输出到 /assets 文件夹中已编译的站点中，正如您在站点上使用 Jekyll 所期望的那样。

Stylesheets

您的主题的样式表应该放在主题的 _sass 文件夹中，就像您在创作 Jekyll 网站时一样。

_sass
└── jekyll-theme-awesome.scss

可以使用 @import 指令将主题的样式包含在用户的样式表中。

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

Theme-gem dependencies (3.5.0)

Jekyll将自动要求你的 theme-gem 的所有白名单 runtime_dependencies ，即使它们没有明确包含在网站配置文件中的 plugins 数组中。（注意：只有在 building 或 serving 后面跟 --safe 选项时才需要白名单。）

这样，最终用户就不需要跟踪需要包含在配置文件中的插件，以便 theme-gem 按预期工作。

Pre-configuring Theme-gems (4.0)

Jekyll将读取 theme-gem 根目录下的 _config.yml ，并将其数据合并到站点现有的配置数据中。

但与从主题中加载的其他实体不同，加载配置文件有一些限制，总结如下：

• Jekyll的默认设置不能被主题配置覆盖。那个"球还在使用者的球场上"。
• 主题配置文件不能是符号链接，无论 safe mode 以及符号链接指向的文件是否是 theme-gem 中的合法文件。
• 主题配置应该是一组键值对。一个空的配置文件、一个只列出"键"下面项目的配置文件，或者一个只有一个简单文本字符串的配置文件都将被忽略。用户将不会收到关于此差异的警告或任何日志输出。
• 用户可以覆盖由主题配置定义的任何设置。

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

此特性将使 theme-gem 能够开箱即用地处理"特定于主题的配置变量"。

Documenting your theme

您的主题应该引入一个 /README.md 文件，该文件解释了网站作者如何安装和使用您的主题。引入哪些布局？有哪些 includes ？他们是否需要在站点的配置文件中添加一些特殊内容？

Adding a screenshot

主题是可视化的。通过在主题的存储库中以 /screenshot.png 的形式包含屏幕截图，来向用户显示您的主题是什么样子的，在存储库中该图片可以通过编程的方式检索。您也可以将此屏幕截图包含在主题文档中。

Previewing your theme

要在创作主题时预览主题，在例如 /index.html 和 /page.html 文件中添加伪内容可能会有所帮助。这将允许您使用 jekyll build 和 jekyll serve 命令预览主题，就像预览 jekyll 网站一样。

注意：
如果您确实在本地预览了主题，请确保将 /_site 添加到主题的 .gitignore 文件中，以防止在分发主题时已编译的网站也被包含进来。

Publishing your theme

主题通过 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。我们建议您在调整主题版本时遵循 Semantic Versioning 。

📃返回目录