jekyll-docs 3.3.1 → 3.4.0
Sign up to get free protection for your applications and to get access to all the features.
- checksums.yaml +4 -4
- data/site/404.html +3 -3
- data/site/community/index.html +5 -5
- data/site/css/screen.css +7 -6
- data/site/docs/assets/index.html +13 -5
- data/site/docs/collections/index.html +132 -29
- data/site/docs/conduct/index.html +16 -5
- data/site/docs/configuration/index.html +26 -8
- data/site/docs/continuous-integration/circleci/index.html +761 -0
- data/site/docs/continuous-integration/index.html +25 -245
- data/site/docs/continuous-integration/travis-ci/index.html +916 -0
- data/site/docs/contributing/index.html +41 -5
- data/site/docs/datafiles/index.html +14 -6
- data/site/docs/deployment-methods/index.html +17 -7
- data/site/docs/drafts/index.html +13 -5
- data/site/docs/extras/index.html +17 -6
- data/site/docs/frontmatter/index.html +13 -5
- data/site/docs/github-pages/index.html +68 -47
- data/site/docs/history/index.html +132 -9
- data/site/docs/home/index.html +13 -5
- data/site/docs/includes/index.html +824 -0
- data/site/docs/installation/index.html +16 -6
- data/site/docs/maintaining/affinity-team-captain/index.html +16 -5
- data/site/docs/maintaining/avoiding-burnout/index.html +16 -5
- data/site/docs/maintaining/becoming-a-maintainer/index.html +17 -6
- data/site/docs/maintaining/index.html +16 -5
- data/site/docs/maintaining/merging-a-pull-request/index.html +21 -6
- data/site/docs/maintaining/reviewing-a-pull-request/index.html +16 -5
- data/site/docs/maintaining/special-labels/index.html +16 -5
- data/site/docs/maintaining/triaging-an-issue/index.html +16 -5
- data/site/docs/migrations/index.html +13 -5
- data/site/docs/pages/index.html +33 -50
- data/site/docs/pagination/index.html +16 -5
- data/site/docs/permalinks/index.html +148 -66
- data/site/docs/plugins/index.html +39 -14
- data/site/docs/posts/index.html +32 -5
- data/site/docs/quickstart/index.html +57 -18
- data/site/docs/resources/index.html +21 -10
- data/site/docs/sites/index.html +18 -7
- data/site/docs/static-files/index.html +15 -7
- data/site/docs/structure/index.html +47 -32
- data/site/docs/templates/index.html +85 -89
- data/site/docs/themes/index.html +214 -63
- data/site/docs/troubleshooting/index.html +16 -5
- data/site/docs/upgrading/0-to-2/index.html +16 -5
- data/site/docs/upgrading/2-to-3/index.html +17 -6
- data/site/docs/upgrading/index.html +16 -5
- data/site/docs/usage/index.html +21 -6
- data/site/docs/variables/index.html +14 -6
- data/site/docs/windows/index.html +35 -10
- data/site/feed.xml +41 -22
- data/site/fonts/FontAwesome.eot +0 -0
- data/site/fonts/FontAwesome.svg +12 -0
- data/site/fonts/FontAwesome.ttf +0 -0
- data/site/fonts/FontAwesome.woff +0 -0
- data/site/help/index.html +3 -3
- data/site/icomoon-selection.json +96 -0
- data/site/index.html +3 -3
- data/site/latest_version.txt +1 -1
- data/site/news/2013/05/05/jekyll-1-0-0-released/index.html +12 -8
- data/site/news/2013/05/08/jekyll-1-0-1-released/index.html +11 -7
- data/site/news/2013/05/12/jekyll-1-0-2-released/index.html +11 -7
- data/site/news/2013/06/07/jekyll-1-0-3-released/index.html +11 -7
- data/site/news/2013/07/14/jekyll-1-1-0-released/index.html +11 -7
- data/site/news/2013/07/24/jekyll-1-1-1-released/index.html +12 -8
- data/site/news/2013/07/25/jekyll-1-0-4-released/index.html +11 -7
- data/site/news/2013/07/25/jekyll-1-1-2-released/index.html +11 -7
- data/site/news/2013/09/06/jekyll-1-2-0-released/index.html +11 -7
- data/site/news/2013/09/14/jekyll-1-2-1-released/index.html +11 -7
- data/site/news/2013/10/28/jekyll-1-3-0-rc1-released/index.html +11 -7
- data/site/news/2013/11/04/jekyll-1-3-0-released/index.html +11 -7
- data/site/news/2013/11/26/jekyll-1-3-1-released/index.html +11 -7
- data/site/news/2013/12/07/jekyll-1-4-0-released/index.html +11 -7
- data/site/news/2013/12/09/jekyll-1-4-1-released/index.html +11 -7
- data/site/news/2013/12/16/jekyll-1-4-2-released/index.html +11 -7
- data/site/news/2014/01/13/jekyll-1-4-3-released/index.html +11 -7
- data/site/news/2014/03/24/jekyll-1-5-0-released/index.html +11 -7
- data/site/news/2014/03/27/jekyll-1-5-1-released/index.html +11 -7
- data/site/news/2014/05/06/jekyll-turns-2-0-0/index.html +11 -7
- data/site/news/2014/05/08/jekyll-2-0-3-released/index.html +11 -7
- data/site/news/2014/06/04/jekyll-stickers-1-dollar-stickermule/index.html +12 -8
- data/site/news/2014/06/28/jekyll-turns-21-i-mean-2-1-0/index.html +12 -8
- data/site/news/2014/07/01/jekyll-2-1-1-released/index.html +11 -7
- data/site/news/2014/07/29/jekyll-2-2-0-released/index.html +11 -7
- data/site/news/2014/08/10/jekyll-2-3-0-released/index.html +11 -7
- data/site/news/2014/09/09/jekyll-2-4-0-released/index.html +11 -7
- data/site/news/2014/11/05/jekylls-midlife-crisis-jekyll-turns-2-5-0/index.html +11 -7
- data/site/news/2014/11/09/jekyll-2-5-1-released/index.html +11 -7
- data/site/news/2014/11/12/jekyll-2-5-2-released/index.html +11 -7
- data/site/news/2014/12/17/alfredxing-welcome-to-jekyll-core/index.html +12 -8
- data/site/news/2014/12/22/jekyll-2-5-3-released/index.html +11 -7
- data/site/news/2015/01/20/jekyll-meet-and-greet/index.html +11 -7
- data/site/news/2015/01/24/jekyll-3-0-0-beta1-released/index.html +11 -7
- data/site/news/2015/02/26/introducing-jekyll-talk/index.html +11 -7
- data/site/news/2015/10/26/jekyll-3-0-released/index.html +11 -7
- data/site/news/2015/11/17/jekyll-3-0-1-released/index.html +11 -7
- data/site/news/2016/01/20/jekyll-3-0-2-released/index.html +11 -7
- data/site/news/2016/01/24/jekyll-3-1-0-released/index.html +11 -7
- data/site/news/2016/01/28/jekyll-3-1-1-released/index.html +11 -7
- data/site/news/2016/02/08/jekyll-3-0-3-released/index.html +11 -7
- data/site/news/2016/02/19/jekyll-3-1-2-released/index.html +11 -7
- data/site/news/2016/03/10/making-it-easier-to-contribute-to-jekyll/index.html +11 -7
- data/site/news/2016/04/19/jekyll-3-0-4-released/index.html +11 -7
- data/site/news/2016/04/19/jekyll-3-1-3-released/index.html +11 -8
- data/site/news/2016/04/26/jekyll-3-0-5-released/index.html +11 -7
- data/site/news/2016/05/18/jekyll-3-1-4-released/index.html +11 -7
- data/site/news/2016/05/18/jekyll-3-1-5-released/index.html +11 -7
- data/site/news/2016/05/19/jekyll-3-1-6-released/index.html +11 -7
- data/site/news/2016/06/03/update-on-jekyll-s-google-summer-of-code-projects/index.html +11 -7
- data/site/news/2016/07/26/jekyll-3-2-0-released/index.html +11 -7
- data/site/news/2016/08/02/jekyll-3-2-1-released/index.html +11 -7
- data/site/news/2016/08/24/jekyll-admin-initial-release/index.html +12 -8
- data/site/news/2016/10/06/jekyll-3-3-is-here/index.html +12 -8
- data/site/news/2016/11/14/jekyll-3-3-1-released/index.html +11 -7
- data/site/news/2017/01/18/jekyll-3-4-0-released/index.html +570 -0
- data/site/news/index.html +81 -15
- data/site/news/releases/index.html +78 -12
- data/site/readme.md +9 -2
- data/site/sitemap.xml +59 -43
- metadata +14 -10
- data/site/fonts/fontawesome-webfont.eot +0 -0
- data/site/fonts/fontawesome-webfont.svg +0 -640
- data/site/fonts/fontawesome-webfont.ttf +0 -0
- data/site/fonts/fontawesome-webfont.woff +0 -0
- data/site/fonts/fontawesome-webfont.woff2 +0 -0
data/site/docs/themes/index.html
CHANGED
@@ -4,7 +4,7 @@
|
|
4
4
|
<meta http-equiv="Content-Type" content="text/html; charset=UTF-8">
|
5
5
|
<meta charset="UTF-8">
|
6
6
|
<meta name="viewport" content="width=device-width,initial-scale=1">
|
7
|
-
<meta name="generator" content="Jekyll v3.
|
7
|
+
<meta name="generator" content="Jekyll v3.4.0">
|
8
8
|
<link type="application/atom+xml" rel="alternate" href="https://jekyllrb.com/feed.xml" title="Jekyll • Simple, blog-aware, static sites">
|
9
9
|
<link rel="alternate" type="application/atom+xml" title="Recent commits to Jekyll’s master branch" href="https://github.com/jekyll/jekyll/commits/master.atom">
|
10
10
|
<link rel="stylesheet" href="//fonts.googleapis.com/css?family=Lato:300,300italic,400,400italic,700,700italic,900">
|
@@ -13,13 +13,13 @@
|
|
13
13
|
<!-- Begin Jekyll SEO tag v2.1.0 -->
|
14
14
|
<title>Themes - Jekyll • Simple, blog-aware, static sites</title>
|
15
15
|
<meta property="og:title" content="Themes">
|
16
|
-
<meta name="description" content="Jekyll has an extensive theme system
|
17
|
-
<meta property="og:description" content="Jekyll has an extensive theme system
|
16
|
+
<meta name="description" content="Jekyll has an extensive theme system that allows you to leverage community-maintained templates and styles to customize your site’s presentation. Jekyll themes package up layouts, includes, and stylesheets in a way that can be overridden by your site’s content.">
|
17
|
+
<meta property="og:description" content="Jekyll has an extensive theme system that allows you to leverage community-maintained templates and styles to customize your site’s presentation. Jekyll themes package up layouts, includes, and stylesheets in a way that can be overridden by your site’s content.">
|
18
18
|
<link rel="canonical" href="https://jekyllrb.com/docs/themes/">
|
19
19
|
<meta property="og:url" content="https://jekyllrb.com/docs/themes/">
|
20
20
|
<meta property="og:site_name" content="Jekyll • Simple, blog-aware, static sites">
|
21
21
|
<meta property="og:type" content="article">
|
22
|
-
<meta property="article:published_time" content="2017-
|
22
|
+
<meta property="article:published_time" content="2017-03-22T08:06:48-07:00">
|
23
23
|
<meta name="twitter:card" content="summary">
|
24
24
|
<meta name="twitter:site" content="@jekyllrb">
|
25
25
|
<meta name="google-site-verification" content="onQcXpAvtHBrUI5LlroHNE_FP0b2qvFyPq7VZw36iEY">
|
@@ -27,8 +27,8 @@
|
|
27
27
|
{"@context": "http://schema.org",
|
28
28
|
"@type": "BlogPosting",
|
29
29
|
"headline": "Themes",
|
30
|
-
"datePublished": "2017-
|
31
|
-
"description": "Jekyll has an extensive theme system
|
30
|
+
"datePublished": "2017-03-22T08:06:48-07:00",
|
31
|
+
"description": "Jekyll has an extensive theme system that allows you to leverage community-maintained templates and styles to customize your site’s presentation. Jekyll themes package up layouts, includes, and stylesheets in a way that can be overridden by your site’s content.",
|
32
32
|
"publisher": {"@type": "Organization",
|
33
33
|
"logo": {"@type": "ImageObject",
|
34
34
|
"url": "https://jekyllrb.com/img/logo-2x.png"}},
|
@@ -192,6 +192,10 @@
|
|
192
192
|
|
193
193
|
|
194
194
|
|
195
|
+
<option value="/docs/includes/">Includes</option>
|
196
|
+
|
197
|
+
|
198
|
+
|
195
199
|
<option value="/docs/permalinks/">Permalinks</option>
|
196
200
|
|
197
201
|
|
@@ -286,93 +290,234 @@
|
|
286
290
|
<a href="https://github.com/jekyll/jekyll/edit/master/docs/_docs/themes.md"><i class="fa fa-pencil"></i> Improve this page</a>
|
287
291
|
</div>
|
288
292
|
<h1>Themes</h1>
|
289
|
-
<p>Jekyll has an extensive theme system
|
293
|
+
<p>Jekyll has an extensive theme system that allows you to leverage community-maintained templates and styles to customize your site’s presentation. Jekyll themes package up layouts, includes, and stylesheets in a way that can be overridden by your site’s content.</p>
|
294
|
+
|
295
|
+
<h2 id="understanding-gem-based-themes">Understanding gem-based themes</h2>
|
296
|
+
|
297
|
+
<p>When you <a href="/docs/quickstart">create a new Jekyll site</a> (by running the <code class="highlighter-rouge">jekyll new <PATH></code> command), Jekyll installs a site that uses a gem-based theme called <a href="https://github.com/jekyll/minima">Minima</a>.</p>
|
298
|
+
|
299
|
+
<p>With gem-based themes, some of the site’s directories (such as the <code class="highlighter-rouge">assets</code>, <code class="highlighter-rouge">_layouts</code>, <code class="highlighter-rouge">_includes</code>, and <code class="highlighter-rouge">_sass</code> directories) are stored in the theme’s gem, hidden from your immediate view. Yet all of the necessary directories will be read and processed during Jekyll’s build process.</p>
|
300
|
+
|
301
|
+
<p>In the case of Minima, you see only the following files in your Jekyll site directory:</p>
|
302
|
+
|
303
|
+
<div class="highlighter-rouge">
|
304
|
+
<pre class="highlight"><code>├── Gemfile
|
305
|
+
├── Gemfile.lock
|
306
|
+
├── _config.yml
|
307
|
+
├── _posts
|
308
|
+
│ └── 2016-12-04-welcome-to-jekyll.markdown
|
309
|
+
├── about.md
|
310
|
+
└── index.md
|
311
|
+
</code></pre>
|
312
|
+
</div>
|
313
|
+
|
314
|
+
<p>The <code class="highlighter-rouge">Gemfile</code> and <code class="highlighter-rouge">Gemfile.lock</code> files are used by Bundler to keep track of the required gems and gem versions you need to build your Jekyll site.</p>
|
315
|
+
|
316
|
+
<p>Gem-based themes make it easy for theme developers to make updates available to anyone who has the theme gem. When there’s an update, theme developers push the update to RubyGems.</p>
|
317
|
+
|
318
|
+
<p>If you have the theme gem, you can (if you desire) run <code class="highlighter-rouge">bundle update</code> to update all gems in your project. Or you can run <code class="highlighter-rouge">bundle update <THEME></code>, replacing <code class="highlighter-rouge"><THEME></code> with the theme name, such as <code class="highlighter-rouge">minima</code>, to just update the theme gem. Any new files or updates the theme developer has made (such as to stylesheets or includes) will be pulled into your project automatically.</p>
|
319
|
+
|
320
|
+
<p>The goal of gem-based themes is to allow you to get all the benefits of a robust, continually updated theme without having all the theme’s files getting in your way and over-complicating what might be your primary focus: creating content.</p>
|
321
|
+
|
322
|
+
<h2 id="overriding-theme-defaults">Overriding theme defaults</h2>
|
323
|
+
|
324
|
+
<p>Jekyll themes set default layouts, includes, and stylesheets. However, you can override any of the theme defaults with your own site content.</p>
|
325
|
+
|
326
|
+
<p>For example, if your selected theme has a <code class="highlighter-rouge">page</code> layout, you can override the theme’s layout by creating your own <code class="highlighter-rouge">page</code> layout in the <code class="highlighter-rouge">_layouts</code> directory (that is, <code class="highlighter-rouge">_layouts/page.html</code>).</p>
|
327
|
+
|
328
|
+
<p>Jekyll will look first to your site’s content before looking to the theme’s defaults for any requested file in the following folders:</p>
|
329
|
+
|
330
|
+
<ul>
|
331
|
+
<li><code class="highlighter-rouge">/assets</code></li>
|
332
|
+
<li><code class="highlighter-rouge">/_layouts</code></li>
|
333
|
+
<li><code class="highlighter-rouge">/_includes</code></li>
|
334
|
+
<li><code class="highlighter-rouge">/_sass</code></li>
|
335
|
+
</ul>
|
290
336
|
|
291
|
-
<
|
337
|
+
<p class="note info">Refer to your selected theme’s documentation and source repository for more information on what files you can override.</p>
|
338
|
+
|
339
|
+
<p>To locate theme’s files on your computer:</p>
|
292
340
|
|
293
341
|
<ol>
|
294
342
|
<li>
|
295
|
-
<p>
|
343
|
+
<p>Run <code class="highlighter-rouge">bundle show</code> followed by the name of the theme’s gem, e.g., <code class="highlighter-rouge">bundle show minima</code> for default Jekyll’s theme.</p>
|
296
344
|
|
297
|
-
<
|
298
|
-
<pre class="highlight"><code> gem 'my-awesome-jekyll-theme'
|
299
|
-
</code></pre>
|
300
|
-
</div>
|
345
|
+
<p>This returns the location of the gem-based theme files. For example, Minima theme’s files are located in <code class="highlighter-rouge">/usr/local/lib/ruby/gems/2.3.0/gems/minima-2.1.0</code> on macOS.</p>
|
301
346
|
</li>
|
302
|
-
<li>Save the changes to your <code class="highlighter-rouge">Gemfile</code>
|
303
|
-
</li>
|
304
|
-
<li>Run the command <code class="highlighter-rouge">bundle install</code> to install the theme</li>
|
305
347
|
<li>
|
306
|
-
<p>
|
348
|
+
<p>Open the theme’s directory in Finder or Explorer:</p>
|
349
|
+
|
350
|
+
<div class="language-shell highlighter-rouge">
|
351
|
+
<pre class="highlight"><code><span class="c"># On MacOS</span>
|
352
|
+
open <span class="k">$(</span>bundle show minima<span class="k">)</span>
|
353
|
+
<span class="c"># On Windows</span>
|
354
|
+
explorer /usr/local/lib/ruby/gems/2.3.0/gems/minima-2.1.0
|
355
|
+
</code></pre>
|
356
|
+
</div>
|
357
|
+
|
358
|
+
<p>A Finder or Explorer window opens showing the theme’s files and directories. The Minima theme gem contains these files:</p>
|
307
359
|
|
308
360
|
<div class="highlighter-rouge">
|
309
|
-
<pre class="highlight"><code>
|
361
|
+
<pre class="highlight"><code> ├── LICENSE.txt
|
362
|
+
├── README.md
|
363
|
+
├── _includes
|
364
|
+
│ ├── disqus_comments.html
|
365
|
+
│ ├── footer.html
|
366
|
+
│ ├── google-analytics.html
|
367
|
+
│ ├── head.html
|
368
|
+
│ ├── header.html
|
369
|
+
│ ├── icon-github.html
|
370
|
+
│ ├── icon-github.svg
|
371
|
+
│ ├── icon-twitter.html
|
372
|
+
│ └── icon-twitter.svg
|
373
|
+
├── _layouts
|
374
|
+
│ ├── default.html
|
375
|
+
│ ├── home.html
|
376
|
+
│ ├── page.html
|
377
|
+
│ └── post.html
|
378
|
+
├── _sass
|
379
|
+
│ ├── minima
|
380
|
+
│ │ ├── _base.scss
|
381
|
+
│ │ ├── _layout.scss
|
382
|
+
│ │ └── _syntax-highlighting.scss
|
383
|
+
│ └── minima.scss
|
384
|
+
└── assets
|
385
|
+
└── main.scss
|
310
386
|
</code></pre>
|
311
387
|
</div>
|
388
|
+
|
389
|
+
<p>With a clear understanding of the theme’s files, you can now override any theme file by creating a similarly named file in your Jekyll site directory.</p>
|
390
|
+
|
391
|
+
<p>Let’s say you want to override Minima’s footer. In your Jekyll site, create an <code class="highlighter-rouge">_includes</code> folder and add a file in it called <code class="highlighter-rouge">footer.html</code>. Jekyll will now use your site’s <code class="highlighter-rouge">footer.html</code> file instead of the <code class="highlighter-rouge">footer.html</code> file from the Minima theme gem.</p>
|
312
392
|
</li>
|
313
393
|
</ol>
|
314
394
|
|
315
|
-
<
|
395
|
+
<h2 id="converting-gem-based-themes-to-regular-themes">Converting gem-based themes to regular themes</h2>
|
316
396
|
|
317
|
-
<
|
397
|
+
<p>Suppose you want to get rid of the gem-based theme and convert it to a regular theme, where all files are present in your Jekyll site directory, with nothing stored in the theme gem.</p>
|
318
398
|
|
319
|
-
<p>
|
399
|
+
<p>To do this, copy the files from the theme gem’s directory into your Jekyll site directory. (For example, copy them to <code class="highlighter-rouge">/myblog</code> if you created your Jekyll site at <code class="highlighter-rouge">/myblog</code>. See the previous section for details.)</p>
|
320
400
|
|
321
|
-
<p>
|
401
|
+
<p>Then remove references to the theme gem in <code class="highlighter-rouge">Gemfile</code> and configuration. For example, to remove <code class="highlighter-rouge">minima</code>:</p>
|
322
402
|
|
323
403
|
<ul>
|
324
|
-
<li
|
325
|
-
<li
|
326
|
-
<li><code class="highlighter-rouge">/_includes</code></li>
|
327
|
-
<li><code class="highlighter-rouge">/_sass</code></li>
|
404
|
+
<li>Open <code class="highlighter-rouge">Gemfile</code> and remove <code class="highlighter-rouge">gem "minima", "~> 2.0"</code>.</li>
|
405
|
+
<li>Open <code class="highlighter-rouge">_config.yml</code> and remove <code class="highlighter-rouge">theme: minima</code>.</li>
|
328
406
|
</ul>
|
329
407
|
|
330
|
-
<p class="
|
408
|
+
<p>Now <code class="highlighter-rouge">bundle update</code> will no longer get updates for the theme gem.</p>
|
409
|
+
|
410
|
+
<h2 id="installing-a-theme">Installing a gem-based theme</h2>
|
411
|
+
|
412
|
+
<p>The <code class="highlighter-rouge">jekyll new <PATH></code> command isn’t the only way to create a new Jekyll site with a gem-based theme. You can also find gem-based themes online and incorporate them into your Jekyll project.</p>
|
413
|
+
|
414
|
+
<p>For example, search for <a href="https://rubygems.org/search?utf8=%E2%9C%93&query=jekyll-theme">jekyll theme on RubyGems</a> to find other gem-based themes. (Note that not all themes are using <code class="highlighter-rouge">jekyll-theme</code> as a convention in the theme name.)</p>
|
331
415
|
|
332
|
-
<p>To
|
333
|
-
the name of the theme’s gem, e.g. <code class="highlighter-rouge">bundle show minima</code> for default Jekyll’s
|
334
|
-
theme. Then copy the files you want to override, from the returned path to your root folder.</p>
|
416
|
+
<p>To install a gem-based theme:</p>
|
335
417
|
|
336
|
-
<
|
418
|
+
<ol>
|
419
|
+
<li>
|
420
|
+
<p>Add the theme to your site’s <code class="highlighter-rouge">Gemfile</code>:</p>
|
421
|
+
|
422
|
+
<div class="language-sh highlighter-rouge">
|
423
|
+
<pre class="highlight"><code>gem <span class="s2">"jekyll-theme-awesome"</span>
|
424
|
+
</code></pre>
|
425
|
+
</div>
|
426
|
+
</li>
|
427
|
+
<li>
|
428
|
+
<p>Install the theme:</p>
|
429
|
+
|
430
|
+
<div class="language-sh highlighter-rouge">
|
431
|
+
<pre class="highlight"><code>bundle install
|
432
|
+
</code></pre>
|
433
|
+
</div>
|
434
|
+
</li>
|
435
|
+
<li>
|
436
|
+
<p>Add the following to your site’s <code class="highlighter-rouge">_config.yml</code> to activate the theme:</p>
|
437
|
+
|
438
|
+
<div class="language-sh highlighter-rouge">
|
439
|
+
<pre class="highlight"><code>theme: jekyll-theme-awesome
|
440
|
+
</code></pre>
|
441
|
+
</div>
|
442
|
+
</li>
|
443
|
+
<li>
|
444
|
+
<p>Build your site:</p>
|
445
|
+
|
446
|
+
<div class="language-sh highlighter-rouge">
|
447
|
+
<pre class="highlight"><code>bundle <span class="nb">exec </span>jekyll serve
|
448
|
+
</code></pre>
|
449
|
+
</div>
|
450
|
+
</li>
|
451
|
+
</ol>
|
452
|
+
|
453
|
+
<p>You can have multiple themes listed in your site’s <code class="highlighter-rouge">Gemfile</code>, but only one theme can be selected in your site’s <code class="highlighter-rouge">_config.yml</code>. {: .note .info }</p>
|
337
454
|
|
338
|
-
<p>
|
455
|
+
<p>If you’re publishing your Jekyll site on <a href="https://pages.github.com/">GitHub Pages</a>, note that GitHub Pages supports only some gem-based themes. See <a href="https://pages.github.com/themes/">Supported Themes</a> in GitHub’s documentation to see which themes are supported.</p>
|
456
|
+
|
457
|
+
<h2 id="creating-a-gem-based-theme">Creating a gem-based theme</h2>
|
458
|
+
|
459
|
+
<p>If you’re a Jekyll theme developer (rather than just a consumer of themes), you can package up your theme in RubyGems and allow users to install it through Bundler.</p>
|
460
|
+
|
461
|
+
<p>If you’re unfamiliar with creating Ruby gems, don’t worry. Jekyll will help you scaffold a new theme with the <code class="highlighter-rouge">new-theme</code> command. Run <code class="highlighter-rouge">jekyll new-theme</code> with the theme name as an argument.</p>
|
462
|
+
|
463
|
+
<p>Here is an example:</p>
|
339
464
|
|
340
465
|
<div class="language-sh highlighter-rouge">
|
341
|
-
<pre class="highlight"><code>jekyll new-theme
|
342
|
-
|
343
|
-
|
344
|
-
|
345
|
-
|
346
|
-
|
347
|
-
|
348
|
-
|
349
|
-
|
350
|
-
|
351
|
-
|
352
|
-
|
353
|
-
|
354
|
-
Your new Jekyll theme,
|
355
|
-
For <span class="nb">help </span>getting started, <span class="nb">read</span> /path/to/
|
466
|
+
<pre class="highlight"><code>jekyll new-theme jekyll-theme-awesome
|
467
|
+
create /path/to/jekyll-theme-awesome/_layouts
|
468
|
+
create /path/to/jekyll-theme-awesome/_includes
|
469
|
+
create /path/to/jekyll-theme-awesome/_sass
|
470
|
+
create /path/to/jekyll-theme-awesome/_layouts/page.html
|
471
|
+
create /path/to/jekyll-theme-awesome/_layouts/post.html
|
472
|
+
create /path/to/jekyll-theme-awesome/_layouts/default.html
|
473
|
+
create /path/to/jekyll-theme-awesome/Gemfile
|
474
|
+
create /path/to/jekyll-theme-awesome/jekyll-theme-awesome.gemspec
|
475
|
+
create /path/to/jekyll-theme-awesome/README.md
|
476
|
+
create /path/to/jekyll-theme-awesome/LICENSE.txt
|
477
|
+
initialize /path/to/jekyll-theme-awesome/.git
|
478
|
+
create /path/to/jekyll-theme-awesome/.gitignore
|
479
|
+
Your new Jekyll theme, jekyll-theme-awesome, is ready <span class="k">for </span>you <span class="k">in</span> /path/to/jekyll-theme-awesome!
|
480
|
+
For <span class="nb">help </span>getting started, <span class="nb">read</span> /path/to/jekyll-theme-awesome/README.md.
|
356
481
|
</code></pre>
|
357
482
|
</div>
|
358
483
|
|
359
|
-
<p>Add your template files in the corresponding folders
|
484
|
+
<p>Add your template files in the corresponding folders. Then complete the <code class="highlighter-rouge">.gemspec</code> and the README files according to your needs.</p>
|
360
485
|
|
361
486
|
<h3 id="layouts-and-includes">Layouts and includes</h3>
|
362
487
|
|
363
488
|
<p>Theme layouts and includes work just like they work in any Jekyll site. Place layouts in your theme’s <code class="highlighter-rouge">/_layouts</code> folder, and place includes in your themes <code class="highlighter-rouge">/_includes</code> folder.</p>
|
364
489
|
|
365
|
-
<p>For example, if your theme has a <code class="highlighter-rouge">/_layouts/page.html</code> file, and a page has <code class="highlighter-rouge">layout: page</code> in its YAML front matter, Jekyll will first look to the site’s <code class="highlighter-rouge">_layouts</code> folder for
|
490
|
+
<p>For example, if your theme has a <code class="highlighter-rouge">/_layouts/page.html</code> file, and a page has <code class="highlighter-rouge">layout: page</code> in its YAML front matter, Jekyll will first look to the site’s <code class="highlighter-rouge">_layouts</code> folder for the <code class="highlighter-rouge">page</code> layout, and if none exists, will use your theme’s <code class="highlighter-rouge">page</code> layout.</p>
|
366
491
|
|
367
492
|
<h3 id="assets">Assets</h3>
|
368
493
|
|
369
|
-
<p>Any file in <code class="highlighter-rouge">/assets</code> will be copied over to the user’s site upon build unless they have a file with the same relative path. You
|
494
|
+
<p>Any file in <code class="highlighter-rouge">/assets</code> will be copied over to the user’s site upon build unless they have a file with the same relative path. You can ship any kind of asset here: SCSS, an image, a webfont, etc. These files behave like pages and static files in Jekyll:</p>
|
495
|
+
|
496
|
+
<ul>
|
497
|
+
<li>If the file has <a href="../docs/frontmatter/">YAML front matter</a> at the top, it will be rendered.</li>
|
498
|
+
<li>If the file does not have YAML front matter, it will simply be copied over into the resulting site.</li>
|
499
|
+
</ul>
|
500
|
+
|
501
|
+
<p>This allows theme creators to ship a default <code class="highlighter-rouge">/assets/styles.scss</code> file which their layouts can depend on as <code class="highlighter-rouge">/assets/styles.css</code>.</p>
|
370
502
|
|
371
503
|
<p>All files in <code class="highlighter-rouge">/assets</code> will be output into the compiled site in the <code class="highlighter-rouge">/assets</code> folder just as you’d expect from using Jekyll on your sites.</p>
|
372
504
|
|
373
505
|
<h3 id="stylesheets">Stylesheets</h3>
|
374
506
|
|
375
|
-
<p>Your theme’s stylesheets should be placed in your theme’s <code class="highlighter-rouge"
|
507
|
+
<p>Your theme’s stylesheets should be placed in your theme’s <code class="highlighter-rouge">_sass</code> folder, again, just as you would when authoring a Jekyll site.</p>
|
508
|
+
|
509
|
+
<div class="highlighter-rouge">
|
510
|
+
<pre class="highlight"><code>_sass
|
511
|
+
├── jekyll-theme-awesome.scss
|
512
|
+
</code></pre>
|
513
|
+
</div>
|
514
|
+
|
515
|
+
<p>Your theme’s styles can be included in the user’s stylesheet using the <code class="highlighter-rouge">@import</code> directive.</p>
|
516
|
+
|
517
|
+
<div class="language-css highlighter-rouge">
|
518
|
+
<pre class="highlight"><code><span class="k">@import</span> <span class="s1">"{{ site.theme }}"</span><span class="p">;</span>
|
519
|
+
</code></pre>
|
520
|
+
</div>
|
376
521
|
|
377
522
|
<h3 id="documenting-your-theme">Documenting your theme</h3>
|
378
523
|
|
@@ -386,32 +531,31 @@ For <span class="nb">help </span>getting started, <span class="nb">read</span> /
|
|
386
531
|
|
387
532
|
<p>To preview your theme as you’re authoring it, it may be helpful to add dummy content in, for example, <code class="highlighter-rouge">/index.html</code> and <code class="highlighter-rouge">/page.html</code> files. This will allow you to use the <code class="highlighter-rouge">jekyll build</code> and <code class="highlighter-rouge">jekyll serve</code> commands to preview your theme, just as you’d preview a Jekyll site.</p>
|
388
533
|
|
389
|
-
<p
|
534
|
+
<p>If you do preview your theme locally, be sure to add <code class="highlighter-rouge">/_site</code> to your theme’s <code class="highlighter-rouge">.gitignore</code> file to prevent the compiled site from also being included when you distribute your theme. {: .info .note}</p>
|
390
535
|
|
391
536
|
<h3 id="publishing-your-theme">Publishing your theme</h3>
|
392
537
|
|
393
|
-
<p>Themes are published via <a href="https://rubygems.org">RubyGems.org</a>. You
|
538
|
+
<p>Themes are published via <a href="https://rubygems.org">RubyGems.org</a>. You will need a RubyGems account, which you can <a href="https://rubygems.org/sign_up">create for free</a>.</p>
|
394
539
|
|
395
540
|
<ol>
|
396
541
|
<li>
|
397
|
-
<p>First, package your theme, by running the following command, replacing <code class="highlighter-rouge">
|
542
|
+
<p>First, package your theme, by running the following command, replacing <code class="highlighter-rouge">jekyll-theme-awesome</code> with the name of your theme:</p>
|
398
543
|
|
399
|
-
<div class="highlighter-rouge">
|
400
|
-
<pre class="highlight"><code>
|
544
|
+
<div class="language-sh highlighter-rouge">
|
545
|
+
<pre class="highlight"><code>gem build jekyll-theme-awesome.gemspec
|
401
546
|
</code></pre>
|
402
547
|
</div>
|
403
548
|
</li>
|
404
549
|
<li>
|
405
|
-
<p>Next, push your packaged theme up to the RubyGems service, by running the following command, again replacing <code class="highlighter-rouge">
|
550
|
+
<p>Next, push your packaged theme up to the RubyGems service, by running the following command, again replacing <code class="highlighter-rouge">jekyll-theme-awesome</code> with the name of your theme:</p>
|
406
551
|
|
407
|
-
<div class="highlighter-rouge">
|
408
|
-
<pre class="highlight"><code>
|
552
|
+
<div class="language-sh highlighter-rouge">
|
553
|
+
<pre class="highlight"><code>gem push jekyll-theme-awesome-<span class="k">*</span>.gem
|
409
554
|
</code></pre>
|
410
555
|
</div>
|
411
556
|
</li>
|
412
557
|
<li>
|
413
|
-
<p>To release a new version of your theme,
|
414
|
-
We recommend that you follow <a href="http://semver.org/">Semantic Versioning</a> while bumping your theme-version.</p>
|
558
|
+
<p>To release a new version of your theme, update the version number in the gemspec file, ( <code class="highlighter-rouge">jekyll-theme-awesome.gemspec</code> in this example ), and then repeat Steps 1 & 2 above. We recommend that you follow <a href="http://semver.org/">Semantic Versioning</a> while bumping your theme-version.</p>
|
415
559
|
</li>
|
416
560
|
</ol>
|
417
561
|
|
@@ -479,6 +623,9 @@ We recommend that you follow <a href="http://semver.org/">Semantic Versioning</a
|
|
479
623
|
|
480
624
|
|
481
625
|
|
626
|
+
|
627
|
+
|
628
|
+
|
482
629
|
|
483
630
|
|
484
631
|
|
@@ -592,6 +739,10 @@ We recommend that you follow <a href="http://semver.org/">Semantic Versioning</a
|
|
592
739
|
|
593
740
|
|
594
741
|
|
742
|
+
<li class=""><a href="/docs/includes/">Includes</a></li>
|
743
|
+
|
744
|
+
|
745
|
+
|
595
746
|
<li class=""><a href="/docs/permalinks/">Permalinks</a></li>
|
596
747
|
|
597
748
|
|
@@ -740,7 +891,7 @@ We recommend that you follow <a href="http://semver.org/">Semantic Versioning</a
|
|
740
891
|
</script>
|
741
892
|
|
742
893
|
|
743
|
-
<!-- Gauges (http://gaug.es/) -->
|
894
|
+
<!-- Gauges (http://get.gaug.es/) -->
|
744
895
|
<script>
|
745
896
|
var _gauges = _gauges || [];
|
746
897
|
(function() {
|
@@ -757,7 +908,7 @@ We recommend that you follow <a href="http://semver.org/">Semantic Versioning</a
|
|
757
908
|
|
758
909
|
|
759
910
|
|
760
|
-
<!-- Google Analytics (
|
911
|
+
<!-- Google Analytics (https://www.google.com/analytics) -->
|
761
912
|
<script>
|
762
913
|
!function(j,e,k,y,l,L){j.GoogleAnalyticsObject=y,j[y]||(j[y]=function(){
|
763
914
|
(j[y].q=j[y].q||[]).push(arguments)}),j[y].l=+new Date,l=e.createElement(k),
|
@@ -4,7 +4,7 @@
|
|
4
4
|
<meta http-equiv="Content-Type" content="text/html; charset=UTF-8">
|
5
5
|
<meta charset="UTF-8">
|
6
6
|
<meta name="viewport" content="width=device-width,initial-scale=1">
|
7
|
-
<meta name="generator" content="Jekyll v3.
|
7
|
+
<meta name="generator" content="Jekyll v3.4.0">
|
8
8
|
<link type="application/atom+xml" rel="alternate" href="https://jekyllrb.com/feed.xml" title="Jekyll • Simple, blog-aware, static sites">
|
9
9
|
<link rel="alternate" type="application/atom+xml" title="Recent commits to Jekyll’s master branch" href="https://github.com/jekyll/jekyll/commits/master.atom">
|
10
10
|
<link rel="stylesheet" href="//fonts.googleapis.com/css?family=Lato:300,300italic,400,400italic,700,700italic,900">
|
@@ -19,7 +19,7 @@
|
|
19
19
|
<meta property="og:url" content="https://jekyllrb.com/docs/troubleshooting/">
|
20
20
|
<meta property="og:site_name" content="Jekyll • Simple, blog-aware, static sites">
|
21
21
|
<meta property="og:type" content="article">
|
22
|
-
<meta property="article:published_time" content="2017-
|
22
|
+
<meta property="article:published_time" content="2017-03-22T08:06:48-07:00">
|
23
23
|
<meta name="twitter:card" content="summary">
|
24
24
|
<meta name="twitter:site" content="@jekyllrb">
|
25
25
|
<meta name="google-site-verification" content="onQcXpAvtHBrUI5LlroHNE_FP0b2qvFyPq7VZw36iEY">
|
@@ -27,7 +27,7 @@
|
|
27
27
|
{"@context": "http://schema.org",
|
28
28
|
"@type": "BlogPosting",
|
29
29
|
"headline": "Troubleshooting",
|
30
|
-
"datePublished": "2017-
|
30
|
+
"datePublished": "2017-03-22T08:06:48-07:00",
|
31
31
|
"description": "If you ever run into problems installing or using Jekyll, here are a few tips that might be of help. If the problem you’re experiencing isn’t covered below, please check out our other help resources as well.",
|
32
32
|
"publisher": {"@type": "Organization",
|
33
33
|
"logo": {"@type": "ImageObject",
|
@@ -192,6 +192,10 @@
|
|
192
192
|
|
193
193
|
|
194
194
|
|
195
|
+
<option value="/docs/includes/">Includes</option>
|
196
|
+
|
197
|
+
|
198
|
+
|
195
199
|
<option value="/docs/permalinks/">Permalinks</option>
|
196
200
|
|
197
201
|
|
@@ -602,6 +606,9 @@ The issue is caused by trying to copy a non-existing symlink.</p>
|
|
602
606
|
|
603
607
|
|
604
608
|
|
609
|
+
|
610
|
+
|
611
|
+
|
605
612
|
|
606
613
|
|
607
614
|
|
@@ -715,6 +722,10 @@ The issue is caused by trying to copy a non-existing symlink.</p>
|
|
715
722
|
|
716
723
|
|
717
724
|
|
725
|
+
<li class=""><a href="/docs/includes/">Includes</a></li>
|
726
|
+
|
727
|
+
|
728
|
+
|
718
729
|
<li class=""><a href="/docs/permalinks/">Permalinks</a></li>
|
719
730
|
|
720
731
|
|
@@ -863,7 +874,7 @@ The issue is caused by trying to copy a non-existing symlink.</p>
|
|
863
874
|
</script>
|
864
875
|
|
865
876
|
|
866
|
-
<!-- Gauges (http://gaug.es/) -->
|
877
|
+
<!-- Gauges (http://get.gaug.es/) -->
|
867
878
|
<script>
|
868
879
|
var _gauges = _gauges || [];
|
869
880
|
(function() {
|
@@ -880,7 +891,7 @@ The issue is caused by trying to copy a non-existing symlink.</p>
|
|
880
891
|
|
881
892
|
|
882
893
|
|
883
|
-
<!-- Google Analytics (
|
894
|
+
<!-- Google Analytics (https://www.google.com/analytics) -->
|
884
895
|
<script>
|
885
896
|
!function(j,e,k,y,l,L){j.GoogleAnalyticsObject=y,j[y]||(j[y]=function(){
|
886
897
|
(j[y].q=j[y].q||[]).push(arguments)}),j[y].l=+new Date,l=e.createElement(k),
|