site/docs/posts/index.html in jekyll-docs-3.9.0 vs site/docs/posts/index.html in jekyll-docs-4.0.0
- old
+ new
@@ -1,36 +1,39 @@
<!DOCTYPE HTML>
<html lang="en-US">
<head>
<meta charset="UTF-8">
<meta name="viewport" content="width=device-width,initial-scale=1">
- <meta name="generator" content="Jekyll v3.9.0">
+ <meta name="generator" content="Jekyll v4.0.0">
<link type="application/atom+xml" rel="alternate" href="https://jekyllrb.com/feed.xml" title="Jekyll • Simple, blog-aware, static sites" />
+ <link type="application/atom+xml" rel="alternate" href="/feed/release.xml" title="Jekyll releases posts" />
<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="preconnect" href="https://fonts.gstatic.com/" crossorigin>
- <link rel="stylesheet" href="https://fonts.googleapis.com/css?family=Lato:300,300italic,400,400italic,700,700italic,900">
- <link rel="stylesheet" href="https://cdn.jsdelivr.net/npm/docsearch.js@2/dist/cdn/docsearch.min.css" />
+ <link rel="preload" href="/fonts/lato-v14-latin-300.woff2" as="font" type="font/woff2" crossorigin />
+ <link rel="preload" href="/fonts/lato-v14-latin-700.woff2" as="font" type="font/woff2" crossorigin />
+ <link rel="preload" href="/css/screen.css" as="style">
<link rel="stylesheet" href="/css/screen.css">
<link rel="icon" type="image/x-icon" href="/favicon.ico">
<!-- Begin Jekyll SEO tag v2.6.1 -->
-<title>Writing posts | Jekyll • Simple, blog-aware, static sites</title>
-<meta name="generator" content="Jekyll v3.9.0" />
-<meta property="og:title" content="Writing posts" />
+<title>Posts | Jekyll • Simple, blog-aware, static sites</title>
+<meta name="generator" content="Jekyll v4.0.0" />
+<meta property="og:title" content="Posts" />
<meta property="og:locale" content="en_US" />
-<meta name="description" content="One of Jekyll’s best aspects is that it is “blog aware”. What does this mean, exactly? Well, simply put, it means that blogging is baked into Jekyll’s functionality. If you write articles and publish them online, you can publish and maintain a blog simply by managing a folder of text-files on your computer. Compared to the hassle of configuring and maintaining databases and web-based CMS systems, this will be a welcome change!" />
-<meta property="og:description" content="One of Jekyll’s best aspects is that it is “blog aware”. What does this mean, exactly? Well, simply put, it means that blogging is baked into Jekyll’s functionality. If you write articles and publish them online, you can publish and maintain a blog simply by managing a folder of text-files on your computer. Compared to the hassle of configuring and maintaining databases and web-based CMS systems, this will be a welcome change!" />
+<meta name="description" content="Blogging is baked into Jekyll. You write blog posts as text files and Jekyll provides everything you need to turn it into a blog." />
+<meta property="og:description" content="Blogging is baked into Jekyll. You write blog posts as text files and Jekyll provides everything you need to turn it into a blog." />
<link rel="canonical" href="https://jekyllrb.com/docs/posts/" />
<meta property="og:url" content="https://jekyllrb.com/docs/posts/" />
<meta property="og:site_name" content="Jekyll • Simple, blog-aware, static sites" />
+<meta property="og:image" content="https://jekyllrb.com/img/jekyll-og.png" />
<meta property="og:type" content="article" />
-<meta property="article:published_time" content="2020-08-05T11:55:36-07:00" />
-<meta name="twitter:card" content="summary" />
-<meta property="twitter:title" content="Writing posts" />
+<meta property="article:published_time" content="2019-09-11T07:30:27-07:00" />
+<meta name="twitter:card" content="summary_large_image" />
+<meta property="twitter:image" content="https://jekyllrb.com/img/jekyll-og.png" />
+<meta property="twitter:title" content="Posts" />
<meta name="twitter:site" content="@jekyllrb" />
<meta name="google-site-verification" content="onQcXpAvtHBrUI5LlroHNE_FP0b2qvFyPq7VZw36iEY" />
<script type="application/ld+json">
-{"url":"https://jekyllrb.com/docs/posts/","headline":"Writing posts","dateModified":"2020-08-05T11:55:36-07:00","datePublished":"2020-08-05T11:55:36-07:00","publisher":{"@type":"Organization","logo":{"@type":"ImageObject","url":"https://jekyllrb.com/img/logo-2x.png"}},"description":"One of Jekyll’s best aspects is that it is “blog aware”. What does this mean, exactly? Well, simply put, it means that blogging is baked into Jekyll’s functionality. If you write articles and publish them online, you can publish and maintain a blog simply by managing a folder of text-files on your computer. Compared to the hassle of configuring and maintaining databases and web-based CMS systems, this will be a welcome change!","mainEntityOfPage":{"@type":"WebPage","@id":"https://jekyllrb.com/docs/posts/"},"@type":"BlogPosting","@context":"https://schema.org"}</script>
+{"description":"Blogging is baked into Jekyll. You write blog posts as text files and Jekyll provides everything you need to turn it into a blog.","@type":"BlogPosting","mainEntityOfPage":{"@type":"WebPage","@id":"https://jekyllrb.com/docs/posts/"},"headline":"Posts","dateModified":"2019-09-11T07:30:27-07:00","url":"https://jekyllrb.com/docs/posts/","datePublished":"2019-09-11T07:30:27-07:00","image":"https://jekyllrb.com/img/jekyll-og.png","publisher":{"@type":"Organization","logo":{"@type":"ImageObject","url":"https://jekyllrb.com/img/logo-2x.png"}},"@context":"https://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>
@@ -49,54 +52,69 @@
</a>
</h1>
</div>
<nav class="main-nav hide-on-mobiles">
<ul>
- <li class="">
+
+ <li>
<a href="/">Home</a>
</li>
+
<li class="current">
- <a href="/docs/home/">Docs</a>
+ <a href="/docs/">Docs</a>
</li>
- <li class="">
- <a href="/news/">News</a>
+
+ <li>
+ <a href="/resources/">Resources</a>
</li>
- <li class="">
- <a href="/help/">Help</a>
+
+ <li>
+ <a href="/showcase/">Showcase</a>
</li>
+
+ <li>
+ <a href="/news/">News</a>
+ </li>
+
</ul>
</nav>
<div class="search hide-on-mobiles">
<input type="text" id="docsearch-input" placeholder="Search the docs…">
</div>
<div class="meta hide-on-mobiles">
<ul>
<li>
- <a href="https://github.com/jekyll/jekyll/releases/tag/v3.9.0">v3.9.0</a>
+ <a href="https://github.com/jekyll/jekyll/releases/tag/v4.0.0">v4.0.0</a>
</li>
<li>
<a href="https://github.com/jekyll/jekyll">GitHub</a>
</li>
</ul>
</div>
</div>
<nav class="mobile-nav show-on-mobiles">
<ul>
- <li class="">
- <a href="/">Home</a>
- </li>
- <li class="current">
- <a href="/docs/home/">Docs</a>
- </li>
- <li class="">
- <a href="/news/">News</a>
- </li>
- <li class="">
- <a href="/help/">Help</a>
- </li>
+
+ <li>
+ <a href="/">Home</a>
+ </li>
+
+ <li class="current">
+ <a href="/docs/">Docs</a>
+ </li>
+
+ <li>
+ <a href="/resources/">Resources</a>
+ </li>
+
+
+ <li>
+ <a href="/news/">News</a>
+ </li>
+
<li>
<a href="https://github.com/jekyll/jekyll">GitHub</a>
</li>
</ul>
@@ -111,729 +129,566 @@
<select onchange="if (this.value) window.location.href=this.value">
<option value="">Navigate the docs…</option>
<optgroup label="Getting Started">
-
-
- <option value="/docs/home/">Welcome</option>
-
-
-
- <option value="/docs/quickstart/">Quick-start guide</option>
-
-
-
- <option value="/docs/installation/">Installation</option>
-
-
-
- <option value="/docs/windows/">Jekyll on Windows</option>
-
-
-
- <option value="/docs/usage/">Basic Usage</option>
-
-
-
- <option value="/docs/structure/">Directory structure</option>
-
-
-
- <option value="/docs/configuration/">Configuration</option>
-
-
- </optgroup>
-
- <optgroup label="Your Content">
+
+ <option value="/docs/">
+ Quickstart
+ </option>
-
-
- <option value="/docs/frontmatter/">Front Matter</option>
-
-
-
- <option value="/docs/posts/">Writing posts</option>
-
-
-
- <option value="/docs/drafts/">Working with drafts</option>
-
-
-
- <option value="/docs/pages/">Creating pages</option>
-
-
-
- <option value="/docs/static-files/">Static Files</option>
-
-
-
- <option value="/docs/variables/">Variables</option>
-
-
-
- <option value="/docs/collections/">Collections</option>
-
-
-
- <option value="/docs/datafiles/">Data Files</option>
-
-
-
- <option value="/docs/assets/">Assets</option>
-
-
-
- <option value="/docs/migrations/">Blog migrations</option>
-
-
+
+ <option value="/docs/ruby-101/">
+ Ruby 101
+ </option>
+
+
+ <option value="/docs/installation/">
+ Installation
+ </option>
+
+
+ <option value="/docs/community/">
+ Community
+ </option>
+
+
+ <option value="/docs/step-by-step/01-setup/">
+ Step by Step Tutorial
+ </option>
+
</optgroup>
- <optgroup label="Customization">
+ <optgroup label="Build">
-
-
- <option value="/docs/templates/">Templates</option>
-
-
-
- <option value="/docs/includes/">Includes</option>
-
-
-
- <option value="/docs/permalinks/">Permalinks</option>
-
-
-
- <option value="/docs/pagination/">Pagination</option>
-
-
-
- <option value="/docs/plugins/">Plugins</option>
-
-
-
- <option value="/docs/themes/">Themes</option>
-
-
-
- <option value="/docs/extras/">Extras</option>
-
-
+
+ <option value="/docs/usage/">
+ Command Line Usage
+ </option>
+
+
+ <option value="/docs/configuration/">
+ Configuration
+ </option>
+
</optgroup>
- <optgroup label="Deployment">
+ <optgroup label="Content">
-
-
- <option value="/docs/github-pages/">GitHub Pages</option>
-
-
-
- <option value="/docs/deployment-methods/">Deployment methods</option>
-
-
-
- <option value="/docs/continuous-integration/">Continuous Integration</option>
-
-
+
+ <option value="/docs/pages/">
+ Pages
+ </option>
+
+
+ <option value="/docs/posts/">
+ Posts
+ </option>
+
+
+ <option value="/docs/front-matter/">
+ Front Matter
+ </option>
+
+
+ <option value="/docs/collections/">
+ Collections
+ </option>
+
+
+ <option value="/docs/datafiles/">
+ Data Files
+ </option>
+
+
+ <option value="/docs/assets/">
+ Assets
+ </option>
+
+
+ <option value="/docs/static-files/">
+ Static Files
+ </option>
+
</optgroup>
- <optgroup label="Miscellaneous">
+ <optgroup label="Site Structure">
-
-
- <option value="/docs/troubleshooting/">Troubleshooting</option>
-
-
-
- <option value="/docs/sites/">Sites using Jekyll</option>
-
-
-
- <option value="/docs/resources/">Resources</option>
-
-
-
- <option value="/docs/upgrading/0-to-2/">Upgrading from 0.x to 2.x</option>
-
-
-
- <option value="/docs/upgrading/2-to-3/">Upgrading from 2.x to 3.x</option>
-
-
+
+ <option value="/docs/structure/">
+ Directory Structure
+ </option>
+
+
+ <option value="/docs/liquid/">
+ Liquid
+ </option>
+
+
+ <option value="/docs/variables/">
+ Variables
+ </option>
+
+
+ <option value="/docs/includes/">
+ Includes
+ </option>
+
+
+ <option value="/docs/layouts/">
+ Layouts
+ </option>
+
+
+ <option value="/docs/permalinks/">
+ Permalinks
+ </option>
+
+
+ <option value="/docs/themes/">
+ Themes
+ </option>
+
+
+ <option value="/docs/pagination/">
+ Pagination
+ </option>
+
</optgroup>
- <optgroup label="Meta">
+ <optgroup label="Guides">
-
-
- <option value="/docs/contributing/">Contributing</option>
-
-
-
- <option value="/docs/maintaining/">Maintaining Jekyll</option>
-
-
-
- <option value="/docs/conduct/">Code of Conduct</option>
-
-
-
- <option value="/docs/history/">History</option>
-
-
+
+ <option value="/docs/plugins/">
+ Plugins
+ </option>
+
+
+ <option value="/docs/migrations/">
+ Blog Migrations
+ </option>
+
+
+ <option value="/docs/upgrading/">
+ Upgrading
+ </option>
+
+
+ <option value="/docs/deployment/">
+ Deployment
+ </option>
+
</optgroup>
</select>
</div>
<div class="unit four-fifths">
<article>
<div class="improve right hide-on-mobiles">
- <a href="https://github.com/jekyll/jekyll/edit/master/docs/_docs/posts.md"><i class="fa fa-pencil"></i> Improve this page</a>
+ <a data-proofer-ignore href="https://github.com/jekyll/jekyll/edit/master/docs/_docs/posts.md"><i class="fa fa-pencil"></i> Improve this page</a>
</div>
- <h1>Writing posts</h1>
- <p>One of Jekyll’s best aspects is that it is “blog aware”. What does this mean,
-exactly? Well, simply put, it means that blogging is baked into Jekyll’s
-functionality. If you write articles and publish them online, you can publish
-and maintain a blog simply by managing a folder of text-files on your computer.
-Compared to the hassle of configuring and maintaining databases and web-based
-CMS systems, this will be a welcome change!</p>
+ <h1>Posts</h1>
+ <p>Blogging is baked into Jekyll. You write blog posts as text files and Jekyll
+provides everything you need to turn it into a blog.</p>
<h2 id="the-posts-folder">The Posts Folder</h2>
-<p>As explained on the <a href="../structure/">directory structure</a> page, the <code class="language-plaintext highlighter-rouge">_posts</code>
-folder is where your blog posts will live. These files are generally
-<a href="https://daringfireball.net/projects/markdown/">Markdown</a> or HTML, but can
-be other formats with the proper converter installed.
-All posts must have <a href="../frontmatter/">YAML Front Matter</a>, and they will be
-converted from their source format into an HTML page that is part of your
-static site.</p>
+<p>The <code class="highlighter-rouge">_posts</code> folder is where your blog posts live. You typically write posts
+in <a href="https://daringfireball.net/projects/markdown/">Markdown</a>, HTML is
+also supported.</p>
-<h3 id="creating-post-files">Creating Post Files</h3>
+<h2 id="creating-posts">Creating Posts</h2>
-<p>To create a new post, all you need to do is create a file in the <code class="language-plaintext highlighter-rouge">_posts</code>
-directory. How you name files in this folder is important. Jekyll requires blog
-post files to be named according to the following format:</p>
+<p>To create a post, add a file to your <code class="highlighter-rouge">_posts</code> directory with the following
+format:</p>
-<div class="language-plaintext highlighter-rouge"><div class="highlight"><pre class="highlight"><code>YEAR-MONTH-DAY-title.MARKUP
+<div class="highlighter-rouge"><div class="highlight"><pre class="highlight"><code>YEAR-MONTH-DAY-title.MARKUP
</code></pre></div></div>
-<p>Where <code class="language-plaintext highlighter-rouge">YEAR</code> is a four-digit number, <code class="language-plaintext highlighter-rouge">MONTH</code> and <code class="language-plaintext highlighter-rouge">DAY</code> are both two-digit
-numbers, and <code class="language-plaintext highlighter-rouge">MARKUP</code> is the file extension representing the format used in the
+<p>Where <code class="highlighter-rouge">YEAR</code> is a four-digit number, <code class="highlighter-rouge">MONTH</code> and <code class="highlighter-rouge">DAY</code> are both two-digit
+numbers, and <code class="highlighter-rouge">MARKUP</code> is the file extension representing the format used in the
file. For example, the following are examples of valid post filenames:</p>
-<div class="language-plaintext highlighter-rouge"><div class="highlight"><pre class="highlight"><code>2011-12-31-new-years-eve-is-awesome.md
+<div class="highlighter-rouge"><div class="highlight"><pre class="highlight"><code>2011-12-31-new-years-eve-is-awesome.md
2012-09-12-how-to-write-a-blog.md
</code></pre></div></div>
+<p>All blog post files must begin with <a href="/docs/front-matter/">front matter</a> which is
+typically used to set a <a href="/docs/layouts/">layout</a> or other meta data. For a simple
+example this can just be empty:</p>
+
+<div class="language-markdown highlighter-rouge"><div class="highlight"><pre class="highlight"><code><span class="nn">---</span>
+<span class="na">layout</span><span class="pi">:</span> <span class="s">post</span>
+<span class="na">title</span><span class="pi">:</span> <span class="s2">"</span><span class="s">Welcome</span><span class="nv"> </span><span class="s">to</span><span class="nv"> </span><span class="s">Jekyll!"</span>
+<span class="nn">---</span>
+
+<span class="gh"># Welcome</span>
+
+<span class="gs">**Hello world**</span>, this is my first Jekyll blog post.
+
+I hope you like it!
+</code></pre></div></div>
+
<div class="note">
<h5>ProTip™: Link to other posts</h5>
<p>
- Use the <a href="../templates/#linking-to-posts"><code>post_url</code></a>
+ Use the <a href="/docs/liquid/tags/#linking-to-posts"><code>post_url</code></a>
tag to link to other posts without having to worry about the URLs
breaking when the site permalink style changes.
</p>
</div>
-<h3 id="content-formats">Content Formats</h3>
-
-<p>All blog post files must begin with <a href="../frontmatter/">YAML Front Matter</a>. After
-that, it’s simply a matter of deciding which format you prefer. Jekyll supports
-<a href="https://daringfireball.net/projects/markdown/">Markdown</a> out of the box,
-and has <a href="/docs/plugins/#converters-1">myriad extensions for other formats as well</a>,
-including the popular <a href="http://redcloth.org/textile">Textile</a> format. These
-formats each have their own way of marking up different types of content
-within a post, so you should familiarize yourself with these formats and
-decide which one best suits your needs.</p>
-
<div class="note info">
<h5>Be aware of character sets</h5>
<p>
Content processors can modify certain characters to make them look nicer.
For example, the <code>smart</code> extension in Redcarpet converts standard,
ASCII quotation characters to curly, Unicode ones. In order for the browser
to display those characters properly, define the charset meta value by
- including <code><meta charset="utf-8"></code> in the
+ including <code><meta charset="utf-8"></code> in the
<code><head></code> of your layout.
</p>
</div>
<h2 id="including-images-and-resources">Including images and resources</h2>
-<p>Chances are, at some point, you’ll want to include images, downloads, or other
-digital assets along with your text content. While the syntax for linking to
-these resources differs between Markdown and Textile, the problem of working
-out where to store these files in your site is something everyone will face.</p>
+<p>At some point, you’ll want to include images, downloads, or other
+digital assets along with your text content. One common solution is to create
+a folder in the root of the project directory called something like <code class="highlighter-rouge">assets</code>,
+into which any images, files or other resources are placed. Then, from within
+any post, they can be linked to using the site’s root as the path for the asset
+to include. The best way to do this depends on the way your site’s (sub)domain
+and path are configured, but here are some simple examples in Markdown:</p>
-<p>There are a number of ways to include digital assets in Jekyll.
-One common solution is to create a folder in the root of the project directory
-called something like <code class="language-plaintext highlighter-rouge">assets</code>, into which any images, files
-or other resources are placed. Then, from within any post, they can be linked
-to using the site’s root as the path for the asset to include. Again, this will
-depend on the way your site’s (sub)domain and path are configured, but here are
-some examples in Markdown of how you could do this using the <code class="language-plaintext highlighter-rouge">absolute_url</code>
-filter in a post.</p>
-
<p>Including an image asset in a post:</p>
<div class="language-markdown highlighter-rouge"><div class="highlight"><pre class="highlight"><code>... which is shown in the screenshot below:
-<span class="p">![</span><span class="nv">My helpful screenshot</span><span class="p">](</span><span class="sx">{{</span> <span class="nn">"/assets/screenshot.jpg"</span> | absolute_url }})
+<span class="p">![</span><span class="nv">My helpful screenshot</span><span class="p">](</span><span class="sx">/assets/screenshot.jpg</span><span class="p">)</span>
</code></pre></div></div>
<p>Linking to a PDF for readers to download:</p>
-<div class="language-markdown highlighter-rouge"><div class="highlight"><pre class="highlight"><code>... you can <span class="p">[</span><span class="nv">get the PDF</span><span class="p">](</span><span class="sx">{{</span> <span class="nn">"/assets/mydoc.pdf"</span> | absolute_url }}) directly.
+<div class="language-markdown highlighter-rouge"><div class="highlight"><pre class="highlight"><code>... you can <span class="p">[</span><span class="nv">get the PDF</span><span class="p">](</span><span class="sx">/assets/mydoc.pdf</span><span class="p">)</span> directly.
</code></pre></div></div>
-<div class="info">
-
-</div>
-
-<h2 id="a-typical-post">A typical post</h2>
-
-<p>Jekyll can handle many different iterations of the idea you might associate with a “post,” however a standard blog style post, including a Title, Layout, Publishing Date, and Categories might look like this:</p>
-
-<div class="language-markdown highlighter-rouge"><div class="highlight"><pre class="highlight"><code><span class="nn">---</span>
-<span class="na">layout</span><span class="pi">:</span> <span class="s">post</span>
-<span class="na">title</span><span class="pi">:</span> <span class="s2">"</span><span class="s">Welcome</span><span class="nv"> </span><span class="s">to</span><span class="nv"> </span><span class="s">Jekyll!"</span>
-<span class="na">date</span><span class="pi">:</span> <span class="s">2015-11-17 16:16:01 -0600</span>
-<span class="na">categories</span><span class="pi">:</span> <span class="s">jekyll update</span>
-<span class="nn">---</span>
-
-You’ll find this post in your <span class="sb">`_posts`</span> directory. Go ahead and edit it and re-build the site to see your changes. You can rebuild the site in many different ways, but the most common way is to run <span class="sb">`bundle exec jekyll serve`</span>, which launches a web server and auto-regenerates your site when a file is updated.
-
-To add new posts, simply add a file in the <span class="sb">`_posts`</span> directory that follows the convention <span class="sb">`YYYY-MM-DD-name-of-post.ext`</span> and includes the necessary front matter. Take a look at the source for this post to get an idea about how it works.
-</code></pre></div></div>
-
-<p>Everything in between the first and second <code class="language-plaintext highlighter-rouge">---</code> are part of the YAML Front Matter, and everything after the second <code class="language-plaintext highlighter-rouge">---</code> will be rendered with Markdown and show up as “Content”.</p>
-
<h2 id="displaying-an-index-of-posts">Displaying an index of posts</h2>
-<p>It’s all well and good to have posts in a folder, but a blog is no use unless
-you have a list of posts somewhere. Creating an index of posts on another page
-(or in a <a href="../templates/">template</a>) is easy, thanks to the <a href="https://docs.shopify.com/themes/liquid/basics">Liquid template
-language</a> and its tags. Here’s a
-basic example of how to create a list of links to your blog posts:</p>
+<p>Creating an index of posts on another page should be easy thanks to
+<a href="https://docs.shopify.com/themes/liquid/basics">Liquid</a> and its tags. Here’s a
+simple example of how to create a list of links to your blog posts:</p>
<div class="language-html highlighter-rouge"><div class="highlight"><pre class="highlight"><code><span class="nt"><ul></span>
{% for post in site.posts %}
<span class="nt"><li></span>
<span class="nt"><a</span> <span class="na">href=</span><span class="s">"{{ post.url }}"</span><span class="nt">></span>{{ post.title }}<span class="nt"></a></span>
<span class="nt"></li></span>
{% endfor %}
<span class="nt"></ul></span>
</code></pre></div></div>
-<p>Of course, you have full control over how (and where) you display your posts,
-and how you structure your site. You should read more about <a href="../templates/">how templates
+<p>You have full control over how (and where) you display your posts,
+and how you structure your site. You should read more about <a href="/docs/templates/">how templates
work</a> with Jekyll if you want to know more.</p>
-<p>Note that the <code class="language-plaintext highlighter-rouge">post</code> variable only exists inside the <code class="language-plaintext highlighter-rouge">for</code> loop above. If
+<p>Note that the <code class="highlighter-rouge">post</code> variable only exists inside the <code class="highlighter-rouge">for</code> loop above. If
you wish to access the currently-rendering page/posts’s variables (the
-variables of the post/page that has the <code class="language-plaintext highlighter-rouge">for</code> loop in it), use the <code class="language-plaintext highlighter-rouge">page</code>
+variables of the post/page that has the <code class="highlighter-rouge">for</code> loop in it), use the <code class="highlighter-rouge">page</code>
variable instead.</p>
-<h2 id="displaying-post-categories-or-tags">Displaying post categories or tags</h2>
+<h2 id="categories-and-tags">Categories and Tags</h2>
-<p>Hey, that’s pretty neat, but what about showing just some of your posts that are
-related to each other? For that you can use any of the <a href="https://jekyllrb.com/docs/frontmatter/">variables definable in
-Front Matter</a>. In the “typical post”
-section you can see how to define categories. Simply add the categories to your
-Front Matter as a <a href="https://en.wikipedia.org/wiki/YAML#Basic_components">yaml
-list</a>.</p>
+<p>Jekyll has first class support for categories and tags in blog posts. The difference
+between categories and tags is a category can be part of the URL for a post
+whereas a tag cannot.</p>
-<p>Now that your posts have a category or multiple categories, you can make a page
-or a template displaying just the posts in those categories you specify. Here’s
-a basic example of how to create a list of posts from a specific category.</p>
+<p>To use these, first set your categories and tags in front matter:</p>
-<p>First, in the <code class="language-plaintext highlighter-rouge">_layouts</code> directory create a new file called <code class="language-plaintext highlighter-rouge">category.html</code> - in
-that file put (at least) the following:</p>
+<div class="language-yaml highlighter-rouge"><div class="highlight"><pre class="highlight"><code><span class="nn">---</span>
+<span class="na">layout</span><span class="pi">:</span> <span class="s">post</span>
+<span class="na">title</span><span class="pi">:</span> <span class="s">A Trip</span>
+<span class="na">categories</span><span class="pi">:</span> <span class="pi">[</span><span class="nv">blog</span><span class="pi">,</span> <span class="nv">travel</span><span class="pi">]</span>
+<span class="na">tags</span><span class="pi">:</span> <span class="pi">[</span><span class="nv">hot</span><span class="pi">,</span> <span class="nv">summer</span><span class="pi">]</span>
+<span class="nn">---</span>
+</code></pre></div></div>
-<div class="language-liquid highlighter-rouge"><div class="highlight"><pre class="highlight"><code>---
-layout: page
----
+<p>Jekyll makes the categories available to us at <code class="highlighter-rouge">site.categories</code>. Iterating over
+<code class="highlighter-rouge">site.categories</code> on a page gives us another array with two items, the first
+item is the name of the category and the second item is an array of posts in that
+category.</p>
-<span class="p">{%</span><span class="w"> </span><span class="nt">for</span><span class="w"> </span><span class="nv">post</span><span class="w"> </span><span class="nt">in</span><span class="w"> </span><span class="nv">site.categories[page.category]</span><span class="w"> </span><span class="p">%}</span>
- <a href="<span class="p">{{</span><span class="w"> </span><span class="nv">post</span><span class="p">.</span><span class="nv">url</span><span class="w"> </span><span class="p">|</span><span class="w"> </span><span class="nf">absolute_url</span><span class="w"> </span><span class="p">}}</span>">
- <span class="p">{{</span><span class="w"> </span><span class="nv">post</span><span class="p">.</span><span class="nv">title</span><span class="w"> </span><span class="p">}}</span>
- </a>
+<div class="language-liquid highlighter-rouge"><div class="highlight"><pre class="highlight"><code><span class="p">{%</span><span class="w"> </span><span class="nt">for</span><span class="w"> </span><span class="nv">category</span><span class="w"> </span><span class="kr">in</span><span class="w"> </span><span class="nv">site.categories</span><span class="w"> </span><span class="p">%}</span>
+ <h3><span class="p">{{</span><span class="w"> </span><span class="nv">category</span><span class="p">[</span><span class="mi">0</span><span class="p">]</span><span class="w"> </span><span class="p">}}</span></h3>
+ <ul>
+ <span class="p">{%</span><span class="w"> </span><span class="nt">for</span><span class="w"> </span><span class="nv">post</span><span class="w"> </span><span class="kr">in</span><span class="w"> </span><span class="nv">category[1]</span><span class="w"> </span><span class="p">%}</span>
+ <li><a href="<span class="p">{{</span><span class="w"> </span><span class="nv">post</span><span class="p">.</span><span class="nv">url</span><span class="w"> </span><span class="p">}}</span>"><span class="p">{{</span><span class="w"> </span><span class="nv">post</span><span class="p">.</span><span class="nv">title</span><span class="w"> </span><span class="p">}}</span></a></li>
+ <span class="p">{%</span><span class="w"> </span><span class="nt">endfor</span><span class="w"> </span><span class="p">%}</span>
+ </ul>
<span class="p">{%</span><span class="w"> </span><span class="nt">endfor</span><span class="w"> </span><span class="p">%}</span>
</code></pre></div></div>
-<p>Next, in the root directory of your Jekyll install, create a new directory
-called <code class="language-plaintext highlighter-rouge">category</code> and then create a file for each category you want to list. For
-example, if you have a category <code class="language-plaintext highlighter-rouge">blog</code> then create a file in the new directory
-called <code class="language-plaintext highlighter-rouge">blog.html</code> with at least</p>
+<p>For tags it’s exactly the same except the variable is <code class="highlighter-rouge">site.tags</code>.</p>
-<div class="language-yaml highlighter-rouge"><div class="highlight"><pre class="highlight"><code><span class="nn">---</span>
-<span class="na">layout</span><span class="pi">:</span> <span class="s">category</span>
-<span class="na">title</span><span class="pi">:</span> <span class="s">Blog</span>
-<span class="na">category</span><span class="pi">:</span> <span class="s">blog</span>
-<span class="nn">---</span>
-</code></pre></div></div>
+<h2 id="post-excerpts">Post excerpts</h2>
-<p>In this case, the listing pages will be accessible at <code class="language-plaintext highlighter-rouge">{baseurl}/category/blog.html</code></p>
+<p>You can access a snippet of a posts’s content by using <code class="highlighter-rouge">excerpt</code> variable on a
+post. By default this is the first paragraph of content in the post, however it
+can be customized by setting a <code class="highlighter-rouge">excerpt_separator</code> variable in front matter or
+<code class="highlighter-rouge">_config.yml</code>.</p>
-<p>Although categories and tags are very similar, they are used to group posts,
-there are a few differences between them. Categories and sub-categories create
-hierarchies that, by default, are reflected in the directory structure of your
-site. A post with the following header</p>
<div class="language-yaml highlighter-rouge"><div class="highlight"><pre class="highlight"><code><span class="nn">---</span>
-<span class="na">layout</span><span class="pi">:</span> <span class="s">post</span>
-<span class="na">title</span><span class="pi">:</span> <span class="s">A Trip</span>
-<span class="na">category</span><span class="pi">:</span> <span class="pi">[</span> <span class="nv">blog</span><span class="pi">,</span> <span class="nv">travel</span> <span class="pi">]</span>
+<span class="na">excerpt_separator</span><span class="pi">:</span> <span class="s"><!--more--></span>
<span class="nn">---</span>
-</code></pre></div></div>
-<p>will be accessible at <code class="language-plaintext highlighter-rouge">{baseurl}/blog/travel/year/month/day/A-Trip.html</code>. On
-the other hand, a tagged post</p>
-<div class="language-yaml highlighter-rouge"><div class="highlight"><pre class="highlight"><code><span class="nn">---</span>
-<span class="na">layout</span><span class="pi">:</span> <span class="s">post</span>
-<span class="na">title</span><span class="pi">:</span> <span class="s">A Trip</span>
-<span class="na">tags</span><span class="pi">:</span> <span class="pi">[</span> <span class="nv">blog</span><span class="pi">,</span> <span class="nv">travel</span> <span class="pi">]</span>
-<span class="nn">---</span>
-</code></pre></div></div>
-<p>will be saved as <code class="language-plaintext highlighter-rouge">{baseurl}/year/month/day/A-Trip.html</code>. It is up to you to
-create <code class="language-plaintext highlighter-rouge">{baseurl}/tag/blog.html</code> and <code class="language-plaintext highlighter-rouge">{baseurl}/tag/travel.html</code> the same way as
-described above for categories.</p>
-<p>While this example is done with tags and categories, you can easily extend your
-lists to filter by any other variable created with extensions.</p>
+<span class="s">Excerpt with multiple paragraphs</span>
-<h2 id="post-excerpts">Post excerpts</h2>
+<span class="s">Here's another paragraph in the excerpt.</span>
+<span class="s"><!--more--></span>
+<span class="s">Out-of-excerpt</span>
+</code></pre></div></div>
-<p>Each post automatically takes the first block of text, from the beginning of
-the content to the first occurrence of <code class="language-plaintext highlighter-rouge">excerpt_separator</code>, and sets it in the
-post’s data hash.
-Take the above example of an index of posts. Perhaps you want to include
-a little hint about the post’s content by adding the first paragraph of each of
-your posts:</p>
+<p>Here’s an example of outputting a list of blog posts with an excerpt:</p>
<div class="language-liquid highlighter-rouge"><div class="highlight"><pre class="highlight"><code><ul>
- <span class="p">{%</span><span class="w"> </span><span class="nt">for</span><span class="w"> </span><span class="nv">post</span><span class="w"> </span><span class="nt">in</span><span class="w"> </span><span class="nv">site.posts</span><span class="w"> </span><span class="p">%}</span>
+ <span class="p">{%</span><span class="w"> </span><span class="nt">for</span><span class="w"> </span><span class="nv">post</span><span class="w"> </span><span class="kr">in</span><span class="w"> </span><span class="nv">site.posts</span><span class="w"> </span><span class="p">%}</span>
<li>
<a href="<span class="p">{{</span><span class="w"> </span><span class="nv">post</span><span class="p">.</span><span class="nv">url</span><span class="w"> </span><span class="p">}}</span>"><span class="p">{{</span><span class="w"> </span><span class="nv">post</span><span class="p">.</span><span class="nv">title</span><span class="w"> </span><span class="p">}}</span></a>
<span class="p">{{</span><span class="w"> </span><span class="nv">post</span><span class="p">.</span><span class="nv">excerpt</span><span class="w"> </span><span class="p">}}</span>
</li>
<span class="p">{%</span><span class="w"> </span><span class="nt">endfor</span><span class="w"> </span><span class="p">%}</span>
</ul>
</code></pre></div></div>
-<p>Because Jekyll grabs the first paragraph you will not need to wrap the excerpt
-in <code class="language-plaintext highlighter-rouge">p</code> tags, which is already done for you. These tags can be removed with the
-following if you’d prefer:</p>
+<h2 id="drafts">Drafts</h2>
-<div class="language-liquid highlighter-rouge"><div class="highlight"><pre class="highlight"><code><span class="p">{{</span><span class="w"> </span><span class="nv">post</span><span class="p">.</span><span class="nv">excerpt</span><span class="w"> </span><span class="p">|</span><span class="w"> </span><span class="nf">remove</span><span class="p">:</span><span class="w"> </span><span class="s1">'<p>'</span><span class="w"> </span><span class="p">|</span><span class="w"> </span><span class="nf">remove</span><span class="p">:</span><span class="w"> </span><span class="s1">'</p>'</span><span class="w"> </span><span class="p">}}</span>
-</code></pre></div></div>
+<p>Drafts are posts without a date in the filename. They’re posts you’re still
+working on and don’t want to publish yet. To get up and running with drafts,
+create a <code class="highlighter-rouge">_drafts</code> folder in your site’s root and create your first draft:</p>
-<p>If you don’t like the automatically-generated post excerpt, it can be
-explicitly overridden by adding an <code class="language-plaintext highlighter-rouge">excerpt</code> value to your post’s YAML
-Front Matter. Alternatively, you can choose to define a custom
-<code class="language-plaintext highlighter-rouge">excerpt_separator</code> in the post’s YAML front matter:</p>
-
-<div class="language-yaml highlighter-rouge"><div class="highlight"><pre class="highlight"><code><span class="nn">---</span>
-<span class="na">excerpt_separator</span><span class="pi">:</span> <span class="s"><!--more--></span>
-<span class="nn">---</span>
-
-<span class="s">Excerpt</span>
-<span class="s"><!--more--></span>
-<span class="s">Out-of-excerpt</span>
+<div class="language-text highlighter-rouge"><div class="highlight"><pre class="highlight"><code>|-- _drafts/
+| |-- a-draft-post.md
</code></pre></div></div>
-<p>You can also set the <code class="language-plaintext highlighter-rouge">excerpt_separator</code> globally in your <code class="language-plaintext highlighter-rouge">_config.yml</code>
-configuration file.</p>
+<p>To preview your site with drafts, run <code class="highlighter-rouge">jekyll serve</code> or <code class="highlighter-rouge">jekyll build</code>
+with the <code class="highlighter-rouge">--drafts</code> switch. Each will be assigned the value modification time
+of the draft file for its date, and thus you will see currently edited drafts
+as the latest posts.</p>
-<p>Completely disable excerpts by setting your <code class="language-plaintext highlighter-rouge">excerpt_separator</code> to <code class="language-plaintext highlighter-rouge">""</code>.</p>
+ </article>
+ </div>
-<p>Also, as with any output generated by Liquid tags, you can pass the
-<code class="language-plaintext highlighter-rouge">| strip_html</code> filter to remove any html tags in the output. This is
-particularly helpful if you wish to output a post excerpt as a
-<code class="language-plaintext highlighter-rouge">meta="description"</code> tag within the post <code class="language-plaintext highlighter-rouge">head</code>, or anywhere else having
-html tags along with the content is not desirable.</p>
-
-<h2 id="highlighting-code-snippets">Highlighting code snippets</h2>
-
-<p>Jekyll also has built-in support for syntax highlighting of code snippets using
-either Pygments or Rouge, and including a code snippet in any post is easy.
-Just use the dedicated Liquid tag as follows:</p>
-
-<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 show
- @widget = Widget(params[:id])
- respond_to do |format|
- format.html # show.html.erb
- format.json { render json: @widget }
- end
-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></div>
-
-<p>And the output will look like this:</p>
-
-<div class="language-ruby highlighter-rouge"><div class="highlight"><pre class="highlight"><code><span class="k">def</span> <span class="nf">show</span>
- <span class="vi">@widget</span> <span class="o">=</span> <span class="no">Widget</span><span class="p">(</span><span class="n">params</span><span class="p">[</span><span class="ss">:id</span><span class="p">])</span>
- <span class="n">respond_to</span> <span class="k">do</span> <span class="o">|</span><span class="nb">format</span><span class="o">|</span>
- <span class="nb">format</span><span class="p">.</span><span class="nf">html</span> <span class="c1"># show.html.erb</span>
- <span class="nb">format</span><span class="p">.</span><span class="nf">json</span> <span class="p">{</span> <span class="n">render</span> <span class="ss">json: </span><span class="vi">@widget</span> <span class="p">}</span>
- <span class="k">end</span>
-<span class="k">end</span>
-</code></pre></div></div>
-
-<div class="note">
- <h5>ProTip™: Show line numbers</h5>
- <p>
- You can make code snippets include line-numbers by adding the word
- <code>linenos</code> to the end of the opening highlight tag like this:
- <code>{% highlight ruby linenos %}</code>.
- </p>
-</div>
-
-<p>These basics should be enough to get you started writing your first posts. When
-you’re ready to dig into what else is possible, you might be interested in
-doing things like <a href="../permalinks/">customizing post permalinks</a> or
-using <a href="../variables/">custom variables</a> in your posts and elsewhere on your
-site.</p>
-
+ <div class="unit one-fifth hide-on-mobiles">
+ <aside>
+
+ <h4>Getting Started</h4>
+ <ul>
+
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
- <div class="section-nav">
- <div class="left align-right">
+ <li>
+ <a href="/docs/">
+ Quickstart
+ </a>
+ </li>
+
-
-
- <a href="/docs/frontmatter/" class="prev">Back</a>
+ <li>
+ <a href="/docs/ruby-101/">
+ Ruby 101
+ </a>
+ </li>
+
- </div>
- <div class="right align-left">
+ <li>
+ <a href="/docs/installation/">
+ Installation
+ </a>
+ </li>
+
-
-
- <a href="/docs/drafts/" class="next">Next</a>
+ <li>
+ <a href="/docs/community/">
+ Community
+ </a>
+ </li>
+
- </div>
- </div>
- <div class="clear"></div>
+ <li>
+ <a href="/docs/step-by-step/01-setup/">
+ Step by Step Tutorial
+ </a>
+ </li>
+
+ </ul>
- </article>
- </div>
-
- <div class="unit one-fifth hide-on-mobiles">
- <aside>
+ <h4>Build</h4>
+ <ul>
+
+
+ <li>
+ <a href="/docs/usage/">
+ Command Line Usage
+ </a>
+ </li>
+
+
+ <li>
+ <a href="/docs/configuration/">
+ Configuration
+ </a>
+ </li>
+
+ </ul>
- <h4>Getting Started</h4>
- <ul>
-
-
-
- <li class=""><a href="/docs/home/">Welcome</a></li>
-
-
-
- <li class=""><a href="/docs/quickstart/">Quick-start guide</a></li>
-
-
-
- <li class=""><a href="/docs/installation/">Installation</a></li>
-
-
-
- <li class=""><a href="/docs/windows/">Jekyll on Windows</a></li>
-
-
-
- <li class=""><a href="/docs/usage/">Basic Usage</a></li>
-
-
-
- <li class=""><a href="/docs/structure/">Directory structure</a></li>
-
-
-
- <li class=""><a href="/docs/configuration/">Configuration</a></li>
-
-</ul>
-
+ <h4>Content</h4>
+ <ul>
+
+
+ <li>
+ <a href="/docs/pages/">
+ Pages
+ </a>
+ </li>
+
+
+ <li class="current">
+ <a href="/docs/posts/">
+ Posts
+ </a>
+ </li>
+
+
+ <li>
+ <a href="/docs/front-matter/">
+ Front Matter
+ </a>
+ </li>
+
+
+ <li>
+ <a href="/docs/collections/">
+ Collections
+ </a>
+ </li>
+
+
+ <li>
+ <a href="/docs/datafiles/">
+ Data Files
+ </a>
+ </li>
+
+
+ <li>
+ <a href="/docs/assets/">
+ Assets
+ </a>
+ </li>
+
+
+ <li>
+ <a href="/docs/static-files/">
+ Static Files
+ </a>
+ </li>
+
+ </ul>
- <h4>Your Content</h4>
- <ul>
-
-
-
- <li class=""><a href="/docs/frontmatter/">Front Matter</a></li>
-
-
-
- <li class="current"><a href="/docs/posts/">Writing posts</a></li>
-
-
-
- <li class=""><a href="/docs/drafts/">Working with drafts</a></li>
-
-
-
- <li class=""><a href="/docs/pages/">Creating pages</a></li>
-
-
-
- <li class=""><a href="/docs/static-files/">Static Files</a></li>
-
-
-
- <li class=""><a href="/docs/variables/">Variables</a></li>
-
-
-
- <li class=""><a href="/docs/collections/">Collections</a></li>
-
-
-
- <li class=""><a href="/docs/datafiles/">Data Files</a></li>
-
-
-
- <li class=""><a href="/docs/assets/">Assets</a></li>
-
-
-
- <li class=""><a href="/docs/migrations/">Blog migrations</a></li>
-
-</ul>
-
+ <h4>Site Structure</h4>
+ <ul>
+
+
+ <li>
+ <a href="/docs/structure/">
+ Directory Structure
+ </a>
+ </li>
+
+
+ <li>
+ <a href="/docs/liquid/">
+ Liquid
+ </a>
+ </li>
+
+
+ <li>
+ <a href="/docs/variables/">
+ Variables
+ </a>
+ </li>
+
+
+ <li>
+ <a href="/docs/includes/">
+ Includes
+ </a>
+ </li>
+
+
+ <li>
+ <a href="/docs/layouts/">
+ Layouts
+ </a>
+ </li>
+
+
+ <li>
+ <a href="/docs/permalinks/">
+ Permalinks
+ </a>
+ </li>
+
+
+ <li>
+ <a href="/docs/themes/">
+ Themes
+ </a>
+ </li>
+
+
+ <li>
+ <a href="/docs/pagination/">
+ Pagination
+ </a>
+ </li>
+
+ </ul>
- <h4>Customization</h4>
- <ul>
-
-
-
- <li class=""><a href="/docs/templates/">Templates</a></li>
-
-
-
- <li class=""><a href="/docs/includes/">Includes</a></li>
-
-
-
- <li class=""><a href="/docs/permalinks/">Permalinks</a></li>
-
-
-
- <li class=""><a href="/docs/pagination/">Pagination</a></li>
-
-
-
- <li class=""><a href="/docs/plugins/">Plugins</a></li>
-
-
-
- <li class=""><a href="/docs/themes/">Themes</a></li>
-
-
-
- <li class=""><a href="/docs/extras/">Extras</a></li>
-
-</ul>
-
+ <h4>Guides</h4>
+ <ul>
+
+
+ <li>
+ <a href="/docs/plugins/">
+ Plugins
+ </a>
+ </li>
+
+
+ <li>
+ <a href="/docs/migrations/">
+ Blog Migrations
+ </a>
+ </li>
+
+
+ <li>
+ <a href="/docs/upgrading/">
+ Upgrading
+ </a>
+ </li>
+
+
+ <li>
+ <a href="/docs/deployment/">
+ Deployment
+ </a>
+ </li>
+
+ </ul>
- <h4>Deployment</h4>
- <ul>
-
-
-
- <li class=""><a href="/docs/github-pages/">GitHub Pages</a></li>
-
-
-
- <li class=""><a href="/docs/deployment-methods/">Deployment methods</a></li>
-
-
-
- <li class=""><a href="/docs/continuous-integration/">Continuous Integration</a></li>
-
-</ul>
-
-
- <h4>Miscellaneous</h4>
- <ul>
-
-
-
- <li class=""><a href="/docs/troubleshooting/">Troubleshooting</a></li>
-
-
-
- <li class=""><a href="/docs/sites/">Sites using Jekyll</a></li>
-
-
-
- <li class=""><a href="/docs/resources/">Resources</a></li>
-
-
-
- <li class=""><a href="/docs/upgrading/0-to-2/">Upgrading from 0.x to 2.x</a></li>
-
-
-
- <li class=""><a href="/docs/upgrading/2-to-3/">Upgrading from 2.x to 3.x</a></li>
-
-</ul>
-
-
- <h4>Meta</h4>
- <ul>
-
-
-
- <li class=""><a href="/docs/contributing/">Contributing</a></li>
-
-
-
- <li class=""><a href="/docs/maintaining/">Maintaining Jekyll</a></li>
-
-
-
- <li class=""><a href="/docs/conduct/">Code of Conduct</a></li>
-
-
-
- <li class=""><a href="/docs/history/">History</a></li>
-
-</ul>
-
-
</aside>
</div>
<div class="clear"></div>
@@ -843,16 +698,25 @@
<footer>
<div class="grid">
<div class="unit one-third center-on-mobiles">
- <p>The contents of this website are <br>© 2020 under the terms of the <a href="https://github.com/jekyll/jekyll/blob/master/LICENSE">MIT License</a>.</p>
+ <p>Jekyll is lovingly maintained by the <a href="/team/">core team</a> of volunteers. </p>
+ <p>The contents of this website are <br />© 2019 under the terms of the <a href="https://github.com/jekyll/jekyll/blob/master/LICENSE">MIT License</a>.</p>
</div>
<div class="unit two-thirds align-right center-on-mobiles">
<p>
Proudly hosted by
<a href="https://github.com">
<img src="/img/footer-logo.png" width="100" height="30" alt="GitHub • Social coding">
+ </a>
+ </p>
+ </div>
+ <div class="unit two-thirds align-right center-on-mobiles">
+ <p>
+ Jekyll is funded thanks to its
+ <a href="https://github.com/jekyll/jekyll#sponsors">
+ sponsors!
</a>
</p>
</div>
</div>
</footer>