site/docs/templates/index.html in jekyll-docs-3.5.2 vs site/docs/templates/index.html in jekyll-docs-3.6.0
- old
+ new
@@ -2,32 +2,32 @@
<html lang="en-US">
<head>
<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.5.2">
+ <meta name="generator" content="Jekyll v3.6.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">
<link rel="stylesheet" href="/css/screen.css">
<link rel="icon" type="image/x-icon" href="/favicon.ico">
- <!-- Begin Jekyll SEO tag v2.2.3 -->
+ <!-- Begin Jekyll SEO tag v2.3.0 -->
<title>Templates | Jekyll • Simple, blog-aware, static sites</title>
<meta property="og:title" content="Templates">
<meta property="og:locale" content="en_US">
-<meta name="description" content="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.">
-<meta property="og:description" content="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.">
+<meta name="description" content="Jekyll uses the Liquid templating language to process templates. All of the standard Liquid tags and filters are supported. To make common tasks easier, Jekyll even adds a few handy filters and tags of its own, all of which you can find on this page. Jekyll even lets you come up with your own tags via plugins.">
+<meta property="og:description" content="Jekyll uses the Liquid templating language to process templates. All of the standard Liquid tags and filters are supported. To make common tasks easier, Jekyll even adds a few handy filters and tags of its own, all of which you can find on this page. Jekyll even lets you come up with your own tags via plugins.">
<link rel="canonical" href="https://jekyllrb.com/docs/templates/">
<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-08-12T13:36:54-07:00">
+<meta property="article:published_time" content="2017-10-24T08:07:43-07:00">
<meta name="twitter:card" content="summary">
<meta name="twitter:site" content="@jekyllrb">
<meta name="google-site-verification" content="onQcXpAvtHBrUI5LlroHNE_FP0b2qvFyPq7VZw36iEY">
<script type="application/ld+json">
-{"@context":"http://schema.org","@type":"BlogPosting","headline":"Templates","datePublished":"2017-08-12T13:36:54-07:00","dateModified":"2017-08-12T13:36:54-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","url":"https://jekyllrb.com/img/logo-2x.png"}},"mainEntityOfPage":{"@type":"WebPage","@id":"https://jekyllrb.com/docs/templates/"},"url":"https://jekyllrb.com/docs/templates/"}</script>
+{"name":null,"description":"Jekyll uses the Liquid templating language to process templates. All of the standard Liquid tags and filters are supported. To make common tasks easier, Jekyll even adds a few handy filters and tags of its own, all of which you can find on this page. Jekyll even lets you come up with your own tags via plugins.","url":"https://jekyllrb.com/docs/templates/","headline":"Templates","dateModified":"2017-10-24T08:07:43-07:00","datePublished":"2017-10-24T08:07:43-07:00","sameAs":null,"@type":"BlogPosting","author":null,"image":null,"publisher":{"@type":"Organization","logo":{"@type":"ImageObject","url":"https://jekyllrb.com/img/logo-2x.png"}},"mainEntityOfPage":{"@type":"WebPage","@id":"https://jekyllrb.com/docs/templates/"},"@context":"http://schema.org"}</script>
<!-- End Jekyll SEO tag -->
<!--[if lt IE 9]>
<script src="/js/html5shiv.min.js"></script>
<script src="/js/respond.min.js"></script>
@@ -288,12 +288,13 @@
</div>
<h1>Templates</h1>
<p>Jekyll uses the <a href="https://shopify.github.io/liquid/">Liquid</a> templating language to
process templates. All of the standard Liquid <a href="https://shopify.github.io/liquid/tags/control-flow/">tags</a> and
<a href="https://shopify.github.io/liquid/filters/abs/">filters</a> are
-supported. Jekyll even adds a few handy filters and tags of its own to make
-common tasks easier.</p>
+supported. To make common tasks easier, Jekyll even adds a few handy filters
+and tags of its own, all of which you can find on this page. Jekyll even lets
+you come up with your own tags via plugins.</p>
<h2 id="filters">Filters</h2>
<div class="mobile-side-scroller">
<table>
@@ -709,18 +710,23 @@
</li>
</ul>
<h2 id="tags">Tags</h2>
+<ul>
+ <li><a href="#includes">Includes</a></li>
+ <li><a href="#code-snippet-highlighting">Code snippet highlighting</a></li>
+ <li><a href="#links">Linking to pages, collections and posts (the new and improved way)</a></li>
+ <li><a href="#linking-to-posts">Linking to posts (the old way)</a></li>
+</ul>
+
<h3 id="includes">Includes</h3>
<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>
+<div class="language-liquid highlighter-rouge"><div class="highlight"><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></div>
<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>For more advanced information on using includes, see <a href="../includes">Includes</a>.</p>
@@ -737,20 +743,18 @@
<code class="highlighter-rouge">pygments</code> in your site’s configuration file. Pygments supports <a href="http://pygments.org/languages/">over 100
languages</a></p>
<p>To render a code block with syntax highlighting, surround your code as follows:</p>
-<div class="language-liquid highlighter-rouge">
-<pre class="highlight"><code>
+<div class="language-liquid highlighter-rouge"><div class="highlight"><pre class="highlight"><code>
<span class="p">{%</span><span class="w"> </span><span class="nt">highlight</span><span class="w"> </span>ruby<span class="w"> </span><span class="p">%}</span>
def foo
puts 'foo'
end
<span class="p">{%</span><span class="w"> </span><span class="nt">endhighlight</span><span class="w"> </span><span class="p">%}</span>
-</code></pre>
-</div>
+</code></pre></div></div>
<p>The argument to the <code class="highlighter-rouge">highlight</code> tag (<code class="highlighter-rouge">ruby</code> in the example above) is the
language identifier. To find the appropriate identifier to use for the language
you want to highlight, look for the “short name” on the <a href="https://github.com/jayferd/rouge/wiki/List-of-supported-languages-and-lexers">Rouge
wiki</a>
@@ -761,20 +765,18 @@
<p>There is a second argument to <code class="highlighter-rouge">highlight</code> called <code class="highlighter-rouge">linenos</code> that is optional.
Including the <code class="highlighter-rouge">linenos</code> argument will force the highlighted code to include line
numbers. For instance, the following code block would include line numbers next
to each line:</p>
-<div class="language-liquid highlighter-rouge">
-<pre class="highlight"><code>
+<div class="language-liquid highlighter-rouge"><div class="highlight"><pre class="highlight"><code>
<span class="p">{%</span><span class="w"> </span><span class="nt">highlight</span><span class="w"> </span>ruby<span class="w"> </span>linenos<span class="w"> </span><span class="p">%}</span>
def foo
puts 'foo'
end
<span class="p">{%</span><span class="w"> </span><span class="nt">endhighlight</span><span class="w"> </span><span class="p">%}</span>
-</code></pre>
-</div>
+</code></pre></div></div>
<h4 id="stylesheets-for-syntax-highlighting">Stylesheets for syntax highlighting</h4>
<p>In order for the highlighting to show up, you’ll need to include a highlighting
stylesheet. For an example stylesheet you can look at
@@ -782,105 +784,71 @@
are the same styles as used by GitHub and you are free to use them for your own
site. If you use <code class="highlighter-rouge">linenos</code>, you might want to include an additional CSS class
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="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>
-
-<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>
-
-</code></pre>
-</div>
-
-<p>You may also optionally specify the filename in the gist to display:</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>
-
-</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>
-
<h2 id="links">Links</h2>
<h3 id="link">Linking to pages</h3>
<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>
+<div class="language-liquid highlighter-rouge"><div class="highlight"><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>
-</code></pre>
-</div>
+</code></pre></div></div>
<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>
+<div class="language-liquid highlighter-rouge"><div class="highlight"><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>)
-</code></pre>
-</div>
+</code></pre></div></div>
-<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>(Including <code class="highlighter-rouge">{{ site.baseurl }}</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>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 in <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>If you’re unsure of the path, add <code class="highlighter-rouge">{{ page.path }}</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>One major benefit of using the <code class="highlighter-rouge">link</code> or <code class="highlighter-rouge">post_url</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>
+<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">{% link mypage.html | append: "#section1" %} </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 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>
+<div class="language-liquid highlighter-rouge"><div class="highlight"><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>
-</code></pre>
-</div>
+</code></pre></div></div>
<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>
+<div class="language-liquid highlighter-rouge"><div class="highlight"><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>
-</code></pre>
-</div>
+</code></pre></div></div>
<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>
+<div class="language-liquid highlighter-rouge"><div class="highlight"><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>)
-</code></pre>
-</div>
+</code></pre></div></div>