jekyll-docs 3.2.1 → 3.3.0

data/site/docs/themes/index.html

@@ -4,7 +4,7 @@
 <meta http-equiv="Content-Type" content="text/html; charset=UTF-8">
   <meta charset="UTF-8">
   <meta name="viewport" content="width=device-width,initial-scale=1">
-  <meta name="generator" content="Jekyll v3.2.1">
+  <meta name="generator" content="Jekyll v3.3.0">
   <link type="application/atom+xml" rel="alternate" href="https://jekyllrb.com/feed.xml" title="Jekyll • Simple, blog-aware, static sites">
   <link rel="alternate" type="application/atom+xml" title="Recent commits to Jekyll’s master branch" href="https://github.com/jekyll/jekyll/commits/master.atom">
   <link rel="stylesheet" href="//fonts.googleapis.com/css?family=Lato:300,300italic,400,400italic,700,700italic,900">
@@ -19,7 +19,7 @@
 <meta property="og:url" content="https://jekyllrb.com/docs/themes/">
 <meta property="og:site_name" content="Jekyll • Simple, blog-aware, static sites">
 <meta property="og:type" content="article">
-<meta property="article:published_time" content="2016-08-02T18:14:35-07:00">
+<meta property="article:published_time" content="2016-10-06T11:16:34-07:00">
 <meta name="twitter:card" content="summary">
 <meta name="twitter:site" content="@jekyllrb">
 <meta name="google-site-verification" content="onQcXpAvtHBrUI5LlroHNE_FP0b2qvFyPq7VZw36iEY">
@@ -28,9 +28,9 @@
     "@context": "http://schema.org",
     "@type": "BlogPosting",
     "headline": "Themes",
-    "datePublished": "2016-08-02T18:14:35-07:00",
+    "datePublished": "2016-10-06T11:16:34-07:00",
     "description": "Jekyll has an extensive theme system, which allows you to leverage community-maintained templates and styles to customize your site’s presentation. Jekyll themes package layouts, includes, and stylesheets in a way that can be overridden by your site’s content.",
-    "logo": "https://jekyllrb.comimg/logo-2x.png",
+    "logo": "https://jekyllrb.com/img/logo-2x.png",
     "url": "https://jekyllrb.com/docs/themes/"
   }
 </script>
@@ -114,27 +114,27 @@
       
   
   
-  <option value="https://jekyllrb.com/docs/home/">Welcome</option>
+  <option value="/docs/home/">Welcome</option>
 
   
   
-  <option value="https://jekyllrb.com/docs/quickstart/">Quick-start guide</option>
+  <option value="/docs/quickstart/">Quick-start guide</option>
 
   
   
-  <option value="https://jekyllrb.com/docs/installation/">Installation</option>
+  <option value="/docs/installation/">Installation</option>
 
   
   
-  <option value="https://jekyllrb.com/docs/usage/">Basic Usage</option>
+  <option value="/docs/usage/">Basic Usage</option>
 
   
   
-  <option value="https://jekyllrb.com/docs/structure/">Directory structure</option>
+  <option value="/docs/structure/">Directory structure</option>
 
   
   
-  <option value="https://jekyllrb.com/docs/configuration/">Configuration</option>
+  <option value="/docs/configuration/">Configuration</option>
 
 
     </optgroup>
@@ -143,43 +143,43 @@
       
   
   
-  <option value="https://jekyllrb.com/docs/frontmatter/">Front Matter</option>
+  <option value="/docs/frontmatter/">Front Matter</option>
 
   
   
-  <option value="https://jekyllrb.com/docs/posts/">Writing posts</option>
+  <option value="/docs/posts/">Writing posts</option>
 
   
   
-  <option value="https://jekyllrb.com/docs/drafts/">Working with drafts</option>
+  <option value="/docs/drafts/">Working with drafts</option>
 
   
   
-  <option value="https://jekyllrb.com/docs/pages/">Creating pages</option>
+  <option value="/docs/pages/">Creating pages</option>
 
   
   
-  <option value="https://jekyllrb.com/docs/static-files/">Static Files</option>
+  <option value="/docs/static-files/">Static Files</option>
 
   
   
-  <option value="https://jekyllrb.com/docs/variables/">Variables</option>
+  <option value="/docs/variables/">Variables</option>
 
   
   
-  <option value="https://jekyllrb.com/docs/collections/">Collections</option>
+  <option value="/docs/collections/">Collections</option>
 
   
   
-  <option value="https://jekyllrb.com/docs/datafiles/">Data Files</option>
+  <option value="/docs/datafiles/">Data Files</option>
 
   
   
-  <option value="https://jekyllrb.com/docs/assets/">Assets</option>
+  <option value="/docs/assets/">Assets</option>
 
   
   
-  <option value="https://jekyllrb.com/docs/migrations/">Blog migrations</option>
+  <option value="/docs/migrations/">Blog migrations</option>
 
 
     </optgroup>
@@ -188,27 +188,27 @@
       
   
   
-  <option value="https://jekyllrb.com/docs/templates/">Templates</option>
+  <option value="/docs/templates/">Templates</option>
 
   
   
-  <option value="https://jekyllrb.com/docs/permalinks/">Permalinks</option>
+  <option value="/docs/permalinks/">Permalinks</option>
 
   
   
-  <option value="https://jekyllrb.com/docs/pagination/">Pagination</option>
+  <option value="/docs/pagination/">Pagination</option>
 
   
   
-  <option value="https://jekyllrb.com/docs/plugins/">Plugins</option>
+  <option value="/docs/plugins/">Plugins</option>
 
   
   
-  <option value="https://jekyllrb.com/docs/themes/">Themes</option>
+  <option value="/docs/themes/">Themes</option>
 
   
   
-  <option value="https://jekyllrb.com/docs/extras/">Extras</option>
+  <option value="/docs/extras/">Extras</option>
 
 
     </optgroup>
@@ -217,15 +217,15 @@
       
   
   
-  <option value="https://jekyllrb.com/docs/github-pages/">GitHub Pages</option>
+  <option value="/docs/github-pages/">GitHub Pages</option>
 
   
   
-  <option value="https://jekyllrb.com/docs/deployment-methods/">Deployment methods</option>
+  <option value="/docs/deployment-methods/">Deployment methods</option>
 
   
   
-  <option value="https://jekyllrb.com/docs/continuous-integration/">Continuous Integration</option>
+  <option value="/docs/continuous-integration/">Continuous Integration</option>
 
 
     </optgroup>
@@ -234,23 +234,23 @@
       
   
   
-  <option value="https://jekyllrb.com/docs/troubleshooting/">Troubleshooting</option>
+  <option value="/docs/troubleshooting/">Troubleshooting</option>
 
   
   
-  <option value="https://jekyllrb.com/docs/sites/">Sites using Jekyll</option>
+  <option value="/docs/sites/">Sites using Jekyll</option>
 
   
   
-  <option value="https://jekyllrb.com/docs/resources/">Resources</option>
+  <option value="/docs/resources/">Resources</option>
 
   
   
-  <option value="https://jekyllrb.com/docs/upgrading/0-to-2/">Upgrading from 0.x to 2.x</option>
+  <option value="/docs/upgrading/0-to-2/">Upgrading from 0.x to 2.x</option>
 
   
   
-  <option value="https://jekyllrb.com/docs/upgrading/2-to-3/">Upgrading from 2.x to 3.x</option>
+  <option value="/docs/upgrading/2-to-3/">Upgrading from 2.x to 3.x</option>
 
 
     </optgroup>
@@ -259,15 +259,15 @@
       
   
   
-  <option value="https://jekyllrb.com/docs/contributing/">Contributing</option>
+  <option value="/docs/contributing/">Contributing</option>
 
   
   
-  <option value="https://jekyllrb.com/docs/conduct/">Code of Conduct</option>
+  <option value="/docs/conduct/">Code of Conduct</option>
 
   
   
-  <option value="https://jekyllrb.com/docs/history/">History</option>
+  <option value="/docs/history/">History</option>
 
 
     </optgroup>
@@ -317,6 +317,7 @@
 <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>
 
 <ul>
+  <li><code class="highlighter-rouge">/assets</code></li>
   <li><code class="highlighter-rouge">/_layouts</code></li>
   <li><code class="highlighter-rouge">/_includes</code></li>
   <li><code class="highlighter-rouge">/_sass</code></li>
@@ -324,20 +325,34 @@
 
 <p class="note info">Refer to your selected theme’s documentation and source repository for more information on what files you can override.</p>
 
+<p>To locate theme’s files on your computer, 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. Then copy the files you want to override, from the returned path to your root folder.</p>
+
 <h2 id="creating-a-theme">Creating a theme</h2>
 
-<p>Jekyll themes are distributed as Ruby gems. The only required file is the <a href="http://guides.rubygems.org/specification-reference/">Ruby Gemspec</a>. Here’s an example of a minimal Gemspec for the <code class="highlighter-rouge">my-awesome-jekyll-theme</code> theme, saved as <code class="highlighter-rouge">/my-awsome-jekyll-theme.gemspec</code>:</p>
+<p>Jekyll themes are distributed as Ruby gems. Don’t worry, Jekyll will help you scaffold a new theme with the <code class="highlighter-rouge">new-theme</code> command. Just run <code class="highlighter-rouge">jekyll new-theme</code> with the theme name as an argument:</p>
+
+<div class="language-sh highlighter-rouge">
+<pre class="highlight"><code>jekyll new-theme my-awesome-theme
+             create /path/to/my-awesome-theme/_layouts
+             create /path/to/my-awesome-theme/_includes
+             create /path/to/my-awesome-theme/_sass
+             create /path/to/my-awesome-theme/_layouts/page.html
+             create /path/to/my-awesome-theme/_layouts/post.html
+             create /path/to/my-awesome-theme/_layouts/default.html
+             create /path/to/my-awesome-theme/Gemfile
+             create /path/to/my-awesome-theme/my-awesome-theme.gemspec
+             create /path/to/my-awesome-theme/README.md
+             create /path/to/my-awesome-theme/LICENSE.txt
+         initialize /path/to/my-awesome-theme/.git
+             create /path/to/my-awesome-theme/.gitignore
+Your new Jekyll theme, my-awesome-theme, is ready <span class="k">for </span>you <span class="k">in</span> /path/to/my-awesome-theme!
+For <span class="nb">help </span>getting started, <span class="nb">read</span> /path/to/my-awesome-theme/README.md.
+</code></pre>
+</div>
 
-<figure class="highlight"><pre><code class="language-ruby" data-lang="ruby"><span class="no">Gem</span><span class="o">::</span><span class="no">Specification</span><span class="p">.</span><span class="nf">new</span> <span class="k">do</span> <span class="o">|</span><span class="n">s</span><span class="o">|</span>
-  <span class="n">s</span><span class="p">.</span><span class="nf">name</span>     <span class="o">=</span> <span class="s1">'&lt;THEME TITLE&gt;'</span>
-  <span class="n">s</span><span class="p">.</span><span class="nf">version</span>  <span class="o">=</span> <span class="s1">'0.1.0'</span>
-  <span class="n">s</span><span class="p">.</span><span class="nf">license</span>  <span class="o">=</span> <span class="s1">'MIT'</span>
-  <span class="n">s</span><span class="p">.</span><span class="nf">summary</span>  <span class="o">=</span> <span class="s1">'&lt;THEME DESCRIPTION&gt;'</span>
-  <span class="n">s</span><span class="p">.</span><span class="nf">author</span>   <span class="o">=</span> <span class="s1">'&lt;YOUR NAME&gt;'</span>
-  <span class="n">s</span><span class="p">.</span><span class="nf">email</span>    <span class="o">=</span> <span class="s1">'&lt;YOUR EMAIL&gt;'</span>
-  <span class="n">s</span><span class="p">.</span><span class="nf">homepage</span> <span class="o">=</span> <span class="s1">'https://github.com/jekyll/my-awesome-jekyll-theme'</span>
-  <span class="n">s</span><span class="p">.</span><span class="nf">files</span>    <span class="o">=</span> <span class="sb">`git ls-files -z`</span><span class="p">.</span><span class="nf">split</span><span class="p">(</span><span class="s2">"</span><span class="se">\x0</span><span class="s2">"</span><span class="p">).</span><span class="nf">grep</span><span class="p">(</span><span class="sr">%r{^_(sass|includes|layouts)/}</span><span class="p">)</span>
-<span class="k">end</span></code></pre></figure>
+<p>Add your template files in the corresponding folders, complete the <code class="highlighter-rouge">.gemspec</code> and the README files according to your needs.</p>
 
 <h3 id="layouts-and-includes">Layouts and includes</h3>
 
@@ -345,6 +360,12 @@
 
 <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 a 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>
 
+<h3 id="assets">Assets</h3>
+
+<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 may ship any kind of asset here: SCSS, an image, a webfont, etc. These files behave just like pages and static files in Jekyll: if the file has <a href="/docs/frontmatter/">YAML front matter</a> at the top, then it will be rendered. If it does not have YAML front matter, it will simply be copied over into the resulting site. 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>
+
+<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>
+
 <h3 id="stylesheets">Stylesheets</h3>
 
 <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. Your theme’s styles can be included in the user’s stylesheet using the <code class="highlighter-rouge">@import</code> directive.</p>
@@ -384,6 +405,10 @@
 </code></pre>
     </div>
   </li>
+  <li>
+    <p>To release a new version of your theme, simply update the version number in the gemspec file, ( <code class="highlighter-rouge">my-awesome-jekyll-theme.gemspec</code> in this example ), and then repeat Steps 1 &amp; 2 above.
+We recommend that you follow <a href="http://semver.org/">Semantic Versioning</a> while bumping your theme-version.</p>
+  </li>
 </ol>
 
           
@@ -483,27 +508,27 @@
 
   
   
-  <li class=""><a href="https://jekyllrb.com/docs/home/">Welcome</a></li>
+  <li class=""><a href="/docs/home/">Welcome</a></li>
 
   
   
-  <li class=""><a href="https://jekyllrb.com/docs/quickstart/">Quick-start guide</a></li>
+  <li class=""><a href="/docs/quickstart/">Quick-start guide</a></li>
 
   
   
-  <li class=""><a href="https://jekyllrb.com/docs/installation/">Installation</a></li>
+  <li class=""><a href="/docs/installation/">Installation</a></li>
 
   
   
-  <li class=""><a href="https://jekyllrb.com/docs/usage/">Basic Usage</a></li>
+  <li class=""><a href="/docs/usage/">Basic Usage</a></li>
 
   
   
-  <li class=""><a href="https://jekyllrb.com/docs/structure/">Directory structure</a></li>
+  <li class=""><a href="/docs/structure/">Directory structure</a></li>
 
   
   
-  <li class=""><a href="https://jekyllrb.com/docs/configuration/">Configuration</a></li>
+  <li class=""><a href="/docs/configuration/">Configuration</a></li>
 
 </ul>
 
@@ -513,43 +538,43 @@
 
   
   
-  <li class=""><a href="https://jekyllrb.com/docs/frontmatter/">Front Matter</a></li>
+  <li class=""><a href="/docs/frontmatter/">Front Matter</a></li>
 
   
   
-  <li class=""><a href="https://jekyllrb.com/docs/posts/">Writing posts</a></li>
+  <li class=""><a href="/docs/posts/">Writing posts</a></li>
 
   
   
-  <li class=""><a href="https://jekyllrb.com/docs/drafts/">Working with drafts</a></li>
+  <li class=""><a href="/docs/drafts/">Working with drafts</a></li>
 
   
   
-  <li class=""><a href="https://jekyllrb.com/docs/pages/">Creating pages</a></li>
+  <li class=""><a href="/docs/pages/">Creating pages</a></li>
 
   
   
-  <li class=""><a href="https://jekyllrb.com/docs/static-files/">Static Files</a></li>
+  <li class=""><a href="/docs/static-files/">Static Files</a></li>
 
   
   
-  <li class=""><a href="https://jekyllrb.com/docs/variables/">Variables</a></li>
+  <li class=""><a href="/docs/variables/">Variables</a></li>
 
   
   
-  <li class=""><a href="https://jekyllrb.com/docs/collections/">Collections</a></li>
+  <li class=""><a href="/docs/collections/">Collections</a></li>
 
   
   
-  <li class=""><a href="https://jekyllrb.com/docs/datafiles/">Data Files</a></li>
+  <li class=""><a href="/docs/datafiles/">Data Files</a></li>
 
   
   
-  <li class=""><a href="https://jekyllrb.com/docs/assets/">Assets</a></li>
+  <li class=""><a href="/docs/assets/">Assets</a></li>
 
   
   
-  <li class=""><a href="https://jekyllrb.com/docs/migrations/">Blog migrations</a></li>
+  <li class=""><a href="/docs/migrations/">Blog migrations</a></li>
 
 </ul>
 
@@ -559,27 +584,27 @@
 
   
   
-  <li class=""><a href="https://jekyllrb.com/docs/templates/">Templates</a></li>
+  <li class=""><a href="/docs/templates/">Templates</a></li>
 
   
   
-  <li class=""><a href="https://jekyllrb.com/docs/permalinks/">Permalinks</a></li>
+  <li class=""><a href="/docs/permalinks/">Permalinks</a></li>
 
   
   
-  <li class=""><a href="https://jekyllrb.com/docs/pagination/">Pagination</a></li>
+  <li class=""><a href="/docs/pagination/">Pagination</a></li>
 
   
   
-  <li class=""><a href="https://jekyllrb.com/docs/plugins/">Plugins</a></li>
+  <li class=""><a href="/docs/plugins/">Plugins</a></li>
 
   
   
-  <li class="current"><a href="https://jekyllrb.com/docs/themes/">Themes</a></li>
+  <li class="current"><a href="/docs/themes/">Themes</a></li>
 
   
   
-  <li class=""><a href="https://jekyllrb.com/docs/extras/">Extras</a></li>
+  <li class=""><a href="/docs/extras/">Extras</a></li>
 
 </ul>
 
@@ -589,15 +614,15 @@
 
   
   
-  <li class=""><a href="https://jekyllrb.com/docs/github-pages/">GitHub Pages</a></li>
+  <li class=""><a href="/docs/github-pages/">GitHub Pages</a></li>
 
   
   
-  <li class=""><a href="https://jekyllrb.com/docs/deployment-methods/">Deployment methods</a></li>
+  <li class=""><a href="/docs/deployment-methods/">Deployment methods</a></li>
 
   
   
-  <li class=""><a href="https://jekyllrb.com/docs/continuous-integration/">Continuous Integration</a></li>
+  <li class=""><a href="/docs/continuous-integration/">Continuous Integration</a></li>
 
 </ul>
 
@@ -607,23 +632,23 @@
 
   
   
-  <li class=""><a href="https://jekyllrb.com/docs/troubleshooting/">Troubleshooting</a></li>
+  <li class=""><a href="/docs/troubleshooting/">Troubleshooting</a></li>
 
   
   
-  <li class=""><a href="https://jekyllrb.com/docs/sites/">Sites using Jekyll</a></li>
+  <li class=""><a href="/docs/sites/">Sites using Jekyll</a></li>
 
   
   
-  <li class=""><a href="https://jekyllrb.com/docs/resources/">Resources</a></li>
+  <li class=""><a href="/docs/resources/">Resources</a></li>
 
   
   
-  <li class=""><a href="https://jekyllrb.com/docs/upgrading/0-to-2/">Upgrading from 0.x to 2.x</a></li>
+  <li class=""><a href="/docs/upgrading/0-to-2/">Upgrading from 0.x to 2.x</a></li>
 
   
   
-  <li class=""><a href="https://jekyllrb.com/docs/upgrading/2-to-3/">Upgrading from 2.x to 3.x</a></li>
+  <li class=""><a href="/docs/upgrading/2-to-3/">Upgrading from 2.x to 3.x</a></li>
 
 </ul>
 
@@ -633,15 +658,15 @@
 
   
   
-  <li class=""><a href="https://jekyllrb.com/docs/contributing/">Contributing</a></li>
+  <li class=""><a href="/docs/contributing/">Contributing</a></li>
 
   
   
-  <li class=""><a href="https://jekyllrb.com/docs/conduct/">Code of Conduct</a></li>
+  <li class=""><a href="/docs/conduct/">Code of Conduct</a></li>
 
   
   
-  <li class=""><a href="https://jekyllrb.com/docs/history/">History</a></li>
+  <li class=""><a href="/docs/history/">History</a></li>
 
 </ul>