site/docs/posts/index.html in jekyll-docs-3.6.2.0 vs site/docs/posts/index.html in jekyll-docs-3.7.0

- old
+ new

@@ -2,32 +2,34 @@ <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.6.2"> + <meta name="generator" content="Jekyll v3.7.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="https://cdn.jsdelivr.net/npm/docsearch.js@2/dist/cdn/docsearch.min.css"> <link rel="stylesheet" href="/css/screen.css"> <link rel="icon" type="image/x-icon" href="/favicon.ico"> - <!-- Begin Jekyll SEO tag v2.3.0 --> + <!-- Begin Jekyll SEO tag v2.4.0 --> <title>Writing posts | Jekyll • Simple, blog-aware, static sites</title> +<meta name="generator" content="Jekyll v3.7.0"> <meta property="og:title" content="Writing 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!"> <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:type" content="article"> -<meta property="article:published_time" content="2017-10-24T09:12:04-07:00"> +<meta property="article:published_time" content="2018-01-03T02:41:17-08: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"> -{"name":null,"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!","url":"https://jekyllrb.com/docs/posts/","headline":"Writing posts","dateModified":"2017-10-24T09:12:04-07:00","datePublished":"2017-10-24T09:12:04-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/posts/"},"@context":"http://schema.org"}</script> +{"headline":"Writing posts","dateModified":"2018-01-03T02:41:17-08:00","datePublished":"2018-01-03T02:41:17-08:00","mainEntityOfPage":{"@type":"WebPage","@id":"https://jekyllrb.com/docs/posts/"},"publisher":{"@type":"Organization","logo":{"@type":"ImageObject","url":"https://jekyllrb.com/img/logo-2x.png"}},"url":"https://jekyllrb.com/docs/posts/","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!","@type":"BlogPosting","@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> @@ -35,66 +37,71 @@ </head> <body class="wrap"> <header> - <nav class="mobile-nav show-on-mobiles"> - <ul> + <div class="flexbox"> + <div class="center-on-mobiles"> + <h1> + <a href="/" class="logo"> + <span class="sr-only">Jekyll</span> + <img src="/img/logo-2x.png" width="140" height="65" alt="Jekyll Logo"> + </a> + </h1> + </div> + <nav class="main-nav hide-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="/community/">Community</a> - </li> - <li class=""> <a href="/help/">Help</a> </li> - <li> - <a href="https://github.com/jekyll/jekyll">GitHub</a> - </li> </ul> - </nav> - <div class="grid"> - <div class="unit one-third center-on-mobiles"> - <h1> - <a href="/"> - <span class="sr-only">Jekyll</span> - <img src="/img/logo-2x.png" width="249" height="115" alt="Jekyll Logo"> - </a> - </h1> + </nav> + <div class="search hide-on-mobiles"> + <input type="text" id="docsearch-input" placeholder="Search the docs…"> + </div> - <nav class="main-nav unit two-thirds hide-on-mobiles"> + <div class="meta hide-on-mobiles"> <ul> + <li> + <a href="https://github.com/jekyll/jekyll/releases/tag/v3.7.0">v3.7.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="/community/">Community</a> - </li> - <li class=""> <a href="/help/">Help</a> </li> <li> <a href="https://github.com/jekyll/jekyll">GitHub</a> </li> </ul> - </nav> - </div> + </nav> </header> <section class="docs"> <div class="grid"> @@ -308,18 +315,18 @@ <p>To create a new post, all you need to do is create a file in the <code class="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> -<div class="language-sh 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="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-sh 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> <div class="note"> <h5>ProTip™: Link to other posts</h5> @@ -358,57 +365,52 @@ <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>There are a number of ways to include digital assets in Jekyll. +<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="highlighter-rouge">assets</code> or <code class="highlighter-rouge">downloads</code>, into which any images, downloads +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. 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="highlighter-rouge">site.url</code> -variable in a post.</p> +some examples in Markdown of how you could do this using the <code class="highlighter-rouge">absolute_url</code> +filter in a post.</p> <p>Including an image asset in a post:</p> -<div class="language-text highlighter-rouge"><div class="highlight"><pre class="highlight"><code>... which is shown in the screenshot below: -![My helpful screenshot]({{ site.url }}/assets/screenshot.jpg) +<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 }}) </code></pre></div></div> <p>Linking to a PDF for readers to download:</p> -<div class="language-text highlighter-rouge"><div class="highlight"><pre class="highlight"><code>... you can [get the PDF]({{ site.url }}/assets/mydoc.pdf) 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">{{</span> <span class="nn">"/assets/mydoc.pdf"</span> | absolute_url }}) directly. </code></pre></div></div> -<div class="note"> - <h5>ProTip™: Link using just the site root URL</h5> - <p> - You can skip the <code>{{ site.url }}</code> variable - if you <strong>know</strong> your site will only ever be displayed at the - root URL of your domain. In this case you can reference assets directly with - just <code>/path/file.jpg</code>. - </p> +<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="highlighter-rouge"><div class="highlight"><pre class="highlight"><code>--- -layout: post -title: "Welcome to Jekyll!" -date: 2015-11-17 16:16:01 -0600 -categories: jekyll update ---- -You’ll find this post in your `_posts` 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 `bundle exec jekyll serve`, which launches a web server and auto-regenerates your site when a file is updated. +<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> -To add new posts, simply add a file in the `_posts` directory that follows the convention `YYYY-MM-DD-name-of-post.ext` and includes the necessary front matter. Take a look at the source for this post to get an idea about how it works. +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="highlighter-rouge">---</code> are part of the YAML Front Matter, and everything after the second <code class="highlighter-rouge">---</code> will be rendered with Markdown and show up as “Content.”</p> +<p>Everything in between the first and second <code class="highlighter-rouge">---</code> are part of the YAML Front Matter, and everything after the second <code class="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 @@ -431,47 +433,91 @@ <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="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> + +<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>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>First, in the <code class="highlighter-rouge">_layouts</code> directory create a new file called <code class="highlighter-rouge">category.html</code> - in +that file put (at least) the following:</p> + +<div class="language-liquid highlighter-rouge"><div class="highlight"><pre class="highlight"><code>--- +layout: page +--- + +<span class="p">{%</span><span class="w"> </span><span class="nt">for</span><span class="w"> </span>post<span class="w"> </span>in<span class="w"> </span>site.categories[page.category]<span class="w"> </span><span class="p">%}</span> + &lt;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>"&gt; + <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> + &lt;/a&gt; +<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="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="highlighter-rouge">blog</code> then create a file in the new directory +called <code class="highlighter-rouge">blog.html</code> with at least</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> + +<p>In this case, the listing pages will be accessible at <code class="highlighter-rouge">{baseurl}/category/blog.html</code></p> + +<p>While this example is done with categories, you can easily extend your lists to +filter by tags or any other variable created with extensions.</p> + <h2 id="post-excerpts">Post excerpts</h2> <p>Each post automatically takes the first block of text, from the beginning of the content to the first occurrence of <code class="highlighter-rouge">excerpt_separator</code>, and sets it as the <code class="highlighter-rouge">post.excerpt</code>. 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> -<div class="language-html highlighter-rouge"><div class="highlight"><pre class="highlight"><code><span class="nt">&lt;ul&gt;</span> - {% for post in site.posts %} - <span class="nt">&lt;li&gt;</span> - <span class="nt">&lt;a</span> <span class="na">href=</span><span class="s">"{{ post.url }}"</span><span class="nt">&gt;</span>{{ post.title }}<span class="nt">&lt;/a&gt;</span> - {{ post.excerpt }} - <span class="nt">&lt;/li&gt;</span> - {% endfor %} -<span class="nt">&lt;/ul&gt;</span> +<div class="language-liquid highlighter-rouge"><div class="highlight"><pre class="highlight"><code>&lt;ul&gt; + <span class="p">{%</span><span class="w"> </span><span class="nt">for</span><span class="w"> </span>post<span class="w"> </span>in<span class="w"> </span>site.posts<span class="w"> </span><span class="p">%}</span> + &lt;li&gt; + &lt;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>"&gt;<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>&lt;/a&gt; + <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> + &lt;/li&gt; + <span class="p">{%</span><span class="w"> </span><span class="nt">endfor</span><span class="w"> </span><span class="p">%}</span> +&lt;/ul&gt; </code></pre></div></div> <p>Because Jekyll grabs the first paragraph you will not need to wrap the excerpt in <code class="highlighter-rouge">p</code> tags, which is already done for you. These tags can be removed with the following if you’d prefer:</p> -<div class="language-html highlighter-rouge"><div class="highlight"><pre class="highlight"><code>{{ post.excerpt | remove: '<span class="nt">&lt;p&gt;</span>' | remove: '<span class="nt">&lt;/p&gt;</span>' }} +<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">'&lt;p&gt;'</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">'&lt;/p&gt;'</span><span class="w"> </span><span class="p">}}</span> </code></pre></div></div> <p>If you don’t like the automatically-generated post excerpt, it can be explicitly overridden by adding an <code class="highlighter-rouge">excerpt</code> value to your post’s YAML Front Matter. Alternatively, you can choose to define a custom <code class="highlighter-rouge">excerpt_separator</code> in the post’s YAML front matter:</p> -<div class="language-text highlighter-rouge"><div class="highlight"><pre class="highlight"><code>--- -excerpt_separator: &lt;!--more--&gt; ---- +<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">&lt;!--more--&gt;</span> +<span class="nn">---</span> -Excerpt -&lt;!--more--&gt; -Out-of-excerpt +<span class="s">Excerpt</span> +<span class="s">&lt;!--more--&gt;</span> +<span class="s">Out-of-excerpt</span> </code></pre></div></div> <p>You can also set the <code class="highlighter-rouge">excerpt_separator</code> globally in your <code class="highlighter-rouge">_config.yml</code> configuration file.</p> @@ -487,19 +533,19 @@ <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-text highlighter-rouge"><div class="highlight"><pre class="highlight"><code>{% highlight ruby %} +<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 -{% endhighlight %} +<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> @@ -773,11 +819,11 @@ <footer> <div class="grid"> <div class="unit one-third center-on-mobiles"> - <p>The contents of this website are <br>© 2017 under the terms of the <a href="https://github.com/jekyll/jekyll/blob/master/LICENSE">MIT License</a>.</p> + <p>The contents of this website are <br>© 2018 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"> @@ -851,8 +897,17 @@ ga('send', 'pageview'); </script> + <script type="text/javascript" src="https://cdn.jsdelivr.net/npm/docsearch.js@2/dist/cdn/docsearch.min.js"></script> +<script type="text/javascript"> docsearch({ +apiKey: '50fe39c839958dfad797000f33e2ec17', +indexName: 'jekyllrb', +inputSelector: '#docsearch-input', +enhancedSearchInput: true, +debug: false // Set debug to true if you want to inspect the dropdown +}); +</script> </body> </html>