jekyll-docs 3.3.1 → 3.4.0

data/site/docs/sites/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.3.1">
+  <meta name="generator" content="Jekyll v3.4.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/sites/">
 <meta property="og:site_name" content="Jekyll • Simple, blog-aware, static sites">
 <meta property="og:type" content="article">
-<meta property="article:published_time" content="2017-01-20T13:17:57-08:00">
+<meta property="article:published_time" content="2017-03-22T08:06:48-07:00">
 <meta name="twitter:card" content="summary">
 <meta name="twitter:site" content="@jekyllrb">
 <meta name="google-site-verification" content="onQcXpAvtHBrUI5LlroHNE_FP0b2qvFyPq7VZw36iEY">
@@ -27,7 +27,7 @@
 {"@context": "http://schema.org",
 "@type": "BlogPosting",
 "headline": "Sites using Jekyll",
-"datePublished": "2017-01-20T13:17:57-08:00",
+"datePublished": "2017-03-22T08:06:48-07:00",
 "description": "It’s interesting to see what designs and features others have come up with. Below are some Jekyll-powered blogs which were hand-picked for learning purposes.",
 "publisher": {"@type": "Organization",
 "logo": {"@type": "ImageObject",
@@ -192,6 +192,10 @@
 
   
   
+  <option value="/docs/includes/">Includes</option>
+
+  
+  
   <option value="/docs/permalinks/">Permalinks</option>
 
   
@@ -295,10 +299,10 @@ learning purposes.</p>
 <a href="http://tom.preston-werner.com/">Tom Preston-Werner</a>
   (<a href="https://github.com/mojombo/mojombo.github.io">source</a>)</li>
   <li>
-<a href="http://training.github.com">GitHub Official Teaching Materials</a>
+<a href="https://services.github.com/training/">GitHub Official Teaching Materials</a>
   (<a href="https://github.com/github/training-kit">source</a>)</li>
   <li>
-<a href="http://rsms.me/">Rasmus Andersson</a>
+<a href="https://rsms.me/">Rasmus Andersson</a>
   (<a href="https://github.com/rsms/rsms.github.com">source</a>)</li>
 </ul>
 
@@ -388,6 +392,9 @@ and their sources on the <a href="https://github.com/jekyll/jekyll/wiki/Sites">
   
 
   
+  
+
+  
   
 
   
@@ -501,6 +508,10 @@ and their sources on the <a href="https://github.com/jekyll/jekyll/wiki/Sites">
 
   
   
+  <li class=""><a href="/docs/includes/">Includes</a></li>
+
+  
+  
   <li class=""><a href="/docs/permalinks/">Permalinks</a></li>
 
   
@@ -649,7 +660,7 @@ and their sources on the <a href="https://github.com/jekyll/jekyll/wiki/Sites">
 </script>
 
   
-  <!-- Gauges (http://gaug.es/) -->
+  <!-- Gauges (http://get.gaug.es/) -->
   <script>
     var _gauges = _gauges || [];
     (function() {
@@ -666,7 +677,7 @@ and their sources on the <a href="https://github.com/jekyll/jekyll/wiki/Sites">
 
 
 
-  <!-- Google Analytics (http://google.com/analytics) -->
+  <!-- Google Analytics (https://www.google.com/analytics) -->
   <script>
     !function(j,e,k,y,l,L){j.GoogleAnalyticsObject=y,j[y]||(j[y]=function(){
     (j[y].q=j[y].q||[]).push(arguments)}),j[y].l=+new Date,l=e.createElement(k),

data/site/docs/static-files/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.3.1">
+  <meta name="generator" content="Jekyll v3.4.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/static-files/">
 <meta property="og:site_name" content="Jekyll • Simple, blog-aware, static sites">
 <meta property="og:type" content="article">
-<meta property="article:published_time" content="2017-01-20T13:17:57-08:00">
+<meta property="article:published_time" content="2017-03-22T08:06:48-07:00">
 <meta name="twitter:card" content="summary">
 <meta name="twitter:site" content="@jekyllrb">
 <meta name="google-site-verification" content="onQcXpAvtHBrUI5LlroHNE_FP0b2qvFyPq7VZw36iEY">
@@ -27,7 +27,7 @@
 {"@context": "http://schema.org",
 "@type": "BlogPosting",
 "headline": "Static Files",
-"datePublished": "2017-01-20T13:17:57-08:00",
+"datePublished": "2017-03-22T08:06:48-07:00",
 "description": "In addition to renderable and convertible content, we also have static files.",
 "publisher": {"@type": "Organization",
 "logo": {"@type": "ImageObject",
@@ -192,6 +192,10 @@
 
   
   
+  <option value="/docs/includes/">Includes</option>
+
+  
+  
   <option value="/docs/permalinks/">Permalinks</option>
 
   
@@ -308,7 +312,7 @@ following metadata:</p>
       <td><p><code>file.path</code></p></td>
       <td><p>
 
-        The relative path to the file, e.g <code>/assets/img/image.jpg</code>
+        The relative path to the file, e.g. <code>/assets/img/image.jpg</code>
 
       </p></td>
     </tr>
@@ -316,7 +320,7 @@ following metadata:</p>
       <td><p><code>file.modified_time</code></p></td>
       <td><p>
 
-        The `Time` the file was last modified, e.g <code>2016-04-01 16:35:26 +0200</code>
+        The `Time` the file was last modified, e.g. <code>2016-04-01 16:35:26 +0200</code>
 
       </p></td>
     </tr>
@@ -496,6 +500,10 @@ following metadata:</p>
 
   
   
+  <li class=""><a href="/docs/includes/">Includes</a></li>
+
+  
+  
   <li class=""><a href="/docs/permalinks/">Permalinks</a></li>
 
   
@@ -644,7 +652,7 @@ following metadata:</p>
 </script>
 
   
-  <!-- Gauges (http://gaug.es/) -->
+  <!-- Gauges (http://get.gaug.es/) -->
   <script>
     var _gauges = _gauges || [];
     (function() {
@@ -661,7 +669,7 @@ following metadata:</p>
 
 
 
-  <!-- Google Analytics (http://google.com/analytics) -->
+  <!-- Google Analytics (https://www.google.com/analytics) -->
   <script>
     !function(j,e,k,y,l,L){j.GoogleAnalyticsObject=y,j[y]||(j[y]=function(){
     (j[y].q=j[y].q||[]).push(arguments)}),j[y].l=+new Date,l=e.createElement(k),

data/site/docs/structure/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.3.1">
+  <meta name="generator" content="Jekyll v3.4.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/structure/">
 <meta property="og:site_name" content="Jekyll • Simple, blog-aware, static sites">
 <meta property="og:type" content="article">
-<meta property="article:published_time" content="2017-01-20T13:17:57-08:00">
+<meta property="article:published_time" content="2017-03-22T08:06:48-07:00">
 <meta name="twitter:card" content="summary">
 <meta name="twitter:site" content="@jekyllrb">
 <meta name="google-site-verification" content="onQcXpAvtHBrUI5LlroHNE_FP0b2qvFyPq7VZw36iEY">
@@ -27,7 +27,7 @@
 {"@context": "http://schema.org",
 "@type": "BlogPosting",
 "headline": "Directory structure",
-"datePublished": "2017-01-20T13:17:57-08:00",
+"datePublished": "2017-03-22T08:06:48-07:00",
 "description": "Jekyll is, at its core, a text transformation engine. The concept behind the system is this: you give it text written in your favorite markup language, be that Markdown, Textile, or just plain HTML, and it churns that through a layout or a series of layout files. Throughout that process you can tweak how you want the site URLs to look, what data gets displayed in the layout, and more. This is all done through editing text files; the static web site is the final product.",
 "publisher": {"@type": "Organization",
 "logo": {"@type": "ImageObject",
@@ -192,6 +192,10 @@
 
   
   
+  <option value="/docs/includes/">Includes</option>
+
+  
+  
   <option value="/docs/permalinks/">Permalinks</option>
 
   
@@ -299,6 +303,8 @@ product.</p>
 <div class="language-sh highlighter-rouge">
 <pre class="highlight"><code>.
 ├── _config.yml
+├── _data
+|   └── members.yml
 ├── _drafts
 |   ├── begin-with-the-crazy-ideas.md
 |   └── on-simplicity-in-technology.md
@@ -311,14 +317,26 @@ product.</p>
 ├── _posts
 |   ├── 2007-10-29-why-every-programmer-should-play-nethack.md
 |   └── 2009-04-26-barcamp-boston-4-roundup.md
-├── _data
-|   └── members.yml
+├── _sass
+|   ├── _base.scss
+|   └── _layout.scss
 ├── _site
 ├── .jekyll-metadata
-└── index.html
+└── index.html <span class="c"># can also be an 'index.md' with valid YAML Frontmatter</span>
 </code></pre>
 </div>
 
+<div class="note info">
+  <h5>Directory structure of Jekyll sites using gem-based themes</h5>
+  <p>
+    Starting <strong>Jekyll 3.2</strong>, a new Jekyll project bootstrapped with <code>jekyll new</code> uses <a href="../themes/">gem-based themes</a> to define the look of the site. This results in a lighter default directory structure : <code>_layouts</code>, <code>_includes</code> and <code>_sass</code> are stored in the theme-gem, by default.
+  </p>
+  <br>
+  <p>
+     <a href="https://github.com/jekyll/minima">minima</a> is the current default theme, and <code>bundle show minima</code> will show you where minima theme's files are stored on your computer.
+  </p>
+</div>
+
 <p>An overview of what each of these does:</p>
 
 <div class="mobile-side-scroller">
@@ -336,11 +354,9 @@ product.</p>
       </td>
       <td>
         <p>
-
           Stores <a href="../configuration/">configuration</a> data. Many of
           these options can be specified from the command line executable but
           it’s easier to specify them here so you don’t have to remember them.
-
         </p>
       </td>
     </tr>
@@ -350,11 +366,9 @@ product.</p>
       </td>
       <td>
         <p>
-
           Drafts are unpublished posts. The format of these files is without a
           date: <code>title.MARKUP</code>. Learn how to <a href="../drafts/">
           work with drafts</a>.
-
         </p>
       </td>
     </tr>
@@ -364,13 +378,11 @@ product.</p>
       </td>
       <td>
         <p>
-
           These are the partials that can be mixed and matched by your layouts
           and posts to facilitate reuse. The liquid tag
           <code>{% include file.ext %}</code>
           can be used to include the partial in
           <code>_includes/file.ext</code>.
-
         </p>
       </td>
     </tr>
@@ -380,14 +392,12 @@ product.</p>
       </td>
       <td>
         <p>
-
           These are the templates that wrap posts. Layouts are chosen on a
           post-by-post basis in the
           <a href="../frontmatter/">YAML Front Matter</a>,
           which is described in the next section. The liquid tag
           <code>{{ content }}</code>
           is used to inject content into the web page.
-
         </p>
       </td>
     </tr>
@@ -397,14 +407,12 @@ product.</p>
       </td>
       <td>
         <p>
-
           Your dynamic content, so to speak. The naming convention of these
           files is important, and must follow the format:
           <code>YEAR-MONTH-DAY-title.MARKUP</code>.
           The <a href="../permalinks/">permalinks</a> can be customized for
           each post, but the date and markup language are determined solely by
           the file name.
-
         </p>
       </td>
     </tr>
@@ -414,15 +422,25 @@ product.</p>
       </td>
       <td>
         <p>
-
           Well-formatted site data should be placed here. The Jekyll engine
-          will autoload all YAML files in this directory (using either the
-          <code>.yml</code>, <code>.yaml</code>, <code>.json</code> or
-          <code>.csv</code> formats and extensions) and they will be
+          will autoload all data files (using either the <code>.yml</code>,
+          <code>.yaml</code>, <code>.json</code> or <code>.csv</code>
+          formats and extensions) in this directory, and they will be
           accessible via `site.data`. If there's a file
           <code>members.yml</code> under the directory, then you can access
           contents of the file through <code>site.data.members</code>.
-
+        </p>
+      </td>
+    </tr>
+    <tr>
+      <td>
+        <p><code>_sass</code></p>
+      </td>
+      <td>
+        <p>
+          These are sass partials that can be imported into your <code>main.scss</code>
+          which will then be processed into a single stylesheet
+          <code>main.css</code> that defines the styles to be used by your site.
         </p>
       </td>
     </tr>
@@ -432,11 +450,9 @@ product.</p>
       </td>
       <td>
         <p>
-
           This is where the generated site will be placed (by default) once
           Jekyll is done transforming it. It’s probably a good idea to add this
           to your <code>.gitignore</code> file.
-
         </p>
       </td>
     </tr>
@@ -446,29 +462,26 @@ product.</p>
       </td>
       <td>
         <p>
-
           This helps Jekyll keep track of which files have not been modified
           since the site was last built, and which files will need to be
           regenerated on the next build. This file will not be included in the
           generated site. It’s probably a good idea to add this to your
           <code>.gitignore</code> file.
-
         </p>
       </td>
     </tr>
     <tr>
       <td>
-        <p><code>index.html</code> and other HTML, Markdown, Textile files</p>
+        <p><code>index.html</code> or <code>index.md</code> and other HTML,
+        Markdown, Textile files</p>
       </td>
       <td>
         <p>
-
           Provided that the file has a <a href="../frontmatter/">YAML Front
           Matter</a> section, it will be transformed by Jekyll. The same will
           happen for any <code>.html</code>, <code>.markdown</code>,
           <code>.md</code>, or <code>.textile</code> file in your site’s root
           directory or directories not listed above.
-
         </p>
       </td>
     </tr>
@@ -478,14 +491,12 @@ product.</p>
       </td>
       <td>
         <p>
-
           Every other directory and file except for those listed above—such as
           <code>css</code> and <code>images</code> folders,
           <code>favicon.ico</code> files, and so forth—will be copied verbatim
           to the generated site. There are plenty of <a href="../sites/">sites
           already using Jekyll</a> if you’re curious to see how they’re laid
           out.
-
         </p>
       </td>
     </tr>
@@ -622,6 +633,10 @@ product.</p>
 
   
   
+  <li class=""><a href="/docs/includes/">Includes</a></li>
+
+  
+  
   <li class=""><a href="/docs/permalinks/">Permalinks</a></li>
 
   
@@ -770,7 +785,7 @@ product.</p>
 </script>
 
   
-  <!-- Gauges (http://gaug.es/) -->
+  <!-- Gauges (http://get.gaug.es/) -->
   <script>
     var _gauges = _gauges || [];
     (function() {
@@ -787,7 +802,7 @@ product.</p>
 
 
 
-  <!-- Google Analytics (http://google.com/analytics) -->
+  <!-- Google Analytics (https://www.google.com/analytics) -->
   <script>
     !function(j,e,k,y,l,L){j.GoogleAnalyticsObject=y,j[y]||(j[y]=function(){
     (j[y].q=j[y].q||[]).push(arguments)}),j[y].l=+new Date,l=e.createElement(k),

data/site/docs/templates/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.3.1">
+  <meta name="generator" content="Jekyll v3.4.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/templates/">
 <meta property="og:site_name" content="Jekyll • Simple, blog-aware, static sites">
 <meta property="og:type" content="article">
-<meta property="article:published_time" content="2017-01-20T13:17:57-08:00">
+<meta property="article:published_time" content="2017-03-22T08:06:48-07:00">
 <meta name="twitter:card" content="summary">
 <meta name="twitter:site" content="@jekyllrb">
 <meta name="google-site-verification" content="onQcXpAvtHBrUI5LlroHNE_FP0b2qvFyPq7VZw36iEY">
@@ -27,7 +27,7 @@
 {"@context": "http://schema.org",
 "@type": "BlogPosting",
 "headline": "Templates",
-"datePublished": "2017-01-20T13:17:57-08:00",
+"datePublished": "2017-03-22T08:06:48-07:00",
 "description": "Jekyll uses the Liquid templating language to process templates. All of the standard Liquid tags and filters are supported. Jekyll even adds a few handy filters and tags of its own to make common tasks easier.",
 "publisher": {"@type": "Organization",
 "logo": {"@type": "ImageObject",
@@ -192,6 +192,10 @@
 
   
   
+  <option value="/docs/includes/">Includes</option>
+
+  
+  
   <option value="/docs/permalinks/">Permalinks</option>
 
   
@@ -431,6 +435,22 @@ common tasks easier.</p>
         </p>
       </td>
     </tr>
+    <tr>
+      <td>
+        <p class="name"><strong>Group By Expression</strong></p>
+        <p>Group an array's items using a Liquid expression.</p>
+      </td>
+      <td class="align-center">
+        <p>
+         <code class="filter">{{ site.members | group_by_exp:"item",
+"item.graduation_year | truncate: 3, \"\"" }}</code>
+        </p>
+        <p>
+          <code class="output">[{"name"=&gt;"201...", "items"=&gt;[...]},
+{"name"=&gt;"200...", "items"=&gt;[...]}]</code>
+        </p>
+      </td>
+    </tr>
     <tr>
       <td>
         <p class="name"><strong>XML Escape</strong></p>
@@ -492,7 +512,7 @@ common tasks easier.</p>
     <tr>
       <td>
         <p class="name"><strong>Array to Sentence</strong></p>
-        <p>Convert an array into a sentence. Useful for listing tags.</p>
+        <p>Convert an array into a sentence. Useful for listing tags. Optional argument for connector.</p>
       </td>
       <td class="align-center">
         <p>
@@ -501,6 +521,12 @@ common tasks easier.</p>
         <p>
           <code class="output">foo, bar, and baz</code>
         </p>
+        <p>
+         <code class="filter">{{ page.tags | array_to_sentence_string: 'or' }}</code>
+        </p>
+        <p>
+          <code class="output">foo, bar, or baz</code>
+        </p>
       </td>
     </tr>
     <tr>
@@ -690,60 +716,16 @@ The default is <code class="highlighter-rouge">default</code>. They are as follo
 
 <h3 id="includes">Includes</h3>
 
-<p>If you have small page fragments that you wish to include in multiple places on
-your site, you can use the <code class="highlighter-rouge">include</code> tag.</p>
+<p>If you have small page snippets that you want to include in multiple places on your site, save the snippets as <em>include files</em> and insert them where required, by using the <code class="highlighter-rouge">include</code> tag:</p>
 
 <div class="language-liquid highlighter-rouge">
 <pre class="highlight"><code><span class="p">{%</span><span class="w"> </span><span class="nt">include</span><span class="w"> </span><span class="na">footer</span><span class="p">.</span><span class="na">html</span><span class="w"> </span><span class="p">%}</span>
 </code></pre>
 </div>
 
-<p>Jekyll expects all include files to be placed in an <code class="highlighter-rouge">_includes</code> directory at the
-root of your source directory. This will embed the contents of
-<code class="highlighter-rouge">&lt;source&gt;/_includes/footer.html</code> into the calling file.</p>
-
-<div class="note">
-  <h5>ProTip™: Use variables as file name</h5>
-  <p>
-
-    The name of the file you wish to embed can be literal (as in the example above),
-    or you can use a variable, using liquid-like variable syntax as in
-    <code>{% include {{my_variable}} %}</code>.
-
-  </p>
-</div>
-
-<p>You can also pass parameters to an include. Omit the quotation marks to send a variable’s value. Liquid curly brackets should not be used here:</p>
-
-<div class="language-liquid highlighter-rouge">
-<pre class="highlight"><code><span class="p">{%</span><span class="w"> </span><span class="nt">include</span><span class="w"> </span><span class="na">footer</span><span class="p">.</span><span class="na">html</span><span class="w"> </span><span class="na">param</span><span class="o">=</span><span class="s2">"value"</span><span class="w"> </span><span class="na">variable-param</span><span class="o">=</span><span class="nv">page</span><span class="p">.</span><span class="nv">variable</span><span class="w"> </span><span class="p">%}</span>
-</code></pre>
-</div>
-
-<p>These parameters are available via Liquid in the include:</p>
-
-<div class="language-liquid highlighter-rouge">
-<pre class="highlight"><code><span class="p">{{</span><span class="w"> </span><span class="nv">include</span><span class="p">.</span><span class="nv">param</span><span class="w"> </span><span class="p">}}</span>
-</code></pre>
-</div>
-
-<h4 id="including-files-relative-to-another-file">Including files relative to another file</h4>
-
-<p>You can also choose to include file fragments relative to the current file:</p>
-
-<div class="language-liquid highlighter-rouge">
-<pre class="highlight"><code><span class="p">{%</span><span class="w"> </span><span class="nt">include</span><span class="na">_relative somedir/footer</span><span class="p">.</span><span class="na">html</span><span class="w"> </span><span class="p">%}</span>
-</code></pre>
-</div>
-
-<p>You won’t need to place your included content within the <code class="highlighter-rouge">_includes</code> directory. Instead,
-the inclusion is specifically relative to the file where the tag is being used. For example,
-if <code class="highlighter-rouge">_posts/2014-09-03-my-file.markdown</code> uses the <code class="highlighter-rouge">include_relative</code> tag, the included file
-must be within the <code class="highlighter-rouge">_posts</code> directory, or one of its subdirectories. You cannot include
-files in other locations.</p>
+<p>Jekyll expects all <em>include files</em> to be placed in an <code class="highlighter-rouge">_includes</code> directory at the root of your source directory. In the above example, this will embed the contents of <code class="highlighter-rouge">_includes/footer.html</code> into the calling file.</p>
 
-<p>All the other capabilities of the <code class="highlighter-rouge">include</code> tag are available to the <code class="highlighter-rouge">include_relative</code> tag,
-such as using variables.</p>
+<p>For more advanced information on using includes, see <a href="../includes">Includes</a>.</p>
 
 <h3 id="code-snippet-highlighting">Code snippet highlighting</h3>
 
@@ -805,93 +787,103 @@ site. If you use <code class="highlighter-rouge">linenos</code>, you might want
 definition for the <code class="highlighter-rouge">.lineno</code> class in <code class="highlighter-rouge">syntax.css</code> to distinguish the line
 numbers from the highlighted code.</p>
 
-<h3 id="link">Link</h3>
-
-<p>If you want to include a link to a collection’s document, a post, a page
-or a file the <code class="highlighter-rouge">link</code> tag will generate the correct permalink URL for the path
-you specify.</p>
+<h3 id="gist">Gist</h3>
 
-<p>You must include the file extension when using the <code class="highlighter-rouge">link</code> tag.</p>
+<p>Use the <code class="highlighter-rouge">gist</code> tag to easily embed a GitHub Gist onto your site. This works
+with public or secret gists:</p>
 
 <div class="language-liquid highlighter-rouge">
 <pre class="highlight"><code>
-<span class="p">{{</span><span class="w"> </span><span class="nv">site</span><span class="p">.</span><span class="nv">baseurl</span><span class="w"> </span><span class="p">}}{%</span><span class="w"> </span><span class="nt">link</span><span class="w"> </span>_collection/name-of-document.md<span class="w"> </span><span class="p">%}</span>
-<span class="p">{{</span><span class="w"> </span><span class="nv">site</span><span class="p">.</span><span class="nv">baseurl</span><span class="w"> </span><span class="p">}}{%</span><span class="w"> </span><span class="nt">link</span><span class="w"> </span>_posts/<span class="mi">2016</span>-<span class="mi">07</span>-<span class="mi">26</span>-name-of-post.md<span class="w"> </span><span class="p">%}</span>
-<span class="p">{{</span><span class="w"> </span><span class="nv">site</span><span class="p">.</span><span class="nv">baseurl</span><span class="w"> </span><span class="p">}}{%</span><span class="w"> </span><span class="nt">link</span><span class="w"> </span>news/index.html<span class="w"> </span><span class="p">%}</span>
-<span class="p">{{</span><span class="w"> </span><span class="nv">site</span><span class="p">.</span><span class="nv">baseurl</span><span class="w"> </span><span class="p">}}{%</span><span class="w"> </span><span class="nt">link</span><span class="w"> </span>/assets/files/doc.pdf<span class="w"> </span><span class="p">%}</span>
+<span class="p">{%</span><span class="w"> </span><span class="nt">gist</span><span class="w"> </span>parkr/<span class="mi">931</span>c<span class="mi">1</span>c<span class="mi">8</span>d<span class="mi">465</span>a<span class="mi">04042403</span><span class="w"> </span><span class="p">%}</span>
 
 </code></pre>
 </div>
 
-<p>You can also use this tag to create a link in Markdown as follows:</p>
+<p>You may also optionally specify the filename in the gist to display:</p>
 
 <div class="language-liquid highlighter-rouge">
 <pre class="highlight"><code>
-[Link to a document](<span class="p">{{</span><span class="w"> </span><span class="nv">site</span><span class="p">.</span><span class="nv">baseurl</span><span class="w"> </span><span class="p">}}{%</span><span class="w"> </span><span class="nt">link</span><span class="w"> </span>_collection/name-of-document.md<span class="w"> </span><span class="p">%}</span>)
-[Link to a post](<span class="p">{{</span><span class="w"> </span><span class="nv">site</span><span class="p">.</span><span class="nv">baseurl</span><span class="w"> </span><span class="p">}}{%</span><span class="w"> </span><span class="nt">link</span><span class="w"> </span>_posts/<span class="mi">2016</span>-<span class="mi">07</span>-<span class="mi">26</span>-name-of-post.md<span class="w"> </span><span class="p">%}</span>)
-[Link to a page](<span class="p">{{</span><span class="w"> </span><span class="nv">site</span><span class="p">.</span><span class="nv">baseurl</span><span class="w"> </span><span class="p">}}{%</span><span class="w"> </span><span class="nt">link</span><span class="w"> </span>news/index.html<span class="w"> </span><span class="p">%}</span>)
-[Link to a file](<span class="p">{{</span><span class="w"> </span><span class="nv">site</span><span class="p">.</span><span class="nv">baseurl</span><span class="w"> </span><span class="p">}}{%</span><span class="w"> </span><span class="nt">link</span><span class="w"> </span>/assets/files/doc.pdf<span class="w"> </span><span class="p">%}</span>)
+<span class="p">{%</span><span class="w"> </span><span class="nt">gist</span><span class="w"> </span>parkr/<span class="mi">931</span>c<span class="mi">1</span>c<span class="mi">8</span>d<span class="mi">465</span>a<span class="mi">04042403</span><span class="w"> </span>jekyll-private-gist.markdown<span class="w"> </span><span class="p">%}</span>
 
 </code></pre>
 </div>
 
-<h3 id="post-url">Post URL</h3>
+<p>To use the <code class="highlighter-rouge">gist</code> tag, you’ll need to add the
+<a href="https://github.com/jekyll/jekyll-gist">jekyll-gist</a> gem to your project.</p>
+
+<h2 id="links">Links</h2>
+
+<h3 id="link">Linking to pages</h3>
 
-<p>If you would like to include a link to a post on your site, the <code class="highlighter-rouge">post_url</code> tag
-will generate the correct permalink URL for the post you specify.</p>
+<p>To link to a post, a page, collection item, or file, the <code class="highlighter-rouge">link</code> tag will generate the correct permalink URL for the path you specify. For example, if you use the <code class="highlighter-rouge">link</code> tag to link to <code class="highlighter-rouge">mypage.html</code>, even if you change your permalink style to include the file extension or omit it, the URL formed by the <code class="highlighter-rouge">link</code> tag will always be valid.</p>
+
+<p>You must include the file’s original extension when using the <code class="highlighter-rouge">link</code> tag. Here are some examples:</p>
 
 <div class="language-liquid highlighter-rouge">
 <pre class="highlight"><code>
-<span class="p">{{</span><span class="w"> </span><span class="nv">site</span><span class="p">.</span><span class="nv">baseurl</span><span class="w"> </span><span class="p">}}{%</span><span class="w"> </span><span class="nt">post_url</span><span class="w"> </span><span class="mi">2010</span>-<span class="mi">07</span>-<span class="mi">21</span>-name-of-post<span class="w"> </span><span class="p">%}</span>
+<span class="p">{{</span><span class="w"> </span><span class="nv">site</span><span class="p">.</span><span class="nv">baseurl</span><span class="w"> </span><span class="p">}}{%</span><span class="w"> </span><span class="nt">link</span><span class="w"> </span>_collection/name-of-document.md<span class="w"> </span><span class="p">%}</span>
+<span class="p">{{</span><span class="w"> </span><span class="nv">site</span><span class="p">.</span><span class="nv">baseurl</span><span class="w"> </span><span class="p">}}{%</span><span class="w"> </span><span class="nt">link</span><span class="w"> </span>_posts/<span class="mi">2016</span>-<span class="mi">07</span>-<span class="mi">26</span>-name-of-post.md<span class="w"> </span><span class="p">%}</span>
+<span class="p">{{</span><span class="w"> </span><span class="nv">site</span><span class="p">.</span><span class="nv">baseurl</span><span class="w"> </span><span class="p">}}{%</span><span class="w"> </span><span class="nt">link</span><span class="w"> </span>news/index.html<span class="w"> </span><span class="p">%}</span>
+<span class="p">{{</span><span class="w"> </span><span class="nv">site</span><span class="p">.</span><span class="nv">baseurl</span><span class="w"> </span><span class="p">}}{%</span><span class="w"> </span><span class="nt">link</span><span class="w"> </span>/assets/files/doc.pdf<span class="w"> </span><span class="p">%}</span>
 
 </code></pre>
 </div>
 
-<p>If you organize your posts in subdirectories, you need to include subdirectory
-path to the post:</p>
+<p>You can also use the <code class="highlighter-rouge">link</code> tag to create a link in Markdown as follows:</p>
 
 <div class="language-liquid highlighter-rouge">
 <pre class="highlight"><code>
-<span class="p">{{</span><span class="w"> </span><span class="nv">site</span><span class="p">.</span><span class="nv">baseurl</span><span class="w"> </span><span class="p">}}{%</span><span class="w"> </span><span class="nt">post_url</span><span class="w"> </span>/subdir/<span class="mi">2010</span>-<span class="mi">07</span>-<span class="mi">21</span>-name-of-post<span class="w"> </span><span class="p">%}</span>
+[Link to a document](<span class="p">{{</span><span class="w"> </span><span class="nv">site</span><span class="p">.</span><span class="nv">baseurl</span><span class="w"> </span><span class="p">}}{%</span><span class="w"> </span><span class="nt">link</span><span class="w"> </span>_collection/name-of-document.md<span class="w"> </span><span class="p">%}</span>)
+[Link to a post](<span class="p">{{</span><span class="w"> </span><span class="nv">site</span><span class="p">.</span><span class="nv">baseurl</span><span class="w"> </span><span class="p">}}{%</span><span class="w"> </span><span class="nt">link</span><span class="w"> </span>_posts/<span class="mi">2016</span>-<span class="mi">07</span>-<span class="mi">26</span>-name-of-post.md<span class="w"> </span><span class="p">%}</span>)
+[Link to a page](<span class="p">{{</span><span class="w"> </span><span class="nv">site</span><span class="p">.</span><span class="nv">baseurl</span><span class="w"> </span><span class="p">}}{%</span><span class="w"> </span><span class="nt">link</span><span class="w"> </span>news/index.html<span class="w"> </span><span class="p">%}</span>)
+[Link to a file](<span class="p">{{</span><span class="w"> </span><span class="nv">site</span><span class="p">.</span><span class="nv">baseurl</span><span class="w"> </span><span class="p">}}{%</span><span class="w"> </span><span class="nt">link</span><span class="w"> </span>/assets/files/doc.pdf<span class="w"> </span><span class="p">%}</span>)
 
 </code></pre>
 </div>
 
-<p>There is no need to include the file extension when using the <code class="highlighter-rouge">post_url</code> tag.</p>
+<p>(Including <code class="highlighter-rouge"><span class="p">{</span><span class="err">{</span><span class="w"> </span><span class="err">site.baseurl</span><span class="w"> </span><span class="p">}</span><span class="err">}</span></code> is optional — it depends on whether you want to preface the page URL with the <code class="highlighter-rouge">baseurl</code> value.)</p>
 
-<p>You can also use this tag to create a link to a post in Markdown as follows:</p>
+<p>The path to the post, page, or collection is defined as the path relative to the root directory (where your config file is) to the file, not the path from your existing page to the other page.</p>
+
+<p>For example, suppose you’re creating a link <code class="highlighter-rouge">page_a.md</code> (stored in <code class="highlighter-rouge">pages/folder1/folder2</code>) to <code class="highlighter-rouge">page_b.md</code> (stored in  <code class="highlighter-rouge">pages/folder1</code>). Your path in the link would not be <code class="highlighter-rouge">../page_b.html</code>. Instead, it would be <code class="highlighter-rouge">/pages/folder1/page_b.md</code>.</p>
+
+<p>If you’re unsure of the path, add <code class="highlighter-rouge"><span class="p">{</span><span class="err">{</span><span class="w"> </span><span class="err">page.path</span><span class="w"> </span><span class="p">}</span><span class="err">}</span></code> to the page and it will display the path.</p>
+
+<p>One major benefit of using the <code class="highlighter-rouge">link</code> tag is link validation. If the link doesn’t exist, Jekyll won’t build your site. This is a good thing, as it will alert you to a broken link so you can fix it (rather than allowing you to build and deploy a site with broken links).</p>
+
+<p>Note you cannot add filters to <code class="highlighter-rouge">link</code> tags. For example, you cannot append a string using Liquid filters, such as <code class="highlighter-rouge"><span class="p">{</span><span class="err">%</span><span class="w"> </span><span class="err">link</span><span class="w"> </span><span class="err">mypage.html</span><span class="w"> </span><span class="err">|</span><span class="w"> </span><span class="err">append:</span><span class="w"> </span><span class="nt">"#section1"</span><span class="w"> </span><span class="err">%}</span><span class="w"> </span></code>. To link to sections on a page, you will need to use regular HTML or Markdown linking techniques.</p>
+
+<h3 id="linking-to-posts">Linking to posts</h3>
+
+<p>If you want like to include a link to a post on your site, the <code class="highlighter-rouge">post_url</code> tag will generate the correct permalink URL for the post you specify.</p>
 
 <div class="language-liquid highlighter-rouge">
 <pre class="highlight"><code>
-[Name of Link](<span class="p">{{</span><span class="w"> </span><span class="nv">site</span><span class="p">.</span><span class="nv">baseurl</span><span class="w"> </span><span class="p">}}{%</span><span class="w"> </span><span class="nt">post_url</span><span class="w"> </span><span class="mi">2010</span>-<span class="mi">07</span>-<span class="mi">21</span>-name-of-post<span class="w"> </span><span class="p">%}</span>)
+<span class="p">{{</span><span class="w"> </span><span class="nv">site</span><span class="p">.</span><span class="nv">baseurl</span><span class="w"> </span><span class="p">}}{%</span><span class="w"> </span><span class="nt">post_url</span><span class="w"> </span><span class="mi">2010</span>-<span class="mi">07</span>-<span class="mi">21</span>-name-of-post<span class="w"> </span><span class="p">%}</span>
 
 </code></pre>
 </div>
 
-<h3 id="gist">Gist</h3>
-
-<p>Use the <code class="highlighter-rouge">gist</code> tag to easily embed a GitHub Gist onto your site. This works
-with public or secret gists:</p>
+<p>If you organize your posts in subdirectories, you need to include subdirectory path to the post:</p>
 
 <div class="language-liquid highlighter-rouge">
 <pre class="highlight"><code>
-<span class="p">{%</span><span class="w"> </span><span class="nt">gist</span><span class="w"> </span>parkr/<span class="mi">931</span>c<span class="mi">1</span>c<span class="mi">8</span>d<span class="mi">465</span>a<span class="mi">04042403</span><span class="w"> </span><span class="p">%}</span>
+<span class="p">{{</span><span class="w"> </span><span class="nv">site</span><span class="p">.</span><span class="nv">baseurl</span><span class="w"> </span><span class="p">}}{%</span><span class="w"> </span><span class="nt">post_url</span><span class="w"> </span>/subdir/<span class="mi">2010</span>-<span class="mi">07</span>-<span class="mi">21</span>-name-of-post<span class="w"> </span><span class="p">%}</span>
 
 </code></pre>
 </div>
 
-<p>You may also optionally specify the filename in the gist to display:</p>
+<p>There is no need to include the file extension when using the <code class="highlighter-rouge">post_url</code> tag.</p>
+
+<p>You can also use this tag to create a link to a post in Markdown as follows:</p>
 
 <div class="language-liquid highlighter-rouge">
 <pre class="highlight"><code>
-<span class="p">{%</span><span class="w"> </span><span class="nt">gist</span><span class="w"> </span>parkr/<span class="mi">931</span>c<span class="mi">1</span>c<span class="mi">8</span>d<span class="mi">465</span>a<span class="mi">04042403</span><span class="w"> </span>jekyll-private-gist.markdown<span class="w"> </span><span class="p">%}</span>
+[Name of Link](<span class="p">{{</span><span class="w"> </span><span class="nv">site</span><span class="p">.</span><span class="nv">baseurl</span><span class="w"> </span><span class="p">}}{%</span><span class="w"> </span><span class="nt">post_url</span><span class="w"> </span><span class="mi">2010</span>-<span class="mi">07</span>-<span class="mi">21</span>-name-of-post<span class="w"> </span><span class="p">%}</span>)
 
 </code></pre>
 </div>
 
-<p>To use the <code class="highlighter-rouge">gist</code> tag, you’ll need to add the
-<a href="https://github.com/jekyll/jekyll-gist">jekyll-gist</a> gem to your project.</p>
-
           
 
 
@@ -960,7 +952,7 @@ with public or secret gists:</p>
           
             
             
-            <a href="/docs/permalinks/" class="next">Next</a>
+            <a href="/docs/includes/" class="next">Next</a>
           
       </div>
     </div>
@@ -1057,6 +1049,10 @@ with public or secret gists:</p>
 
   
   
+  <li class=""><a href="/docs/includes/">Includes</a></li>
+
+  
+  
   <li class=""><a href="/docs/permalinks/">Permalinks</a></li>
 
   
@@ -1205,7 +1201,7 @@ with public or secret gists:</p>
 </script>
 
   
-  <!-- Gauges (http://gaug.es/) -->
+  <!-- Gauges (http://get.gaug.es/) -->
   <script>
     var _gauges = _gauges || [];
     (function() {
@@ -1222,7 +1218,7 @@ with public or secret gists:</p>
 
 
 
-  <!-- Google Analytics (http://google.com/analytics) -->
+  <!-- Google Analytics (https://www.google.com/analytics) -->
   <script>
     !function(j,e,k,y,l,L){j.GoogleAnalyticsObject=y,j[y]||(j[y]=function(){
     (j[y].q=j[y].q||[]).push(arguments)}),j[y].l=+new Date,l=e.createElement(k),