Docs: updates (#6407)

Merge pull request 6407

.github/CONTRIBUTING.markdown

@@ -121,19 +121,27 @@ site or configuration. [Feel free to check it out!](https://github.com/jekyll/je
 
 To run the test suite and build the gem you'll need to install Jekyll's dependencies by running the following command:
 
-<pre class="highlight"><code>$ script/bootstrap</code></pre>
+```sh
+script/bootstrap
+```
 
 Before you make any changes, run the tests and make sure that they pass (to confirm your environment is configured properly):
 
-<pre class="highlight"><code>$ script/cibuild</code></pre>
+```sh
+script/cibuild
+```
 
 If you are only updating a file in `test/`, you can use the command:
 
-<pre class="highlight"><code>$ script/test test/blah_test.rb</code></pre>
+```sh
+script/test test/blah_test.rb
+```
 
 If you are only updating a `.feature` file, you can use the command:
 
-<pre class="highlight"><code>$ script/cucumber features/blah.feature</code></pre>
+```sh
+script/cucumber features/blah.feature
+```
 
 Both `script/test` and `script/cucumber` can be run without arguments to
 run its entire respective suite.

docs/_config.yml

@@ -8,7 +8,6 @@ google_analytics_id: UA-50755011-1
 google_site_verification: onQcXpAvtHBrUI5LlroHNE_FP0b2qvFyPq7VZw36iEY
 
 repository: https://github.com/jekyll/jekyll
-help_url: https://github.com/jekyll/jekyll-help
 
 timezone: America/Los_Angeles
 

docs/_docs/collections.md

@@ -454,7 +454,7 @@ works:
 
 Every album in the collection could be listed on a single page with a template:
 
-```html
+```liquid
 {% raw %}
 {% for album in site.albums %}
   <h2>{{ album.title }}</h2>

docs/_docs/continuous-integration/circleci.md

@@ -40,7 +40,7 @@ CircleCI detects when `Gemfile` is present is will automatically run `bundle ins
 
 The most basic test that can be run is simply seeing if `jekyll build` actually works. This is a blocker, a dependency if you will,  for other tests you might run on the generate site. So we'll run Jekyll, via Bundler, in the `dependencies` phase.
 
-```
+```yaml
 dependencies:
   post:
     - bundle exec jekyll build
@@ -63,7 +63,7 @@ test:
 
 When you put it all together, here's an example of what that `circle.yml` file could look like:
 
-```
+```yaml
 machine:
   environment:
     NOKOGIRI_USE_SYSTEM_LIBRARIES: true # speeds up installation of html-proofer

docs/_docs/continuous-integration/travis-ci.md

@@ -49,7 +49,7 @@ Some options can be specified via command-line switches. Check out the
 For example to avoid testing external sites, use this command:
 
 ```sh
-$ bundle exec htmlproofer ./_site --disable-external
+bundle exec htmlproofer ./_site --disable-external
 ```
 
 ### The HTML Proofer Library

docs/_docs/contributing.md

@@ -125,19 +125,27 @@ site or configuration. [Feel free to check it out!](https://github.com/jekyll/je
 
 To run the test suite and build the gem you'll need to install Jekyll's dependencies by running the following command:
 
-<pre class="highlight"><code>$ script/bootstrap</code></pre>
+```sh
+script/bootstrap
+```
 
 Before you make any changes, run the tests and make sure that they pass (to confirm your environment is configured properly):
 
-<pre class="highlight"><code>$ script/cibuild</code></pre>
+```sh
+script/cibuild
+```
 
 If you are only updating a file in `test/`, you can use the command:
 
-<pre class="highlight"><code>$ script/test test/blah_test.rb</code></pre>
+```sh
+script/test test/blah_test.rb
+```
 
 If you are only updating a `.feature` file, you can use the command:
 
-<pre class="highlight"><code>$ script/cucumber features/blah.feature</code></pre>
+```sh
+script/cucumber features/blah.feature
+```
 
 Both `script/test` and `script/cucumber` can be run without arguments to
 run its entire respective suite.

docs/_docs/datafiles.md

@@ -56,8 +56,8 @@ determines the variable name).
 
 You can now render the list of members in a template:
 
-```html
 {% raw %}
+```liquid
 <ul>
 {% for member in site.data.members %}
   <li>
@@ -67,8 +67,8 @@ You can now render the list of members in a template:
   </li>
 {% endfor %}
 </ul>
-{% endraw %}
 ```
+{% endraw %}
 
 {: .note .info }
 If your Jekyll site has a lot of pages, such as with documentation websites, see the detailed examples in [how to build robust navigation for your site]({% link _tutorials/navigation.md %}).
@@ -106,8 +106,8 @@ members:
 The organizations can then be accessed via `site.data.orgs`, followed by the
 file name:
 
-```html
 {% raw %}
+```liquid
 <ul>
 {% for org_hash in site.data.orgs %}
 {% assign org = org_hash[1] %}
@@ -119,8 +119,8 @@ file name:
   </li>
 {% endfor %}
 </ul>
-{% endraw %}
 ```
+{% endraw %}
 
 ## Example: Accessing a specific author
 
@@ -136,8 +136,8 @@ dave:
 
 The author can then be specified as a page variable in a post's frontmatter:
 
-```html
 {% raw %}
+```liquid
 ---
 title: sample post
 author: dave
@@ -149,8 +149,7 @@ author: dave
   title="{{ author.name }}">
     {{ author.name }}
 </a>
-
-{% endraw %}
 ```
+{% endraw %}
 
 For information on how to build robust navigation for your site (especially if you have a documentation website or another type of Jekyll site with a lot of pages to organize), see [Navigation](/tutorials/navigation).

docs/_docs/frontmatter.md

@@ -129,14 +129,14 @@ data that is sent to the Liquid templating engine during the conversion. For
 instance, if you set a title, you can use that in your layout to set the page
 title:
 
-```html
+```liquid
 <!DOCTYPE HTML>
 <html>
   <head>
     <title>{% raw %}{{ page.title }}{% endraw %}</title>
   </head>
   <body>
-    ...
+    …
 ```
 
 ## Predefined Variables for Posts
@@ -167,7 +167,7 @@ These are available out-of-the-box to be used in the front matter for a post.
     </tr>
     <tr>
       <td>
-        <p style="margin-bottom: 5px;"><code>category</code></p>
+        <p><code>category</code></p>
         <p><code>categories</code></p>
       </td>
       <td>

docs/_docs/github-pages.md

@@ -60,14 +60,14 @@ branch to GitHub. However, the subdirectory-like URL structure GitHub uses for
 Project Pages complicates the proper resolution of URLs. In order to assure your
 site builds properly, use the handy [URL filters](../templates/#filters):
 
-```html
 {% raw %}
+```liquid
 <!-- For styles with static names... -->
 <link href="{{ "/assets/css/style.css" | relative_url }}" rel="stylesheet">
 <!-- For documents/pages whose URLs can change... -->
 [{{ page.title }}]("{{ page.url | relative_url }}")
-{% endraw %}
 ```
+{% endraw %}
 
 This way you can preview your site locally from the site root on localhost,
 but when GitHub generates your pages from the `gh-pages` branch all the URLs

docs/_docs/includes.md

@@ -5,9 +5,11 @@ permalink: /docs/includes/
 
 The `include` tag allows you to include the content from another file stored in the `_includes` folder:
 
+{% raw %}
 ```liquid
-{% raw %}{% include footer.html %}{% endraw %}
+{% include footer.html %}
 ```
+{% endraw %}
 
 Jekyll will look for the referenced file (in this case, `footer.html`) in the `_includes` directory at the root of your source directory and insert its contents.
 
@@ -15,9 +17,11 @@ Jekyll will look for the referenced file (in this case, `footer.html`) in the `_
 
 You can choose to include file fragments relative to the current file by using the `include_relative` tag:
 
+{% raw %}
 ```liquid
-{% raw %}{% include_relative somedir/footer.html %}{% endraw %}
+{% include_relative somedir/footer.html %}
 ```
+{% endraw %}
 
 You won't need to place your included content within the `_includes` directory. Instead,
 the inclusion is specifically relative to the file where the tag is being used. For example,
@@ -42,9 +46,11 @@ my_variable: footer_company_a.html
 
 You could then reference that variable in your include:
 
+{% raw %}
 ```liquid
-{% raw %}{% include {{ page.my_variable }} %}{% endraw %}
+{% include {{ page.my_variable }} %}
 ```
+{% endraw %}
 
 In this example, the include would insert the file `footer_company_a.html` from the `_includes/footer_company_a.html` directory.
 
@@ -52,18 +58,22 @@ In this example, the include would insert the file `footer_company_a.html` from
 
 You can also pass parameters to an include. For example, suppose you have a file called `note.html` in your `_includes` folder that contains this formatting:
 
+{% raw %}
 ```liquid
-{% raw %}<div markdown="span" class="alert alert-info" role="alert">
+<div markdown="span" class="alert alert-info" role="alert">
 <i class="fa fa-info-circle"></i> <b>Note:</b>
 {{ include.content }}
-</div>{% endraw %}
+</div>
 ```
+{% endraw %}
 
 The `{% raw %}{{ include.content }}{% endraw %}` is a parameter that gets populated when you call the include and specify a value for that parameter, like this:
 
+{% raw %}
 ```liquid
-{% raw %}{% include note.html content="This is my sample note." %} {% endraw %}
+{% include note.html content="This is my sample note." %}
 ```
+{% endraw %}
 
 The value of `content` (which is `This is my sample note`) will be inserted into the {% raw %}`{{ include.content }}`{% endraw %} parameter.
 
@@ -82,14 +92,16 @@ For example, suppose you have a special image syntax with complex formatting, an
 
 You could templatize this content in your include and make each value available as a parameter, like this:
 
+{% raw %}
 ```liquid
-{% raw %}<figure>
+<figure>
    <a href="{{ include.url }}">
    <img src="{{ include.file }}" style="max-width: {{ include.max-width }};"
       alt="{{ include.alt }}"/>
    <figcaption>{{ include.caption }}</figcaption>
-</figure>{% endraw %}
+</figure>
 ```
+{% endraw %}
 
 This include contains 5 parameters:
 
@@ -101,15 +113,17 @@ This include contains 5 parameters:
 
 Here's an example that passes all the parameters to this include (the include file is named `image.html`):
 
+{% raw %}
 ```liquid
-{% raw %}{% include image.html url="http://jekyllrb.com"
+{% include image.html url="http://jekyllrb.com"
 max-width="200px" file="logo.png" alt="Jekyll logo"
-caption="This is the Jekyll logo." %} {% endraw %}
+caption="This is the Jekyll logo." %}
 ```
+{% endraw %}
 
 The result is the original HTML code shown earlier.
 
-To safeguard situations where users don't supply a value for the parameter, you can use [Liquid's default filter](https://help.shopify.com/themes/liquid/filters/additional-filters#default).
+To safeguard situations where users don't supply a value for the parameter, you can use [Liquid's default filter](https://shopify.github.io/liquid/filters/default/).
 
 Overall, you can create includes that act as templates for a variety of uses &mdash; inserting audio or video clips, alerts, special formatting, and more. However, note that you should avoid using too many includes, as this will slow down the build time of your site. For example, don't use includes every time you insert an image. (The above technique shows a use case for special images.)
 
@@ -121,16 +135,21 @@ The string you pass to your include parameter can't contain curly braces. For ex
 
 If you want to include this variable in your parameter that you pass to an include, you need to store the entire parameter as a variable before passing it to the include. You can use `capture` tags to create the variable:
 
+{% raw %}
 ```liquid
-{% raw %}{% capture download_note %}The latest version of
+{% capture download_note %}
-{{ site.product_name }} is now available.{% endcapture %}{% endraw %}
+The latest version of {{ site.product_name }} is now available.
+{% endcapture %}
 ```
+{% endraw %}
 
 Then pass this captured variable into the parameter for the include. Omit the quotation marks around the parameter content because it's no longer a string (it's a variable):
 
+{% raw %}
 ```liquid
-{% raw %}{% include note.html content=download_note %}{% endraw %}
+{% include note.html content=download_note %}
 ```
+{% endraw %}
 
 ### Passing references to YAML files as parameter values
 
@@ -150,18 +169,22 @@ Here's an example. In the `_data` folder, suppose you have a YAML file called `p
 
 In the `_includes` folder, assume you have a file called `spotlight.html` with this code:
 
+{% raw %}
 ```liquid
-{% raw %}{% for person in include.participants %}
+{% for person in include.participants %}
 {% if person.login_age == "new" %}
 {{ person.name }}
 {% endif %}
-{% endfor %}{% endraw %}
+{% endfor %}
 ```
+{% endraw %}
 
 Now when you insert the `spotlight.html` include file, you can submit the YAML file as a parameter:
 
+{% raw %}
+```liquid
+{% include spotlight.html participants=site.data.profiles %}
 ```
-{% raw %}{% include spotlight.html participants=site.data.profiles %}{% endraw %}
+{% endraw %}
-```
 
 In this instance, `site.data.profiles` gets inserted in place of {% raw %}`include.participants`{% endraw %} in the include file, and the Liquid logic processes. The result will be `Jane Doe`.

docs/_docs/index.md

@@ -15,7 +15,7 @@ development of Jekyll itself.
 Jekyll is a simple, blog-aware, static site generator. It takes a template
 directory containing raw text files in various formats, runs it through
 a converter (like [Markdown](https://daringfireball.net/projects/markdown/))
-and our [Liquid](https://github.com/Shopify/liquid/wiki) renderer, and
+and our [Liquid](https://shopify.github.io/liquid/) renderer, and
 spits out a complete, ready-to-publish static website suitable
 for serving with your favorite web server. Jekyll also happens to be the engine
 behind [GitHub Pages](https://pages.github.com), which means you can use Jekyll

docs/_docs/pagination.md

@@ -24,7 +24,7 @@ your `_config.yml` under `plugins`. For Jekyll 2, this is standard.
 
 ## Enable pagination
 
-To enable pagination for your blog, add a line to the `_config.yml` file that
+To enable pagination for posts on your blog, add a line to the `_config.yml` file that
 specifies how many items should be displayed per page:
 
 ```yaml
@@ -55,6 +55,14 @@ directory.
   </p>
 </div>
 
+<div class="note info">
+  <h5>Pagination for categories, tags and collections</h5>
+  <p>
+    The more recent <a href="https://github.com/sverrirs/jekyll-paginate-v2">jekyll-paginate-v2</a> plugin supports more features. See the <a href="https://github.com/sverrirs/jekyll-paginate-v2/tree/master/examples">pagination examples</a> in the repository.
+    <strong>This plugin is not supported by GitHub Pages</strong>.
+  </p>
+</div>
+
 ## Liquid Attributes Available
 
 The pagination plugin exposes the `paginator` liquid object with the following
@@ -145,8 +153,8 @@ the `paginator` variable that will now be available to you. You’ll probably
 want to do this in one of the main pages of your site. Here’s one example of a
 simple way of rendering paginated Posts in a HTML file:
 
-```html
 {% raw %}
+```liquid
 ---
 layout: default
 title: My Blog
@@ -177,8 +185,8 @@ title: My Blog
     <span class="next ">Next</span>
   {% endif %}
 </div>
-{% endraw %}
 ```
+{% endraw %}
 
 <div class="note warning">
   <h5>Beware the page one edge-case</h5>
@@ -192,8 +200,8 @@ title: My Blog
 The following HTML snippet should handle page one, and render a list of each
 page with links to all but the current page.
 
-```html
 {% raw %}
+```liquid
 {% if paginator.total_pages > 1 %}
 <div class="pagination">
   {% if paginator.previous_page %}
@@ -219,5 +227,5 @@ page with links to all but the current page.
   {% endif %}
 </div>
 {% endif %}
-{% endraw %}
 ```
+{% endraw %}

docs/_docs/plugins.md

@@ -387,11 +387,11 @@ Liquid::Template.register_tag('render_time', Jekyll::RenderTimeTag)
 In the example above, we can place the following tag anywhere in one of our
 pages:
 
-```ruby
 {% raw %}
+```ruby
 <p>{% render_time page rendered at: %}</p>
-{% endraw %}
 ```
+{% endraw %}
 
 And we would get something like this on the page:
 

docs/_docs/posts.md

@@ -80,53 +80,52 @@ out where to store these files in your site is something everyone will face.
 
 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 `assets` or `downloads`, into which any images, downloads
+called something like `assets`, 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 `site.url`
+some examples in Markdown of how you could do this using the `absolute_url`
-variable in a post.
+filter in a post.
 
 Including an image asset in a post:
 
-```text
+{% raw %}
+```markdown
 ... which is shown in the screenshot below:
-![My helpful screenshot]({% raw %}{{ site.url }}{% endraw %}/assets/screenshot.jpg)
+![My helpful screenshot]({{ "/assets/screenshot.jpg" | absolute_url }})
 ```
+{% endraw %}
 
 Linking to a PDF for readers to download:
 
-```text
+{% raw %}
-... you can [get the PDF]({% raw %}{{ site.url }}{% endraw %}/assets/mydoc.pdf) directly.
+```markdown
+... you can [get the PDF]({{ "/assets/mydoc.pdf" | absolute_url }}) directly.
 ```
+{% endraw %}
+
+<div class="info">
 
-<div class="note">
-  <h5>ProTip™: Link using just the site root URL</h5>
-  <p>
-    You can skip the <code>{% raw %}{{ site.url }}{% endraw %}</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>
 
 ## A typical post
 
 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:
 
-```
+```markdown
 ---
 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.
 
 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.
-
 ```
-Everything in between the first and second `---` are part of the YAML Front Matter, and everything after the second `---` will be rendered with Markdown and show up as "Content."
+
+Everything in between the first and second `---` are part of the YAML Front Matter, and everything after the second `---` will be rendered with Markdown and show up as "Content".
 
 ## Displaying an index of posts
 
@@ -136,15 +135,17 @@ you have a list of posts somewhere. Creating an index of posts on another page
 language](https://docs.shopify.com/themes/liquid/basics) and its tags. Here’s a
 basic example of how to create a list of links to your blog posts:
 
+{% raw %}
 ```html
 <ul>
-  {% raw %}{% for post in site.posts %}{% endraw %}
+  {% for post in site.posts %}
     <li>
-      <a href="{% raw %}{{ post.url }}{% endraw %}">{% raw %}{{ post.title }}{% endraw %}</a>
+      <a href="{{ post.url }}">{{ post.title }}</a>
     </li>
-  {% raw %}{% endfor %}{% endraw %}
+  {% endfor %}
 </ul>
 ```
+{% endraw %}
 
 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 [how templates
@@ -170,24 +171,27 @@ a basic example of how to create a list of posts from a specific category.
 
 First, in the `_layouts` directory create a new file called `category.html` - in
 that file put (at least) the following:
-```
+
+{% raw %}
+```liquid
 ---
 layout: page
 ---
+
 {% for post in site.categories[page.category] %}
-    <a href="{{ post.url | prepend: site.baseurl }}">
+    <a href="{{ post.url | absolute_url }}">
       {{ post.title }}
     </a>
-<hr>
 {% endfor %}
 ```
+{% endraw %}
 
 Next, in the root directory of your Jekyll install, create a new directory
 called `category` and then create a file for each category you want to list. For
 example, if you have a category `blog` then create a file in the new directory
 called `blog.html` with at least
 
-```text
+```yaml
 ---
 layout: category
 title: Blog
@@ -208,31 +212,35 @@ 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:
 
-```html
+{% raw %}
+```liquid
 <ul>
-  {% raw %}{% for post in site.posts %}{% endraw %}
+  {% for post in site.posts %}
     <li>
-      <a href="{% raw %}{{ post.url }}{% endraw %}">{% raw %}{{ post.title }}{% endraw %}</a>
+      <a href="{{ post.url }}">{{ post.title }}</a>
-      {% raw %}{{ post.excerpt }}{% endraw %}
+      {{ post.excerpt }}
     </li>
-  {% raw %}{% endfor %}{% endraw %}
+  {% endfor %}
 </ul>
 ```
+{% endraw %}
 
 Because Jekyll grabs the first paragraph you will not need to wrap the excerpt
 in `p` tags, which is already done for you. These tags can be removed with the
 following if you'd prefer:
 
-```html
+{% raw %}
-{% raw %}{{ post.excerpt | remove: '<p>' | remove: '</p>' }}{% endraw %}
+```liquid
+{{ post.excerpt | remove: '<p>' | remove: '</p>' }}
 ```
+{% endraw %}
 
 If you don't like the automatically-generated post excerpt, it can be
 explicitly overridden by adding an `excerpt` value to your post's YAML
 Front Matter. Alternatively, you can choose to define a custom
 `excerpt_separator` in the post's YAML front matter:
 
-```text
+```yaml
 ---
 excerpt_separator: <!--more-->
 ---
@@ -259,8 +267,9 @@ 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:
 
-```text
+{% raw %}
-{% raw %}{% highlight ruby %}{% endraw %}
+```liquid
+{% highlight ruby %}
 def show
   @widget = Widget(params[:id])
   respond_to do |format|
@@ -268,8 +277,9 @@ def show
     format.json { render json: @widget }
   end
 end
-{% raw %}{% endhighlight %}{% endraw %}
+{% endhighlight %}
 ```
+{% endraw %}
 
 And the output will look like this:
 

docs/_docs/static_files.md

@@ -88,11 +88,13 @@ This assumes that your Jekyll site has a folder path of `assets/img` where  you
 
 Suppose you want to list all your image assets as contained in `assets/img`. You could use this for loop to look in the `static_files` object and get all static files that have this front matter property:
 
+{% raw %}
 ```liquid
-{% raw %}{% assign image_files = site.static_files | where: "image", true %}
+{% assign image_files = site.static_files | where: "image", true %}
 {% for myimage in image_files %}
   {{ myimage.path }}
-{% endfor %}{% endraw %}
+{% endfor %}
 ```
+{% endraw %}
 
 When you build your site, the output will list the path to each file that meets this front matter condition.

docs/_docs/templates.md

@@ -428,9 +428,11 @@ The default is `default`. They are as follows (with what they filter):
 
 If you have small page snippets that you want to include in multiple places on your site, save the snippets as *include files* and insert them where required, by using the `include` tag:
 
+{% raw %}
 ```liquid
-{% raw %}{% include footer.html %}{% endraw %}
+{% include footer.html %}
 ```
+{% endraw %}
 
 Jekyll expects all *include files* to be placed in an `_includes` directory at the root of your source directory. In the above example, this will embed the contents of `_includes/footer.html` into the calling file.
 
@@ -451,15 +453,15 @@ languages](http://pygments.org/languages/)
 
 To render a code block with syntax highlighting, surround your code as follows:
 
-```liquid
 {% raw %}
+```liquid
 {% highlight ruby %}
 def foo
   puts 'foo'
 end
 {% endhighlight %}
-{% endraw %}
 ```
+{% endraw %}
 
 The argument to the `highlight` tag (`ruby` in the example above) is the
 language identifier. To find the appropriate identifier to use for the language
@@ -474,15 +476,15 @@ Including the `linenos` argument will force the highlighted code to include line
 numbers. For instance, the following code block would include line numbers next
 to each line:
 
-```liquid
 {% raw %}
+```liquid
 {% highlight ruby linenos %}
 def foo
   puts 'foo'
 end
 {% endhighlight %}
-{% endraw %}
 ```
+{% endraw %}
 
 #### Stylesheets for syntax highlighting
 
@@ -503,25 +505,25 @@ To link to a post, a page, collection item, or file, the `link` tag will generat
 
 You must include the file's original extension when using the `link` tag. Here are some examples:
 
-```liquid
 {% raw %}
+```liquid
 {{ site.baseurl }}{% link _collection/name-of-document.md %}
 {{ site.baseurl }}{% link _posts/2016-07-26-name-of-post.md %}
 {{ site.baseurl }}{% link news/index.html %}
 {{ site.baseurl }}{% link /assets/files/doc.pdf %}
-{% endraw %}
 ```
+{% endraw %}
 
 You can also use the `link` tag to create a link in Markdown as follows:
 
-```liquid
 {% raw %}
+```liquid
 [Link to a document]({{ site.baseurl }}{% link _collection/name-of-document.md %})
 [Link to a post]({{ site.baseurl }}{% link _posts/2016-07-26-name-of-post.md %})
 [Link to a page]({{ site.baseurl }}{% link news/index.html %})
 [Link to a file]({{ site.baseurl }}{% link /assets/files/doc.pdf %})
-{% endraw %}
 ```
+{% endraw %}
 
 (Including `{% raw %}{{ site.baseurl }}{% endraw %}` is optional — it depends on whether you want to preface the page URL with the `baseurl` value.)
 
@@ -539,26 +541,26 @@ Note you cannot add filters to `link` tags. For example, you cannot append a str
 
 If you want to include a link to a post on your site, the `post_url` tag will generate the correct permalink URL for the post you specify.
 
-```liquid
 {% raw %}
+```liquid
 {{ site.baseurl }}{% post_url 2010-07-21-name-of-post %}
-{% endraw %}
 ```
+{% endraw %}
 
 If you organize your posts in subdirectories, you need to include subdirectory path to the post:
 
-```liquid
 {% raw %}
+```liquid
 {{ site.baseurl }}{% post_url /subdir/2010-07-21-name-of-post %}
-{% endraw %}
 ```
+{% endraw %}
 
 There is no need to include the file extension when using the `post_url` tag.
 
 You can also use this tag to create a link to a post in Markdown as follows:
 
-```liquid
 {% raw %}
+```liquid
 [Name of Link]({{ site.baseurl }}{% post_url 2010-07-21-name-of-post %})
-{% endraw %}
 ```
+{% endraw %}

docs/_docs/themes.md

@@ -218,13 +218,15 @@ _sass
 
 Your theme's styles can be included in the user's stylesheet using the `@import` directive.
 
+{% raw %}
 ```css
-{% raw %}@import "{{ site.theme }}";{% endraw %}
+@import "{{ site.theme }}";
 ```
+{% endraw %}
 
 ### Theme-gem dependencies
 
-From `v3.5`, Jekyll will automatically require all whitelisted `runtime_dependencies` of your theme-gem even if they're not explicitly included under the `gems` array in the site's config file. (NOTE: whitelisting is only required when building or serving with the `--safe` option.)
+From `v3.5`, Jekyll will automatically require all whitelisted `runtime_dependencies` of your theme-gem even if they're not explicitly included under the `plugins` array in the site's config file. (Note: whitelisting is only required when building or serving with the `--safe` option.)
 
 With this, the end-user need not keep track of the plugins required to be included in their config file for their theme-gem to work as intended.
 

docs/_docs/troubleshooting.md

@@ -261,7 +261,7 @@ The issue is caused by trying to copy a non-existing symlink.
 <div class="note">
   <h5>Please report issues you encounter!</h5>
   <p>
-  If you come across a bug, please <a href="{{ site.help_url }}/issues/new">create an issue</a>
+  If you come across a bug, please <a href="{{ site.repository }}/issues/new">create an issue</a>
   on GitHub describing the problem and any work-arounds you find so we can
   document it here for others.
   </p>

docs/_docs/upgrading/0-to-2.md

@@ -9,7 +9,7 @@ and 2.0 that you'll want to know about.
 Before we dive in, go ahead and fetch the latest version of Jekyll:
 
 ```sh
-$ gem update jekyll
+gem update jekyll
 ```
 
 <div class="note feature">

docs/_docs/upgrading/2-to-3.md

@@ -3,20 +3,21 @@ title: Upgrading from 2.x to 3.x
 permalink: /docs/upgrading/2-to-3/
 ---
 
-Upgrading from an older version of Jekyll? A few things have changed in 3.0
+Upgrading from an older version of Jekyll? A few things have changed in Jekyll 3
 that you'll want to know about.
 
 Before we dive in, go ahead and fetch the latest version of Jekyll:
 
 ```sh
-$ gem update jekyll
+gem update jekyll
 ```
 
-Please note: Jekyll 3.2 requires Ruby version >= 2.1
+Since v3.2 Jekyll requires Ruby version >= 2.1
+{: .note .warning }
 
 <div class="note feature">
-  <h5 markdown="1">Diving in</h5>
+  <h5>Diving in</h5>
-  <p markdown="1">Want to get a new Jekyll site up and running quickly? Simply
+  <p>Want to get a new Jekyll site up and running quickly? Simply
    run <code>jekyll new SITENAME</code> to create a new folder with a bare bones
    Jekyll site.</p>
 </div>

docs/_docs/usage.md

@@ -7,22 +7,22 @@ The Jekyll gem makes a `jekyll` executable available to you in your Terminal
 window. You can use this command in a number of ways:
 
 ```sh
-$ jekyll build
+jekyll build
 # => The current folder will be generated into ./_site
 
-$ jekyll build --destination <destination>
+jekyll build --destination <destination>
 # => The current folder will be generated into <destination>
 
-$ jekyll build --source <source> --destination <destination>
+jekyll build --source <source> --destination <destination>
 # => The <source> folder will be generated into <destination>
 
-$ jekyll build --watch
+jekyll build --watch
 # => The current folder will be generated into ./_site,
 #    watched for changes, and regenerated automatically.
 ```
 
 <div class="note info">
-  <h5>Changes to _config.yml are not included during automatic regeneration.</h5>
+  <h5>Changes to <code>_config.yml</code> are not included during automatic regeneration.</h5>
   <p>
     The <code>_config.yml</code> master configuration file contains global configurations
     and variable definitions that are read once at execution time. Changes made to <code>_config.yml</code>
@@ -52,25 +52,22 @@ Jekyll also comes with a built-in development server that will allow you to
 preview what the generated site will look like in your browser locally.
 
 ```sh
-$ jekyll serve
+jekyll serve
 # => A development server will run at http://localhost:4000/
 # Auto-regeneration: enabled. Use `--no-watch` to disable.
 
-$ jekyll serve --detach
+jekyll serve --detach
 # => Same as `jekyll serve` but will detach from the current terminal.
 #    If you need to kill the server, you can `kill -9 1234` where "1234" is the PID.
 #    If you cannot find the PID, then do, `ps aux | grep jekyll` and kill the instance.
 ```
-
+<div class="note tip">
-<div class="note info">
+  <h5>Livereload</h5>
-  <h5>Be aware of default behavior</h5>
+  <p>If you want to enable Livereload, you can enable the <a href="https://github.com/RobertDeRose/jekyll-livereload">jekyll-livereload</a> plugin in a <a href="../configuration/#build-command-options">development config file</a>.</p>
-  <p>
-    As of version 2.4, the <code>serve</code> command will watch for changes automatically. To disable this, you can use <code>jekyll serve --no-watch</code>, which preserves the old behavior.
-  </p>
 </div>
 
 ```sh
-$ jekyll serve --no-watch
+jekyll serve --no-watch
 # => Same as `jekyll serve` but will not watch for changes.
 ```
 
@@ -89,8 +86,8 @@ destination: _deploy
 Then the following two commands will be equivalent:
 
 ```sh
-$ jekyll build
+jekyll build
-$ jekyll build --source _source --destination _deploy
+jekyll build --source _source --destination _deploy
 ```
 
 For more about the possible configuration options, see the

docs/_docs/windows.md

@@ -17,17 +17,17 @@ If you are using Windows 10 Anniversary Update, the easiest way to run Jekyll is
 
 First let's make sure all our packages / repositories are up to date. Open a new Command Prompt instance, and type the following:
 
-```
+```sh
 bash
 ```
 Your Command Prompt instance should now be a Bash instance. Now we must update our repo lists and packages.
 
-```
+```sh
 sudo apt-get update -y && sudo apt-get upgrade -y
 ```
 Now we can install Ruby. To do this we will use a repository from [BrightBox](https://www.brightbox.com/docs/ruby/ubuntu/), which hosts optimized versions of Ruby for Ubuntu.
 
-```
+```sh
 sudo apt-add-repository ppa:brightbox/ruby-ng
 sudo apt-get update
 sudo apt-get install ruby2.3 ruby2.3-dev build-essential
@@ -35,19 +35,19 @@ sudo apt-get install ruby2.3 ruby2.3-dev build-essential
 
 Next let's update our Ruby gems:
 
-```
+```sh
 sudo gem update
 ```
 
 Now all that is left to do is install Jekyll.
 
-```
+```sh
 sudo gem install jekyll bundler
 ```
 
 Check if Jekyll installed properly by running:
 
-```
+```sh
 jekyll -v
 ```
 
@@ -55,7 +55,7 @@ jekyll -v
 
 To start a new project named `my_blog`, just run:
 
-```
+```sh
 jekyll new my_blog
 ```
 
@@ -122,14 +122,14 @@ This gem is also needed in the github-pages and to get it running on Windows x64
 
 **Note:** In the current [pre release][nokogiriFails] it works out of the box with Windows x64 but this version is not referenced in the github-pages.
 
-`choco install libxml2 -Source "https://www.nuget.org/api/v2/"`{:.language-ruby}
+```sh
+choco install libxml2 -Source "https://www.nuget.org/api/v2/"
 
-`choco install libxslt -Source "https://www.nuget.org/api/v2/"`{:.language-ruby}
+choco install libxslt -Source "https://www.nuget.org/api/v2/"
 
-`choco install libiconv -Source "https://www.nuget.org/api/v2/"`{:.language-ruby}
+choco install libiconv -Source "https://www.nuget.org/api/v2/
 
-```ruby
+gem install nokogiri --^
- gem install nokogiri --^
    --with-xml2-include=C:\Chocolatey\lib\libxml2.2.7.8.7\build\native\include^
    --with-xml2-lib=C:\Chocolatey\lib\libxml2.redist.2.7.8.7\build\native\bin\v110\x64\Release\dynamic\cdecl^
    --with-iconv-include=C:\Chocolatey\lib\libiconv.1.14.0.11\build\native\include^
@@ -165,14 +165,10 @@ In the future the installation process of the github-pages should be as simple a
 [Bundler]: http://bundler.io/ "Ruby Dependencie Manager"
 [nokogiriReleases]: https://github.com/sparklemotion/nokogiri/releases "Nokogiri Releases"
 
----
-
 For a more conventional way of installing Jekyll you can follow this [complete guide to install Jekyll 3 on Windows by Sverrir Sigmundarson][windows-installjekyll3].
 
 Optionally you can use [Autoinstall Jekyll for Windows][fastjekyll-autoinstall].
 
----
-
 [windows-installjekyll3]: https://labs.sverrirs.com/jekyll/
 [fastjekyll-autoinstall]: https://github.com/KeJunMao/fastjekyll#autoinstall-jekyll-for-windows
 
@@ -185,7 +181,7 @@ Jekyll. This is especially relevant when you're running Jekyll on Windows.
 Additionally, you might need to change the code page of the console window to UTF-8 in case you get a "Liquid Exception: Incompatible character encoding" error during the site generation process. It can be done with the following command:
 
 ```sh
-$ chcp 65001
+chcp 65001
 ```
 
 
@@ -207,7 +203,7 @@ gem 'tzinfo-data', platforms: [:mingw, :mswin, :x64_mingw, :jruby]
 
 ## Auto Regeneration
 
-As of v1.3.0, Jekyll uses the `listen` gem to watch for changes when the `--watch` switch is specified during a build or serve. While `listen` has built-in support for UNIX systems, it may require an extra gem for compatibility with Windows.
+Jekyll uses the `listen` gem to watch for changes when the `--watch` switch is specified during a build or serve. While `listen` has built-in support for UNIX systems, it may require an extra gem for compatibility with Windows.
 
 Add the following to the Gemfile for your site if you have issues with auto-regeneration on Windows alone:
 

docs/_posts/2014-12-22-jekyll-2-5-3-released.markdown

@@ -10,7 +10,7 @@ Happy Holidays, everyone.
 
 Jekyll v2.5.3 is a quick patch release, containing some minor fixes. See the
 [full history](/docs/history/) for more info. If you notice any problems,
-please [let us know]({{ site.help_url }}).
+please [let us know]({{ site.repository }}).
 
 This release also marks the start of Jekyll 3 development. I wrote about it
 over on my personal blog: [Jekyll 3 — The Road Ahead](https://byparker.com/blog/2014/jekyll-3-the-road-ahead/).

docs/_sass/_pygments.scss

@@ -8,7 +8,7 @@
   .n { color: #ffffff} /* Name */
   .o { color: #ffffff} /* Operator */
   .x { color: #ffffff} /* Other */
-  .p { color: #ffffff} /* Punctuation */
+  .p { color: #98b9ef} /* Punctuation */
   .cm { color: #87ceeb} /* Comment.Multiline */
   .cp { color: #cd5c5c} /* Comment.Preproc */
   .c1 { color: #87ceeb} /* Comment.Single */
@@ -45,7 +45,7 @@
   .nx { color: #ffffff} /* Name.Other */
   .py { color: #ffffff} /* Name.Property */
   .nt { color: #f0e68c} /* Name.Tag */
-  .nv { color: #98fb98} /* Name.Variable */
+  .nv { color: #88d472} /* Name.Variable */
   .ow { color: #ffffff} /* Operator.Word */
   .w { color: #ffffff} /* Text.Whitespace */
   .mf { color: #ffffff} /* Literal.Number.Float */
@@ -69,10 +69,6 @@
   .vi { color: #98fb98} /* Name.Variable.Instance */
   .il { color: #ffffff} /* Literal.Number.Integer.Long */
   .bash .nv {
-    -webkit-user-select: none;
-       -moz-user-select: none;
-        -ms-user-select: none;
-         -o-user-select: none;
     user-select: none;
   }
 }

docs/_tutorials/convert-existing-site-to-jekyll.md

@@ -306,7 +306,7 @@ At minimum, a layout should contain `{% raw %}{{ content }}{% endraw %}`, which
 
 ### For loops
 
-By the way, let's pause here to look at the `for` loop logic a little more closely. [For loops in Liquid](https://help.shopify.com/themes/liquid/tags/iteration-tags#for) are one of the most commonly used Liquid tags. *For loops* let you iterate through content in your Jekyll site and build out a result. The `for` loop also has [certain properties available](https://help.shopify.com/themes/liquid/objects/for-loops) (like first or last iteration) based on the loop's position in the loop as well.
+By the way, let's pause here to look at the `for` loop logic a little more closely. [For loops in Liquid](https://shopify.github.io/liquid/tags/iteration/) are one of the most commonly used Liquid tags. *For loops* let you iterate through content in your Jekyll site and build out a result. The `for` loop also has [certain properties available](https://help.shopify.com/themes/liquid/objects/for-loops) (like first or last iteration) based on the loop's position in the loop as well.
 
 We've only scratched the surface of what you can do with `for` loops in retrieving posts. For example, if you wanted to display posts from a specific category, you could do so by adding a `categories` property to your post's front matter and then look in those categories. Further, you could limit the number of results by adding a `limit` property. Here's an example:
 

docs/_tutorials/custom-404-page.md

@@ -15,7 +15,7 @@ Simply add a `404.md` or `404.html` at the root of your site's source directory
 
 If you plan to organize your files under subdirectories, the error page should have the following Front Matter Data, set: `permalink: /404.html`. This is to ensure that the compiled `404.html` resides at the root of your processed site, where it'll be picked by the server.
 
-```
+```markdown
 ---
 # example 404.md
 
@@ -34,13 +34,13 @@ Apache Web Servers load a configuration file named [`.htaccess`](http://www.htac
 
 Simply add the following to your `.htaccess` file.
 
-```
+```apache
 ErrorDocument 404 /404.html
 ```
 
 With an `.htaccess` file, you have the freedom to place your error page within a subdirectory.
 
-```
+```apache
 ErrorDocument 404 /error_pages/404.html
 ```
 
@@ -55,7 +55,7 @@ The procedure is just as simple as configuring Apache servers, but slightly diff
 
 Add the following to the nginx configuration file, `nginx.conf`, which is usually located inside `/etc/nginx/` or `/etc/nginx/conf/`:
 
-```
+```nginx
 server {
   error_page 404 /404.html;
   location  /404.html {
@@ -63,4 +63,5 @@ server {
   }
 }
 ```
+
 The `location` directive prevents users from directly browsing the 404.html page.

docs/_tutorials/navigation.md

@@ -91,12 +91,14 @@ Suppose you wanted to sort the list by the `title`. To do this, convert the refe
 
 **Liquid**
 
+{% raw %}
 ```liquid
-{% raw %}{% assign doclist = site.data.samplelist.docs | sort: 'title'  %}
+{% assign doclist = site.data.samplelist.docs | sort: 'title'  %}
 {% for item in doclist %}
     <li><a href="{{ item.url }}" alt="{{ item.title }}">{{ item.title }}</a></li>
-{% endfor %}{% endraw %}
+{% endfor %}
 ```
+{% endraw %}
 
 **Result**
 
@@ -110,9 +112,11 @@ The items now appear in alphabetical order. The `sort` property in the Liquid fi
 
 See the [Liquid array filter](https://help.shopify.com/themes/liquid/filters/array-filters) for more filter options. Note that you can't simply use this syntax:
 
+{% raw %}
 ```liquid
-{% raw %}{% for item in site.data.samplelist.docs | sort: "title" %}{% endfor %}{% endraw %}
+{% for item in site.data.samplelist.docs | sort: "title" %}{% endfor %}
 ```
+{% endraw %}
 
 You have to convert `site.data.samplelist.docs` to a variable first using either `assign` or `capture` tags.
 
@@ -152,16 +156,18 @@ toc:
 
 **Liquid**
 
+{% raw %}
 ```liquid
-{% raw %}{% for item in site.data.samplelist.toc %}
+{% for item in site.data.samplelist.toc %}
     <h3>{{ item.title }}</h3>
       <ul>
         {% for entry in item.subfolderitems %}
           <li><a href="{{ entry.url }}">{{ entry.page }}</a></li>
         {% endfor %}
       </ul>
-  {% endfor %}{% endraw %}
+  {% endfor %}
 ```
+{% endraw %}
 
 **Result**
 <div class="highlight result">
@@ -242,8 +248,9 @@ toc2:
 
 **Liquid**
 
+{% raw %}
 ```liquid
-{% raw %}<div>
+<div>
 {% if site.data.samplelist.toc2[0] %}
   {% for item in site.data.samplelist.toc2 %}
     <h3>{{ item.title }}</h3>
@@ -263,8 +270,9 @@ toc2:
       {% endif %}
     {% endfor %}
 {% endif %}
-</div>{% endraw %}
+</div>
 ```
+{% endraw %}
 
 **Result**
 
@@ -327,13 +335,16 @@ sidebar: toc
 
 **Liquid**
 
+{% raw %}
 ```liquid
-{% raw %}<ul>
+<ul>
     {% for item in site.data.samplelist[page.sidebar] %}
       <li><a href="{{ item.url }}">{{ item.title }}</a></li>
     {% endfor %}
-</ul>{% endraw %}
+</ul>
 ```
+{% endraw %}
+
 **Result**
 
 <div class="highlight result">
@@ -361,13 +372,15 @@ In addition to inserting items from the YAML data file into your list, you also
 ```
 **Liquid**
 
+{% raw %}
 ```liquid
-{% raw %}{% for item in site.data.samplelist.docs %}
+{% for item in site.data.samplelist.docs %}
     <li class="{% if item.url == page.url %}active{% endif %}">
       <a href="{{ item.url }}">{{ item.title }}</a>
     </li>
-{% endfor %}{% endraw %}
+{% endfor %}
 ```
+{% endraw %}
 
 **Result**
 
@@ -412,15 +425,17 @@ docs2:
 
 **Liquid**
 
+{% raw %}
 ```liquid
-{% raw %}<ul>
+<ul>
     {% for item in site.data.samplelist.docs2 %}
       {% if item.version == 1 %}
         <li><a href="{{ item.url }}">{{ item.title }}</a></li>
       {% endif %}
     {% endfor %}
-</ul>{% endraw %}
+</ul>
 ```
+{% endraw %}
 
 **Result**
 
@@ -491,16 +506,18 @@ Note that even though `category` is used in the doc front matter, `category` is
 
 If you wanted to simply get all docs in the collection for a specific category, you could use a `for` loop with an `if` condition to check for a specific category:
 
+{% raw %}
 ```liquid
-{% raw %}<h3>Getting Started</h3>
+<h3>Getting Started</h3>
 <ul>
     {% for doc in site.docs %}
       {% if doc.category == "getting-started" %}
         <li><a href="{{ doc.url }}">{{ doc.title }}</a></li>
       {% endif %}
     {% endfor %}
-</ul>{% endraw %}
+</ul>
 ```
+{% endraw %}
 
 The result would be as follows:
 
@@ -523,8 +540,9 @@ Here's the code for getting lists of pages grouped under their corresponding cat
 
 **Liquid**
 
+{% raw %}
 ```liquid
-{% raw %}{% assign mydocs = site.docs | group_by: 'category' %}
+{% assign mydocs = site.docs | group_by: 'category' %}
 {% for cat in mydocs %}
 <h2>{{ cat.name | capitalize }}</h2>
     <ul>
@@ -533,8 +551,9 @@ Here's the code for getting lists of pages grouped under their corresponding cat
         <li><a href="{{ item.url }}">{{ item.title }}</a></li>
       {% endfor %}
     </ul>
-{% endfor %}{% endraw %}
+{% endfor %}
 ```
+{% endraw %}
 
 **Result**
 
@@ -574,6 +593,6 @@ After getting the category name, we assign the variable `items` for the docs and
 
 The `for item in items` loop looks through each `item` and gets the `title` and `url` to form the list item link.
 
-For more details on the `group_by` filter, see [Jekyll's Templates documentation](https://jekyllrb.com/docs/templates/) as well as [this Siteleaf tutorial](https://www.siteleaf.com/blog/advanced-liquid-group-by/). For more details on the `sort` filter, see [sort](https://help.shopify.com/themes/liquid/filters/array-filters#sort) in Liquid's documentation.
+For more details on the `group_by` filter, see [Jekyll's Templates documentation](https://jekyllrb.com/docs/templates/) as well as [this Siteleaf tutorial](https://www.siteleaf.com/blog/advanced-liquid-group-by/). For more details on the `sort` filter, see [sort](https://shopify.github.io/liquid/filters/sort/) in Liquid's documentation.
 
 Whether you use properties in your doc's front matter to retrieve your pages or a YAML data file, in both cases you can programmatically build a more robust navigation for your site.

docs/_tutorials/orderofinterpretation.md

@@ -37,15 +37,19 @@ The following scenarios highlight potential problems you might encounter. These
 
 In your layout file (`_layouts/default.html`), suppose you have a variable assigned:
 
+{% raw %}
+```liquid
+{% assign myvar = "joe" %}
 ```
-{% raw %}{% assign myvar = "joe" %}{% endraw %}
+{% endraw %}
-```
 
 On a page that uses the layout, you reference that variable:
 
+{% raw %}
+```liquid
+{{ myvar }}
 ```
-{% raw %}{{ myvar }}{% endraw %}
+{% endraw %}
-```
 
 The variable won't render because the page's order of interpretation is to render Liquid first and later process the Layout. When the Liquid rendering happens, the variable assignment isn't available.
 
@@ -63,9 +67,11 @@ This is a list:
 
 You include the file into an HTML file as follows:
 
+{% raw %}
 ```liquid
-{% raw %}{% include mycontent.md %}{% endraw %}
+{% include mycontent.md %}
 ```
+{% endraw %}
 
 The Markdown is not processed because first the Liquid (`include` tag) gets processed, inserting `mycontent.md` into the HTML file. *Then* the Markdown would get processed.
 
@@ -75,11 +81,13 @@ To make the code work, use HTML formatting in includes that are inserted into HT
 
 Note that `highlight` tags don't require Markdown to process. Suppose your include contains the following:
 
+{% raw %}
 ```liquid
-{% raw %}{% highlight javascript %}
+{% highlight javascript %}
 console.log('alert');
-{% endhighlight %}{% endraw %}
+{% endhighlight %}
 ```
+{% endraw %}
 
 The `highlight` tag *is* Liquid. (Liquid passes the content to Rouge or Pygments for syntax highlighting.) As a result, this code will actually convert to HTML with syntax highlighting. Jekyll does not need the Markdown filter to process `highlight` tags.
 
@@ -87,8 +95,9 @@ The `highlight` tag *is* Liquid. (Liquid passes the content to Rouge or Pygments
 
 Suppose you try to mix Liquid's `assign` tag with JavaScript, like this:
 
+{% raw %}
 ```javascript
-{% raw %}<button onclick="someFunction()">Click me</button>
+<button onclick="someFunction()">Click me</button>
 
 <p id="intro"></p>
 
@@ -97,15 +106,17 @@ Suppose you try to mix Liquid's `assign` tag with JavaScript, like this:
 function someFunction() {
     document.getElementById("intro").innerHTML = someContent;
 }
-</script>{% endraw %}
+</script>
 ```
+{% endraw %}
 
 This won't work because the `assign` tag is only available during the Liquid rendering phase of the site. In this JavaScript example, the script executes when a user clicks a button ("Click me") on the HTML page. At that time, the Liquid logic is no longer available, so the `assign` tag wouldn't return anything.
 
 However, you can use Jekyll's site variables or Liquid to *populate* a script that is executed at a later time. For example, suppose you have the following property in your front matter: `someContent: "This is some content"`. You could do this:
 
+{% raw %}
 ```js
-{% raw %}<button onclick="someFunction()">Click me</button>
+<button onclick="someFunction()">Click me</button>
 
 <p id="intro"></p>
 
@@ -114,8 +125,9 @@ However, you can use Jekyll's site variables or Liquid to *populate* a script th
 function someFunction() {
     document.getElementById("intro").innerHTML = "{{ page.someContent }}";
 }
-</script>{% endraw %}
+</script>
 ```
+{% endraw %}
 
 When Jekyll builds the site, this `someContent` property populates the script's values, converting `{% raw %}{{ page.someContent }}{% endraw %}` to `"This is some content"`.
 
@@ -127,17 +139,21 @@ There's one more detail to remember: Liquid does not render when embedded in YAM
 
 For example, suppose you have a `highlight` tag in your `_data/mydata.yml` file:
 
-```
+{% raw %}
-{% raw %}myvalue: >
+```liquid
+myvalue: >
   {% highlight javascript %}
   console.log('alert');
-  {% endhighlight %}{% endraw %}
+  {% endhighlight %}
 ```
+{% endraw %}
 
 On a page, you try to insert the value:
 
+{% raw %}
+```liquid
+{{ site.data.mydata.myvalue }}
 ```
-{% raw %}{{ site.data.mydata.myvalue }}{% endraw %}
+{% endraw %}
-```
 
 This would render only as a string rather than a code sample with syntax highlighting. To make the code render, consider using an include instead.

docs/community/index.md

@@ -4,9 +4,11 @@ title: Community
 permalink: /community/
 ---
 
+## Jekyllconf
+
 [JekyllConf](http://jekyllconf.com) is a free, online conference for all things Jekyll hosted by [CloudCannon](http://cloudcannon.com). Each year members of the Jekyll community speak about interesting use cases, tricks they've learned, or meta Jekyll topics.
 
-## Featured
+### Featured
 {% assign random = site.time | date: "%s%N" | modulo: site.data.jekyllconf-talks.size %}
 {% assign featured = site.data.jekyllconf-talks[random] %}
 
@@ -17,7 +19,7 @@ permalink: /community/
 
 {% assign talks = site.data.jekyllconf-talks | group_by: 'year' %}
 {% for year in talks reversed %}
-## {{ year.name }}
+### {{ year.name }}
     {% for talk in year.items %}
  * [{{ talk.topic }}](https://youtu.be/{{ talk.youtube_id }}) - [{{ talk.speaker }}](https://twitter.com/{{ talk.twitter_handle }})
     {% endfor %}