docs: improve highlighting of code blocks (#8017)

Merge pull request 8017

docs/_config.yml

@@ -46,6 +46,9 @@ plugins:
 feed:
   categories:
   - release
+kramdown:
+  syntax_highlighter_opts:
+    default_lang: plaintext
 sass:
   style: compressed
 strict_front_matter: true

docs/_docs/assets.md

@@ -79,7 +79,6 @@ sass:
 These are passed to Sass, so any output style options Sass supports are valid
 here, too.
 
-
 ## Coffeescript
 
 To enable Coffeescript in Jekyll 3.0 and up you must

docs/_docs/collections.md

@@ -15,7 +15,8 @@ example here's a collection of staff members:
 collections:
   - staff_members
 ```
-In this case `collections` is defined as a sequence (i.e array) with no additional metadata defined for each collection.  
+
+In this case `collections` is defined as a sequence (i.e array) with no additional metadata defined for each collection.
 You can optionally specify metadata for your collection by defining `collections` as a mapping (i.e hashmap) instead of sequence, and then defining additional fields in it:
 
 ```yaml
@@ -71,7 +72,7 @@ Jane has worked on Jekyll for the past *five years*.
   Do note that in spite of being considered as a collection internally, the above
   doesn't apply to [posts](/docs/posts/). Posts with a valid filename format will be
   marked for processing even if they do not contain front matter.
-</em> 
+</em>
 
 <div class="note info">
   <h5>Be sure to name your directories correctly</h5>
@@ -96,7 +97,6 @@ using the `content` variable:
 ```
 {% endraw %}
 
-
 If you'd like Jekyll to create a rendered page for each document in your
 collection, you can set the `output` key to `true` in your collection
 metadata in `_config.yml`:
@@ -285,7 +285,6 @@ you specified in your `_config.yml` (if present) and the following information:
   </p>
 </div>
 
-
 ### Documents
 
 In addition to any front matter provided in the document's corresponding

docs/_docs/community/community.md

@@ -28,7 +28,6 @@ There are a bunch of helpful community members on these services that should be
 * [How to file a bug](/docs/community/bug/)
 * [Guide for maintaining Jekyll](/docs/maintaining/)
 
-
 ## Jekyllconf
 
 [Watch videos](/jekyllconf/) from members of the Jekyll community speak about interesting use cases, tricks they’ve learned or meta Jekyll topics.

docs/_docs/configuration/front-matter-defaults.md

@@ -114,7 +114,6 @@ defaults:
   </p>
 </div>
 
-
 ### Precedence
 
 Jekyll will apply all of the configuration settings you specify in the `defaults` section of your `_config.yml` file. You can choose to override settings from other scope/values pair by specifying a more specific path for the scope.

docs/_docs/configuration/markdown.md

@@ -51,7 +51,7 @@ currently supported options:
   </p>
 </div>
 
-For more details about these options have a look at the [Kramdown configuration documentation](https://kramdown.gettalong.org/options.html). 
+For more details about these options have a look at the [Kramdown configuration documentation](https://kramdown.gettalong.org/options.html).
 
 ### CommonMark
 
@@ -78,9 +78,9 @@ extension for disabling fenced code.
 Note that you can also specify a language for highlighting after the first
 delimiter:
 
-        ```ruby
+    ```ruby
-        # ...ruby code
+    # ...ruby code
-        ```
+    ```
 
 With both fenced code blocks and highlighter enabled, this will statically
 highlight the code; without any syntax highlighter, it will add a

docs/_docs/configuration/options.md

@@ -346,7 +346,6 @@ class="flag">flags</code> (specified on the command-line) that control them.
 </table>
 </div>
 
-
 ### Serve Command Options
 
 In addition to the options below, the `serve` sub-command can accept any of the options

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

@@ -34,7 +34,7 @@ Save the commands you want to run and succeed in a file: `./script/cibuild`
 
 ### The HTML Proofer Executable
 
-```sh
+```bash
 #!/usr/bin/env bash
 set -e # halt script on error
 

docs/_docs/datafiles.md

@@ -42,7 +42,7 @@ In `_data/members.yml`:
 
 Or `_data/members.csv`:
 
-```text
+```
 name,github
 Eric Mill,konklone
 Parker Moore,parkr

docs/_docs/deployment/automated.md

@@ -11,7 +11,7 @@ CI.
 
 These services run a script when there's a commit on your Git repository.
 You might want this script to build the site, run tests over the output then deploy it to the
-service of your choice. 
+service of your choice.
 
 We have guides for the following providers:
 

docs/_docs/deployment/manual.md

@@ -31,7 +31,6 @@ Most traditional web hosting provider let you upload files to their servers over
 
 If you have direct access to the deployment web server, the process is essentially the same, except you might have other methods available to you (such as `scp`, or even direct filesystem access) for transferring the files. Remember to make sure the contents of the generated `_site` folder get placed in the appropriate web root directory for your web server.
 
-
 ## Rack-Jekyll
 
 [Rack-Jekyll](https://github.com/adaoraul/rack-jekyll/) allows you to deploy your site on any Rack server such as Amazon EC2, Slicehost, Heroku, and so forth. It also can run with [shotgun](https://github.com/rtomayko/shotgun/), [rackup](https://github.com/rack/rack), [mongrel](https://github.com/mongrel/mongrel), [unicorn](https://github.com/defunkt/unicorn/), and [others](https://github.com/adaoraul/rack-jekyll#readme).

docs/_docs/deployment/third-party.md

@@ -33,7 +33,6 @@ Kickster provides a basic Jekyll project setup packed with web best practises an
 
 Install the Kickster gem and you are good to go. More documentation can here found [here](https://github.com/nielsenramon/kickster#kickster). If you do not want to use the gem or start a new project you can just copy paste the deployment scripts for [Travis CI](https://github.com/nielsenramon/kickster/tree/master/snippets/travis) or [Circle CI](https://github.com/nielsenramon/kickster#automated-deployment-with-circle-ci).
 
-
 ## Netlify
 
 Netlify provides Global CDN, Continuous Deployment, one click HTTPS and [much more](https://www.netlify.com/features/), providing developers the most robust toolset available for modern web projects, without added complexity. Netlify supports custom plugins for Jekyll and has a free plan for open source projects.

docs/_docs/includes.md

@@ -69,7 +69,7 @@ You can also pass parameters to an include. For example, suppose you have a file
 ```
 {% 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:
+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

docs/_docs/installation/macos.md

@@ -13,7 +13,7 @@ xcode-select --install
 ## Install Ruby
 
 Jekyll requires **Ruby > {{ site.data.ruby.min_version }}**.
-macOS Catalina 10.15 comes with ruby 2.6.3, so you're fine. 
+macOS Catalina 10.15 comes with ruby 2.6.3, so you're fine.
 If you're running a previous macOS system, you'll have to install a newer version of Ruby.
 
 ### With Homebrew {#brew}
@@ -26,9 +26,9 @@ To run the latest Ruby version you need to install it through [Homebrew](https:/
 brew install ruby
 ```
 
-Add the brew ruby path to your shell config :
+Add the brew ruby path to your shell config:
 
-```
+```bash
 export PATH=/usr/local/opt/ruby/bin:$PATH
 ```
 
@@ -56,10 +56,10 @@ Ruby versions. This is very useful when you need to be able to run a given Ruby
 # Install rbenv and ruby-build
 brew install rbenv
 
-# Setup rbenv integration to your shell
+# Set up rbenv integration with your shell
 rbenv init
 
-# Check your install
+# Check your installation
 curl -fsSL https://github.com/rbenv/rbenv-installer/raw/master/bin/rbenv-doctor | bash
 ```
 
@@ -94,7 +94,7 @@ ruby -v
 
 Then append your path file with the following, replacing the `X.X` with the first two digits of your Ruby version.
 
-```
+```bash
 export PATH=$HOME/.gem/ruby/X.X.0/bin:$PATH
 ```
 

docs/_docs/installation/other-linux.md

@@ -6,7 +6,7 @@ Installation on other Linux distributions works similarly as on [Ubuntu](../ubun
 
 On Fedora, the dependencies can be installed as follows:
 
- ```sh
+```sh
 sudo dnf install ruby ruby-devel @development-tools
 ```
 

docs/_docs/installation/windows.md

@@ -8,7 +8,6 @@ redirect_from:
 While Windows is not an officially-supported platform, it can be used to run Jekyll with the proper tweaks. This page aims to
 collect some of the general knowledge and lessons that have been unearthed by Windows users.
 
-
 ## Installing Jekyll
 
 ### Installation via RubyInstaller
@@ -43,11 +42,13 @@ First let's make sure all our packages / repositories are up to date. Open a new
 ```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.
 
@@ -90,7 +91,6 @@ with the current date in the filename.
 
 **Note:** Bash on Ubuntu on Windows is still under development, so you may run into issues.
 
-
 ## Encoding
 
 If you use UTF-8 encoding, make sure that no `BOM` header characters exist in your files or very, very bad things will happen to

docs/_docs/layouts.md

@@ -24,17 +24,14 @@ from this as needed.
   </p>
 </div>
 
-
 ## Usage
 
 The first step is to put the template source code in `default.html`. `content`
 is a special variable, the value is the rendered content of the post or page
 being wrapped.
 
-
-
 {% raw %}
-```
+```liquid
 <!doctype html>
 <html lang="en">
   <head>
@@ -67,7 +64,7 @@ You can also use
 [front matter defaults](/docs/configuration/front-matter-defaults/) to save you
 from having to set this on every page.
 
-```
+```markdown
 ---
 title: My First Page
 layout: default
@@ -78,7 +75,7 @@ This is the content of my page
 
 The rendered output of this page is:
 
-```
+```html
 <!doctype html>
 <html lang="en">
   <head>
@@ -102,7 +99,6 @@ The rendered output of this page is:
 </html>
 ```
 
-
 ## Inheritance
 
 Layout inheritance is useful when you want to add something to an existing
@@ -115,7 +111,7 @@ layout in front matter. For example this layout will live at
 `_layouts/post.html`:
 
 {% raw %}
-```
+```liquid
 ---
 layout: default
 ---
@@ -134,7 +130,7 @@ using in Liquid, you need to use the `layout` variable instead of `page`. For
 example:
 
 {% raw %}
-```
+```liquid
 ---
 city: San Francisco
 ---

docs/_docs/liquid.md

@@ -5,7 +5,7 @@ redirect_from: "/docs/templates/"
 ---
 
 Jekyll uses the [Liquid](https://shopify.github.io/liquid/) templating language
-to process templates. 
+to process templates.
 
 Generally in Liquid you output content using two curly braces e.g.
 {% raw %}`{{ variable }}`{% endraw %} and perform logic statements by

docs/_docs/liquid/filters.md

@@ -108,15 +108,21 @@ The default is `default`. They are as follows (with what they filter):
 
 You can use the `where` filter to detect documents and pages with properties that are `nil` or `""`. For example,
 
+{% raw %}
 ```liquid
-// Using `nil` to select posts that either do not have `my_prop` defined or `my_prop` has been set to `nil` explicitly.
+// Using `nil` to select posts that either do not have `my_prop`
-{% raw %}{% assign filtered_posts = site.posts | where: 'my_prop', nil %}{% endraw %}
+// defined or `my_prop` has been set to `nil` explicitly.
+{% assign filtered_posts = site.posts | where: 'my_prop', nil %}
 ```
+{% endraw %}
 
+{% raw %}
 ```liquid
-// Using Liquid's special literal `empty` or `blank` to select posts that have `my_prop` set to an empty value.
+// Using Liquid's special literal `empty` or `blank` to select
-{% raw %}{% assign filtered_posts = site.posts | where: 'my_prop', empty %}{% endraw %}
+// posts that have `my_prop` set to an empty value.
+{% assign filtered_posts = site.posts | where: 'my_prop', empty %}
 ```
+{% endraw %}
 
 ### Binary operators in `where_exp` filter {%- include docs_version_badge.html version="4.0" -%}
 
@@ -125,15 +131,19 @@ conditionals in the operation.
 
 For example, to get a list of documents on English horror flicks, one could use the following snippet:
 
+{% raw %}
 ```liquid
-{% raw %}{{ site.movies | where_exp: "item", "item.genre == 'horror' and item.language == 'English'" }}{% endraw %}
+{{ site.movies | where_exp: "item", "item.genre == 'horror' and item.language == 'English'" }}
 ```
+{% endraw %}
 
 Or to get a list of comic-book based movies, one may use the following:
 
+{% raw %}
 ```liquid
-{% raw %}{{ site.movies | where_exp: "item", "item.sub_genre == 'MCU' or item.sub_genre == 'DCEU'" }}{% endraw %}
+{{ site.movies | where_exp: "item", "item.sub_genre == 'MCU' or item.sub_genre == 'DCEU'" }}
 ```
+{% endraw %}
 
 ### Standard Liquid Filters
 

docs/_docs/liquid/tags.md

@@ -71,8 +71,8 @@ end
 
 In order for the highlighting to show up, you’ll need to include a highlighting
 stylesheet. For Pygments or Rouge you can use a stylesheet for Pygments, you
-can find an example gallery 
+can find an example gallery
-[here](https://jwarby.github.io/jekyll-pygments-themes/languages/ruby.html) 
+[here](https://jwarby.github.io/jekyll-pygments-themes/languages/ruby.html)
 or from [its repository](https://github.com/jwarby/jekyll-pygments-themes).
 
 Copy the CSS file (`native.css` for example) into your css directory and import
@@ -117,11 +117,11 @@ The path to the post, page, or collection is defined as the path relative to the
 
 For example, suppose you're creating a link in `page_a.md` (stored in `pages/folder1/folder2`) to `page_b.md` (stored in  `pages/folder1`). Your path in the link would not be `../page_b.html`. Instead, it would be `/pages/folder1/page_b.md`.
 
-If you're unsure of the path, add `{% raw %}{{ page.path }}{% endraw %}` to the page and it will display the path.
+If you're unsure of the path, add {% raw %}`{{ page.path }}`{% endraw %} to the page and it will display the path.
 
 One major benefit of using the `link` or `post_url` tag is link validation. If the link doesn't exist, Jekyll won't build your site. This is a good thing, as it will alert you to a broken link so you can fix it (rather than allowing you to build and deploy a site with broken links).
 
-Note you cannot add filters to `link` tags. For example, you cannot append a string using Liquid filters, such as `{% raw %}{% link mypage.html | append: "#section1" %} {% endraw %}`. To link to sections on a page, you will need to use regular HTML or Markdown linking techniques.
+Note you cannot add filters to `link` tags. For example, you cannot append a string using Liquid filters, such as {% raw %}`{% link mypage.html | append: "#section1" %}`{% endraw %}. To link to sections on a page, you will need to use regular HTML or Markdown linking techniques.
 
 ### Linking to posts
 

docs/_docs/maintaining/merging-a-pull-request.md

@@ -20,7 +20,7 @@ We have [a helpful little bot](https://github.com/jekyllbot) which we use to mer
 
 To merge a pull request, leave a comment thanking the contributor, then add the special merge request:
 
-```text
+```
 Thank you very much for your contribution. Folks like you make this project and community strong. :heart:
 
 @jekyllbot: merge +dev

docs/_docs/pages.md

@@ -13,7 +13,7 @@ a `.md` extension which converts to HTML on build. For a site with
 a homepage, an about page, and a contact page, here’s what the root directory
 and associated URLs might look like:
 
-```sh
+```
 .
 |-- about.md    # => http://example.com/about.html
 |-- index.html    # => http://example.com/
@@ -22,7 +22,7 @@ and associated URLs might look like:
 
 If you have a lot of pages, you can organize them into subfolders. The same subfolders that are used to group your pages in your project's source will then exist in the `_site` folder when your site builds. However, when a page has a *different* permalink set in the front matter, the subfolder at `_site` changes accordingly.
 
-```sh
+```
 .
 |-- about.md          # => http://example.com/about.html
 |-- documentation     # folder containing pages

docs/_docs/permalinks.md

@@ -16,7 +16,7 @@ For example, you might have a page on your site located at
 `/my_pages/about-me.html` and you want the output url to be `/about/`. In
 front matter of the page you would set:
 
-```
+```yaml
 ---
 permalink: /about/
 ---
@@ -46,7 +46,6 @@ For example, a permalink style of
 
 Here's the full list of placeholders available:
 
-
 <div class="mobile-side-scroller">
 <table>
   <thead>

docs/_docs/plugins/installation.md

@@ -27,12 +27,12 @@ You have 3 options for installing plugins:
    example:
 
    ```ruby
-    group :jekyll_plugins do
+   group :jekyll_plugins do
-      gem "jekyll-gist"
+     gem "jekyll-gist"
-      gem "jekyll-coffeescript"
+     gem "jekyll-coffeescript"
-      gem "jekyll-assets"
+     gem "jekyll-assets"
-      gem "another-jekyll-plugin"
+     gem "another-jekyll-plugin"
-    end
+   end
    ```
 
    Now you need to install all plugins from your Bundler group by running single command `bundle install`.

docs/_docs/plugins/tags.md

@@ -60,7 +60,7 @@ In the example above, we can place the following tag anywhere in one of our
 pages:
 
 {% raw %}
-```ruby
+```liquid
 <p>{% render_time page rendered at: %}</p>
 ```
 {% endraw %}
@@ -73,7 +73,7 @@ And we would get something like this on the page:
 
 ## Tag Blocks
 
-The `render_time` tag seen above can also be rewritten as a tag block by 
+The `render_time` tag seen above can also be rewritten as a tag block by
 inheriting the `Liquid::Block` class. Look at the example below:
 
 ```ruby
@@ -108,8 +108,8 @@ And we would still get the same output as above on the page:
 ```
 
 <div class="note info">
-  <p>In the above example, the tag block and the tag are both registered with 
+  <p>In the above example, the tag block and the tag are both registered with
-  the name <code>render_time</code> but to register a tag and a tag block using 
+  the name <code>render_time</code> but to register a tag and a tag block using
-  the same name in the same project is not recommended as this may lead to 
+  the same name in the same project is not recommended as this may lead to
   conflicts.</p>
-</div>
+</div>

docs/_docs/posts.md

@@ -58,8 +58,6 @@ I hope you like it!
   </p>
 </div>
 
-
-
 <div class="note info">
   <h5>Be aware of character sets</h5>
   <p>
@@ -102,7 +100,7 @@ Creating an index of posts on another page should be easy thanks to
 simple example of how to create a list of links to your blog posts:
 
 {% raw %}
-```html
+```liquid
 <ul>
   {% for post in site.posts %}
     <li>
@@ -166,7 +164,7 @@ post. By default this is the first paragraph of content in the post, however it
 can be customized by setting a `excerpt_separator` variable in front matter or
 `_config.yml`.
 
-```yaml
+```markdown
 ---
 excerpt_separator: <!--more-->
 ---
@@ -199,9 +197,11 @@ 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 `_drafts` folder in your site's root and create your first draft:
 
-```text
+```
-|-- _drafts/
+.
-|   |-- a-draft-post.md
+├── _drafts
+|   └── a-draft-post.md
+...
 ```
 
 To preview your site with drafts, run `jekyll serve` or `jekyll build`

docs/_docs/ruby-101.md

@@ -18,7 +18,6 @@ A gem is code you can include in Ruby projects. It allows you to package up func
 [jekyll-seo-tag](https://github.com/jekyll/jekyll-seo-tag) and
 [jekyll-archives](https://github.com/jekyll/jekyll-archives).
 
-
 ## Gemfile
 
 A `Gemfile` is a list of gems required for your site. For a simple Jekyll site it might look something like this:

docs/_docs/step-by-step/01-setup.md

@@ -6,7 +6,7 @@ position: 1
 ---
 Welcome to Jekyll's step-by-step tutorial. The goal of this tutorial is to take
 you from having some front end web development experience to building your
-first Jekyll site from scratch — not relying on the default gem-based theme. 
+first Jekyll site from scratch — not relying on the default gem-based theme.
 Let's get into it!
 
 ## Installation
@@ -18,25 +18,25 @@ instructions for your operating system.
 With Ruby setup you can install Jekyll by running the following in your
 terminal:
 
-```
+```sh
 gem install jekyll bundler
 ```
 
 To create a new `Gemfile` to list your project's dependencies run:
 
-```
+```sh
 bundle init
 ```
 
-Now edit the `Gemfile`and add jekyll as a dependency:
+Now edit the `Gemfile` and add jekyll as a dependency:
 
-```
+```ruby
 gem "jekyll"
 ```
 
 Finally run `bundle` to install jekyll for your project.
 
-You can now prefix all jekyll commands listed in this tutorial with `bundle exec` 
+You can now prefix all jekyll commands listed in this tutorial with `bundle exec`
 to make sure you use the jekyll version defined in your `Gemfile`.
 
 ## Create a site

docs/_docs/step-by-step/02-liquid.md

@@ -7,7 +7,6 @@ Liquid is where Jekyll starts to get more interesting. Liquid is a templating
 language which has three main parts: [objects](#objects), [tags](#tags) and
 [filters](#filters).
 
-
 ## Objects
 
 Objects tell Liquid where to output content. They're denoted by double curly
@@ -68,7 +67,7 @@ Now it's your turn, change the Hello World! on your page to output as lowercase:
 
 To get our changes processed by Jekyll we need to add [front matter](../03-front-matter/) to the top of the page:
 
-```markdown
+```yaml
 ---
 # front matter tells Jekyll to process Liquid
 ---

docs/_docs/step-by-step/03-front-matter.md

@@ -7,7 +7,7 @@ Front matter is a snippet of [YAML](http://yaml.org/) which sits between two
 triple-dashed lines at the top of a file. Front matter is used to set variables
 for the page, for example:
 
-```liquid
+```yaml
 ---
 my_number: 5
 ---
@@ -27,7 +27,7 @@ example to output the variable above you would use:
 Let's change the `<title>` on your site to populate using front matter:
 
 {% raw %}
-```html
+```liquid
 ---
 title: Home
 ---
@@ -44,12 +44,11 @@ title: Home
 ```
 {% endraw %}
 
-
 Note that in order for Jekyll to process any liquid tags on your page,
 you _must_ include front matter on it. The most minimal snippet of front matter
 you can include is:
 
-```liquid
+```yaml
 ---
 ---
 ```

docs/_docs/step-by-step/04-layouts.md

@@ -50,7 +50,7 @@ matter. The layout wraps around the content of the page so all you need in
 `index.html` is:
 
 {% raw %}
-```html
+```liquid
 ---
 layout: default
 title: Home
@@ -70,8 +70,7 @@ layout.
 
 Add the following to `about.md`:
 
-{% raw %}
+```markdown
-```html
 ---
 layout: default
 title: About
@@ -80,7 +79,6 @@ title: About
 
 This page tells you a little bit about me.
 ```
-{% endraw %}
 
 Open <a href="http://localhost:4000/about.html" target="_blank" data-proofer-ignore>http://localhost:4000/about.html</a>
 in your browser and view your new page.

docs/_docs/step-by-step/05-includes.md

@@ -17,14 +17,14 @@ in an `_includes` folder. Includes are useful for having a single source for
 source code that repeats around the site or for improving the readability.
 
 Navigation source code can get complex so sometimes it's nice to move it into an
-include. 
+include.
 
 ## Include usage
 
 Create a file for the navigation at `_includes/navigation.html` with the
 following content:
 
-```liquid
+```
 <nav>
   <a href="/">Home</a>
   <a href="/about.html">About</a>

docs/_docs/step-by-step/07-assets.md

@@ -8,7 +8,7 @@ them in your site folder and they’ll copy across to the built site.
 
 Jekyll sites often use this structure to keep assets organized:
 
-```sh
+```
 .
 ├── assets
 |   ├── css
@@ -38,13 +38,11 @@ to CSS baked right into Jekyll.
 
 First create a Sass file at `/assets/css/styles.scss` with the following content:
 
-{% raw %}
+```sass
-```css
 ---
 ---
 @import "main";
 ```
-{% endraw %}
 
 The empty front matter at the top tells Jekyll it needs to process the file. The
 `@import "main"` tells Sass to look for a file called `main.scss` in the sass

docs/_docs/step-by-step/08-blogging.md

@@ -39,7 +39,7 @@ The `post` layout doesn't exist so you'll need to create it at
 `_layouts/post.html` with the following content:
 
 {% raw %}
-```html
+```liquid
 ---
 layout: default
 ---
@@ -65,7 +65,7 @@ Jekyll makes posts available at `site.posts`.
 Create `blog.html` in your root (`/blog.html`) with the following content:
 
 {% raw %}
-```html
+```liquid
 ---
 layout: default
 title: Blog
@@ -139,7 +139,7 @@ golden flesh with rows of tiny, black, edible seeds. The fruit has a soft
 texture, with a sweet and unique flavor.
 ```
 
-Open <a href="http://localhost:4000" target="_blank" data-proofer-ignore>http://localhost:4000</a> and have
+Open <a href="http://localhost:4000" target="_blank" data-proofer-ignore>http://localhost:4000</a>
-a look through your blog posts.
+and have a look through your blog posts.
 
 Next we'll focus on creating a page for each post author.

docs/_docs/step-by-step/09-collections.md

@@ -60,7 +60,7 @@ collection available at `site.authors`.
 Create `staff.html` and iterate over `site.authors` to output all the staff:
 
 {% raw %}
-```html
+```liquid
 ---
 layout: default
 title: Staff
@@ -117,7 +117,7 @@ You can link to the output page using `author.url`.
 Add the link to the `staff.html` page:
 
 {% raw %}
-```html
+```liquid
 ---
 layout: default
 title: Staff
@@ -141,7 +141,7 @@ Just like posts you'll need to create a layout for authors.
 Create `_layouts/author.html` with the following content:
 
 {% raw %}
-```html
+```liquid
 ---
 layout: default
 ---
@@ -203,7 +203,7 @@ Iterate over this filtered list in `_layouts/author.html` to output the
 author's posts:
 
 {% raw %}
-```html
+```liquid
 ---
 layout: default
 ---
@@ -228,7 +228,7 @@ The posts have a reference to the author so let's link it to the author's page.
 You can do this using a similar filtering technique in `_layouts/post.html`:
 
 {% raw %}
-```html
+```liquid
 ---
 layout: default
 ---

docs/_docs/step-by-step/10-deployment.md

@@ -13,7 +13,7 @@ different environments.
 
 Create `Gemfile` in the root with the following:
 
-```
+```ruby
 source 'https://rubygems.org'
 
 gem 'jekyll'
@@ -27,7 +27,7 @@ creates `Gemfile.lock` which locks the current gem versions for a future
 When using a `Gemfile`, you'll run commands like `jekyll serve` with
 `bundle exec` prefixed. So the full command is:
 
-```bash
+```sh
 bundle exec jekyll serve
 ```
 
@@ -51,7 +51,7 @@ with SEO
 To use these first you need to add them to your `Gemfile`. If you put them
 in a `jekyll_plugins` group they'll automatically be required into Jekyll:
 
-```
+```ruby
 source 'https://rubygems.org'
 
 gem 'jekyll'
@@ -65,7 +65,7 @@ end
 
 Then add these lines to your `_config.yml`:
 
-```
+```yaml
 plugins:
   - jekyll-feed
   - jekyll-sitemap
@@ -109,7 +109,7 @@ To do this you can use [environments](/docs/configuration/environments/). You
 can set the environment by using the `JEKYLL_ENV` environment variable when
 running a command. For example:
 
-```bash
+```sh
 JEKYLL_ENV=production bundle exec jekyll build
 ```
 
@@ -130,7 +130,7 @@ on production you would do the following:
 The final step is to get the site onto a production server. The most basic way
 to do this is to run a production build:
 
-```bash
+```sh
 JEKYLL_ENV=production bundle exec jekyll build
 ```
 

docs/_docs/structure.md

@@ -4,7 +4,7 @@ permalink: /docs/structure/
 ---
 A basic Jekyll site usually looks something like this:
 
-```sh
+```
 .
 ├── _config.yml
 ├── _data

docs/_docs/themes.md

@@ -23,6 +23,7 @@ With gem-based themes, some of the site's directories (such as the `assets`, `_l
 In the case of Minima, you see only the following files in your Jekyll site directory:
 
 ```
+.
 ├── Gemfile
 ├── Gemfile.lock
 ├── _config.yml
@@ -75,33 +76,34 @@ To locate a theme's files on your computer:
 
    A Finder or Explorer window opens showing the theme's files and directories. The Minima theme gem contains these files:
 
-    ```
+   ```
-    ├── LICENSE.txt
+   .
-    ├── README.md
+   ├── LICENSE.txt
-    ├── _includes
+   ├── README.md
-    │   ├── disqus_comments.html
+   ├── _includes
-    │   ├── footer.html
+   │   ├── disqus_comments.html
-    │   ├── google-analytics.html
+   │   ├── footer.html
-    │   ├── head.html
+   │   ├── google-analytics.html
-    │   ├── header.html
+   │   ├── head.html
-    │   ├── icon-github.html
+   │   ├── header.html
-    │   ├── icon-github.svg
+   │   ├── icon-github.html
-    │   ├── icon-twitter.html
+   │   ├── icon-github.svg
-    │   └── icon-twitter.svg
+   │   ├── icon-twitter.html
-    ├── _layouts
+   │   └── icon-twitter.svg
-    │   ├── default.html
+   ├── _layouts
-    │   ├── home.html
+   │   ├── default.html
-    │   ├── page.html
+   │   ├── home.html
-    │   └── post.html
+   │   ├── page.html
-    ├── _sass
+   │   └── post.html
-    │   ├── minima
+   ├── _sass
-    │   │   ├── _base.scss
+   │   ├── minima
-    │   │   ├── _layout.scss
+   │   │   ├── _base.scss
-    │   │   └── _syntax-highlighting.scss
+   │   │   ├── _layout.scss
-    │   └── minima.scss
+   │   │   └── _syntax-highlighting.scss
-    └── assets
+   │   └── minima.scss
-        └── main.scss
+   └── assets
-     ```
+       └── main.scss
+   ```
 
 With a clear understanding of the theme's files, you can now override any theme file by creating a similarly named file in your Jekyll site directory.
 
@@ -129,7 +131,7 @@ To do this, copy the files from the theme gem's directory into your Jekyll site
 
 Then you must tell Jekyll about the plugins that were referenced by the theme. You can find these plugins in the theme's gemspec file as runtime dependencies. If you were converting the Minima theme, for example, you might see:
 
-```
+```ruby
 spec.add_runtime_dependency "jekyll-feed", "~> 0.12"
 spec.add_runtime_dependency "jekyll-seo-tag", "~> 2.6"
 ```
@@ -191,7 +193,8 @@ To install a gem-based theme:
    # This is an example, declare the theme gem you want to use here
    gem "jekyll-theme-minimal"
    ```
-  Or if you've started with the `jekyll new` command, replace `gem "minima", "~> 2.0"` with the gem you want, e.g:
+
+   Or if you've started with the `jekyll new` command, replace `gem "minima", "~> 2.0"` with the gem you want, e.g:
 
    ```diff
    # ./Gemfile
@@ -274,7 +277,7 @@ Your theme's stylesheets should be placed in your theme's `_sass` folder, again,
 
 ```
 _sass
-├── jekyll-theme-awesome.scss
+└── jekyll-theme-awesome.scss
 ```
 
 Your theme's styles can be included in the user's stylesheet using the `@import` directive.

docs/_docs/troubleshooting.md

@@ -111,7 +111,7 @@ possible to run Jekyll as a non-superuser and without having to install
 gems to system-wide locations by adding the following lines to the end
 of your `.bashrc` file:
 
-```
+```bash
 # Ruby exports
 
 export GEM_HOME=$HOME/gems
@@ -252,7 +252,7 @@ specified elsewhere.
 
 **Note: From v3.3.0 onward, Jekyll does not process `node_modules` and certain subdirectories within `vendor`, by default. But, by having an `exclude:` array defined explicitly in the config file overrides this default setting, which results in some users to encounter an error in building the site, with the following error message:**
 
-```sh
+```
     ERROR: YOUR SITE COULD NOT BE BUILT:
     ------------------------------------
     Invalid date '<%= Time.now.strftime('%Y-%m-%d %H:%M:%S %z') %>':
@@ -262,7 +262,6 @@ specified elsewhere.
 
 Adding `vendor/bundle` to the `exclude:` list will solve this problem but will lead to having other sub-directories under `/vendor/` (and also `/node_modules/`, if present) be processed to the destination folder `_site`.
 
-
 The proper solution is to incorporate the default setting for `exclude:` rather than override it completely:
 
 For versions up to `v3.4.3`, the `exclude:` setting must look like following:
@@ -281,7 +280,6 @@ exclude:
 
 From `v3.5` onward, `Gemfile` and `Gemfile.lock` are also excluded by default. So, in most cases there is no need to define another `exclude:` array in the config file. So an existing definition can either be modified as above, or removed completely, or commented out to enable easy edits in future.
 
-
 ## Markup Problems
 
 The various markup engines that Jekyll uses may have some issues. This
@@ -293,7 +291,7 @@ problems.
 Liquid version 2.0 seems to break the use of `{{ "{{" }}` in templates.
 Unlike previous versions, using `{{ "{{" }}` in 2.0 triggers the following error:
 
-```sh
+```
 '{{ "{{" }}' was not properly terminated with regexp: /\}\}/  (Liquid::SyntaxError)
 ```
 

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

@@ -120,13 +120,12 @@ such as previewing locally before pushing to GitHub Pages. Jekyll 1.0 makes
 that easier with the new `--baseurl` flag. To take advantage of this
 feature, first add the production `baseurl` to your site's `_config.yml`
 file. Then, throughout the site, prefix relative URLs
-with `{% raw %}{{ site.baseurl }}{% endraw %}`.
+with {% raw %}`{{ site.baseurl }}`{% endraw %}.
 When you're ready to preview your site locally, pass along the `--baseurl`
 flag with your local baseurl (most likely `/`) to `jekyll serve` and Jekyll
 will swap in whatever you've passed along, ensuring all your links work as
 you'd expect in both environments.
 
-
 <div class="note warning">
   <h5 markdown="1">All page and post URLs contain leading slashes</h5>
   <p markdown="1">If you use the method described above, please remember

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

@@ -36,11 +36,11 @@ When iterating over `site.collections`, ensure the above conversions are made.
 
 For `site.collections.myCollection` in Jekyll 2, you now do:
 
-```liquid
 {% raw %}
+```liquid
 {% assign myCollection = site.collections | where: "label", "myCollection" | first %}
-{% endraw %}
 ```
+{% endraw %}
 
 This is a bit cumbersome at first, but is easier than a big `for` loop.
 
@@ -83,7 +83,7 @@ Introducing: `layout`. In Jekyll 2 and below, any metadata in the layout was mer
 the `page` variable in Liquid. This caused a lot of confusion in the way the data was
 merged and some unexpected behaviour. In Jekyll 3, all layout data is accessible via `layout`
 in Liquid. For example, if your layout has `class: my-layout` in its front matter,
-then the layout can access that via `{% raw %}{{ layout.class }}{% endraw %}`.
+then the layout can access that via {% raw %}`{{ layout.class }}`{% endraw %}.
 
 ### Syntax highlighter changed
 
@@ -101,7 +101,7 @@ In Jekyll 3 and above, relative permalinks have been deprecated. If you
 created your site using Jekyll 2 and below, you may receive the following
 error when trying to **serve** or **build**:
 
-```text
+```
 Since v3.0, permalinks for pages in subfolders must be relative to the site
 source directory, not the parent directory. Check
 https://jekyllrb.com/docs/upgrading/ for more info.

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

@@ -42,7 +42,6 @@ gem update jekyll
 {% endhighlight %}
 </div>
 
-
 ## Template rendering
 
 We've slightly altered the way Jekyll parses and renders your various templates
@@ -161,6 +160,7 @@ Notes:
       end
     end
     ```
+
   * Vendors that provide a versioned Jekyll Environment Image (e.g. Docker Image, GitHub Pages, etc)
     will have to manually whitelist kramdown's extension gems in their distributions for Jekyll 4.0.
 

docs/_posts/2016-10-06-jekyll-3-3-is-here.md

@@ -38,31 +38,31 @@ new filters have you covered. When working locally, if you set your
 then `relative_url` will ensure that this baseurl is prepended to anything
 you pass it:
 
-{% highlight liquid %}
 {% raw %}
+```liquid
 {{ "/docs/assets/" | relative_url }} => /myproject/docs/assets
+```
 {% endraw %}
-{% endhighlight %}
 
 By default, `baseurl` is set to `""` and therefore yields (never set to
 `"/"`):
 
-{% highlight liquid %}
 {% raw %}
+```liquid
 {{ "/docs/assets/" | relative_url }} => /docs/assets
+```
 {% endraw %}
-{% endhighlight %}
 
 A result of `relative_url` will safely always produce a URL which is
 relative to the domain root. A similar principle applies to `absolute_url`.
 It prepends your `baseurl` and `url` values, making absolute URLs all the
 easier to make:
 
-{% highlight liquid %}
 {% raw %}
+```liquid
 {{ "/docs/assets/" | absolute_url }} => https://jekyllrb.com/myproject/docs/assets
+```
 {% endraw %}
-{% endhighlight %}
 
 ### 3. `site.url` is set by the development server
 

docs/_posts/2018-01-25-jekyll-3-7-2-released.md

@@ -46,7 +46,7 @@ The highlights being:
     Ergo, if you set a custom location for your collections, please ensure you
     move all of your collections into that directory. **This includes posts and
     drafts as well**. Your links generated by
-    `{% raw %}{% post_url %}{% endraw %}` or `{% raw %}{% link %}{% endraw %}`
+    {% raw %}`{% post_url %}`{% endraw %} or {% raw %}`{% link %}`{% endraw %}
     will adapt automatically.
 
   * We also found out that `gem "wdm"` boosts performance while directories are

docs/_tutorials/cache_api.md

@@ -64,7 +64,6 @@ is built.
 This will clear all cached objects from a particular Cache. The Cache will be
 empty, both in memory and on disk.
 
-
 ### The following methods will probably only be used in special circumstances
 
 ## cache[key] → value

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

@@ -19,6 +19,7 @@ First, let's start with a grounding in the basics. Stripping a Jekyll site down
 We'll start with a *basic Jekyll site* consisting of three files:
 
 ```
+.
 ├── _config.yml
 ├── _layouts
 │   └── default.html
@@ -28,8 +29,8 @@ We'll start with a *basic Jekyll site* consisting of three files:
 Manually create these three files in a folder called `my_jekyll_site` or whatever suits you the most, and place `default.html` inside a folder named `_layouts`.
 
 ```sh
-$ touch _config.yml index.md default.html
+touch _config.yml index.md default.html
-$ mkdir _layouts && mv default.html _layouts
+mkdir _layouts && mv default.html _layouts
 ```
 
 Fire up your favorite editor, and populate the contents of the `default.html` and `index.md` files as follows:
@@ -42,35 +43,42 @@ name: My Jekyll Website
 
 **_layouts/default.html**
 
+{% raw %}
 ```html
 <!DOCTYPE html>
 <html>
   <body>
-     {% raw %}{{ content }}{% endraw %}
+     {{ content }}
   </body>
 </html>
 ```
+{% endraw %}
 
 **index.md**
 
-```yaml
+{% raw %}
+```markdown
 ---
 title: My page
 layout: default
 ---
 
-# {% raw %}{{ page.title }}{% endraw %}
+# {{ page.title }}
 
-Content is written in [Markdown](https://learnxinyminutes.com/docs/markdown/). Plain text format allows you to focus on your **content**.
+Content is written in [Markdown](https://learnxinyminutes.com/docs/markdown/).
+Plain text format allows you to focus on your **content**.
 
 <!--
-You can use HTML elements in Markdown, such as the comment element, and they won't be affected by a markdown parser. However, if you create an HTML element in your markdown file, you cannot use markdown syntax within that element's contents.
+You can use HTML elements in Markdown, such as the comment element, and they won't
+be affected by a markdown parser. However, if you create an HTML element in your
+markdown file, you cannot use markdown syntax within that element's contents.
 -->
 ```
+{% endraw %}
 
 Now `cd` to `my_jekyll_site` and serve the site with the built-in server:
 
-```
+```sh
 cd my_jekyll_site
 jekyll serve
 ```
@@ -84,7 +92,7 @@ This is a Jekyll site at the most basic functional level. Here's what is happeni
 
   * The `_config.yml` file contains settings that Jekyll uses as it processes your site. An empty config file will use default values for building a Jekyll site. For example, to convert [Markdown](https://learnxinyminutes.com/docs/markdown/) to HTML, Jekyll will automatically use the [kramdown Markdown filter](https://rubygems.org/gems/kramdown/), without any need to specify it.
   * Jekyll looks for files with [front matter tags]({% link _docs/front-matter.md %}) (the two sets of dashed lines `---` like those in `index.md`) and processes the files (populating site variables, rendering any [Liquid](https://shopify.github.io/liquid/), and converting Markdown to HTML).
-  * Jekyll pushes the content from all pages and posts into the `{% raw %}{{ content }}{% endraw %}` variable in the layout specified (`default`) in the front matter tags.
+  * Jekyll pushes the content from all pages and posts into the {% raw %}`{{ content }}`{% endraw %} variable in the layout specified (`default`) in the front matter tags.
   * The processed files get written as `.html` files in the `_site` directory.
 
 You can read more about how Jekyll processes the files in [order of Interpretation]({% link _tutorials/orderofinterpretation.md %}).
@@ -110,21 +118,25 @@ For example, if the paths were relative on the site you copied, you'll need to e
 
 Jekyll provides some [filters](/docs/liquid/filters) to prepend a site URL before path. For example, you could preface your stylesheet like this:
 
+{% raw %}
 ```liquid
-{% raw %}{{ "/assets/style.css" | relative_url }}{% endraw %}
+{{ "/assets/style.css" | relative_url }}
 ```
+{% endraw %}
 
-The `relative_url` filter will prepend the [`baseurl`](https://byparker.com/blog/2014/clearing-up-confusion-around-baseurl/) value from your config file (as`blog` for instance) to the input. This is useful if your site is hosted at a subpath rather than at the root of the domain (for example, `http://mysite.com/blog/`).
+The `relative_url` filter will prepend the [`baseurl`](https://byparker.com/blog/2014/clearing-up-confusion-around-baseurl/) value from your config file (as `blog` for instance) to the input. This is useful if your site is hosted at a subpath rather than at the root of the domain (for example, `http://mysite.com/blog/`).
 
 You can also use an `absolute_url` filter. This filter will prepend the `url` *and* `baseurl` value to the input:
 
+{% raw %}
 ```liquid
-{% raw %}{{ "/assets/style.css" | absolute_url }}{% endraw %}
+{{ "/assets/style.css" | absolute_url }}
 ```
+{% endraw %}
 
 Again, both `url` and `baseurl` can be defined in your site's config file, like this:
 
-```
+```yaml
 url: http://mysite.com
 baseurl: /blog
 ```
@@ -141,9 +153,9 @@ In the next section, you'll blank out the content of the layout and replace it w
 
 ## 2. Identify the content part of the layout
 
-In `default.html`, find where the page content begins (usually at `h1` or `h2` tags). Replace the title that appears inside these tags with `{% raw %}{{ page.title }}{% endraw %}`.
+In `default.html`, find where the page content begins (usually at `h1` or `h2` tags). Replace the title that appears inside these tags with {% raw %}`{{ page.title }}`{% endraw %}.
 
-Remove the content part (keep everything else: navigation menu, sidebar, footer, etc.) and replace it with `{% raw %}{{ content }}{% endraw %}`.
+Remove the content part (keep everything else: navigation menu, sidebar, footer, etc.) and replace it with {% raw %}`{{ content }}`{% endraw %}.
 
 Check the layout again in your browser and make sure you didn't corrupt or alter it up by inadvertently removing a crucial `div` tag or other element. The only change should be to the title and page content, which are now blanked out or showing the placeholder tag.
 
@@ -153,7 +165,7 @@ Create a couple of files (`index.md` and `about.md`) in your root directory.
 
 In your `index.md` file, add some front matter tags containing a `title` and `layout` property, like this:
 
-```yaml
+```markdown
 ---
 title: Home
 layout: default
@@ -171,13 +183,13 @@ If you don't specify a layout in your pages, Jekyll will simply render that page
 
 Add a `_config.yml` file in your root directory. In `_config.yml`, you can optionally specify the markdown filter you want. By default, [kramdown](https://kramdown.gettalong.org/) is used (without the need to specify it). If no other filter is specified, your config file will automatically apply the following as a default setting:
 
-```
+```yaml
 markdown: kramdown
 ```
 
 You can also specify [some options](https://kramdown.gettalong.org/converter/html.html) for kramdown to make it behave more like [GitHub Flavored Markdown (GFM)](https://github.github.com/gfm/):
 
-```
+```yaml
 kramdown:
  input: GFM
  auto_ids: true
@@ -193,7 +205,7 @@ You've now extracted your content out into separate files and defined a common l
 
 You could define any number of layouts you want for pages. Then just identify the layout you want that particular page to use. For example:
 
-```
+```yaml
 ---
 title: Sample page
 layout: homepage
@@ -206,7 +218,7 @@ You can even set [default front matter tags](/docs/configuration/front-matter-de
 
 ## 6. Configure site variables
 
-You already configured the page title using `{% raw %}{{ page.title }}{% endraw %}` tags. But there are more `title` tags to populate. Pages also have a [`title`](https://moz.com/learn/seo/title-tag) tag that appears in the browser tab or window. Typically you put the page title followed by the site title here.
+You already configured the page title using {% raw %}`{{ page.title }}`{% endraw %} tags. But there are more `title` tags to populate. Pages also have a [`title`](https://moz.com/learn/seo/title-tag) tag that appears in the browser tab or window. Typically you put the page title followed by the site title here.
 
 In your `default.html` layout, look for the `title` tags below your `head` tags:
 
@@ -216,13 +228,15 @@ In your `default.html` layout, look for the `title` tags below your `head` tags:
 
 Insert the following site variables:
 
+{% raw %}
+```liquid
+<title>{{ page.title }} | {{ site.title }}</title>
 ```
-{% raw %}<title>{{ page.title }} | {{ site.title }}</title>{% endraw %}
+{% endraw %}
-```
 
 Open `_config.yml` and add a `title` property for your site's name.
 
-```
+```yaml
 title: ACME Website
 ```
 
@@ -247,7 +261,7 @@ Add some posts in a `_posts` folder following the standard `YYYY-MM-DD-title.md`
 
 In each post, add some basic content:
 
-```
+```markdown
 ---
 title: My First Post
 layout: default
@@ -258,43 +272,44 @@ Some sample content...
 
 Now let's create a layout that will display the posts. Create a new file in `_layouts` called `home.html` and add the following logic:
 
-```
+{% raw %}
+```liquid
 ---
 layout: default
 ---
 
-{% raw %}{{ content }}
+{{ content }}
 <ul class="myposts">
 {% for post in site.posts %}
     <li><a href="{{ post.url }}">{{ post.title}}</a>
     <span class="postDate">{{ post.date | date: "%b %-d, %Y" }}</span>
     </li>
 {% endfor %}
-</ul>{% endraw %}
+</ul>
 ```
+{% endraw %}
 
 Create a file called `blog.md` in your root directory and specify the `home` layout:
 
-```
+```yaml
 ---
 title: Blog
 layout: home
 ---
 ```
 
-In this case, contents of `blog.md` will be pushed into the `{% raw %}{{ content }}{% endraw %}` tag in the `home` layout. Then the `home` layout will be pushed into the `{% raw %}{{ content }}{% endraw %}` tag of the `default` layout.
+In this case, contents of `blog.md` will be pushed into the {% raw %}`{{ content }}`{% endraw %} tag in the `home` layout. Then the `home` layout will be pushed into the {% raw %}`{{ content }}`{% endraw %} tag of the `default` layout.
-
 
 ### How layouts work
 
-When a layout specifies another layout, it means the content of the first layout will be stuffed into the `{% raw %}{{ content }}{% endraw %}` tag of the second layout. As an analogy, think of Russian dolls that fit into each other. Each layout fits into another layout that it specifies.
+When a layout specifies another layout, it means the content of the first layout will be stuffed into the {% raw %}`{{ content }}`{% endraw %} tag of the second layout. As an analogy, think of Russian dolls that fit into each other. Each layout fits into another layout that it specifies.
 
 The following diagram shows how layouts work in Jekyll:
 
 <img src="../../img/jekylllayoutconcept.png" alt="Concept of Jekyll layouts" />
 
 {: .image-description}
-In this example, the content from a Markdown document `document.md` that specifies `layout: docs` gets pushed into the `{% raw %}{{ content }}{% endraw %}` tag of the layout file `docs.html`. Because the `docs` layout itself specifies `layout: page`, the content from `docs.html` gets pushed into the `{% raw %}{{ content }}{% endraw %}` tag in the layout file `page.html`. Finally because the `page` layout specifies `layout: default`, the content from `page.html` gets pushed into the `{% raw %}{{ content }}{% endraw %}` tag of the layout file `default.html`.
+In this example, the content from a Markdown document `document.md` that specifies `layout: docs` gets pushed into the {% raw %}`{{ content }}`{% endraw %} tag of the layout file `docs.html`. Because the `docs` layout itself specifies `layout: page`, the content from `docs.html` gets pushed into the {% raw %}`{{ content }}`{% endraw %} tag in the layout file `page.html`. Finally because the `page` layout specifies `layout: default`, the content from `page.html` gets pushed into the {% raw %}`{{ content }}`{% endraw %} tag of the layout file `default.html`.
 
 You don't need multiple layouts. You could just use one: `default`. You have options for how you design your site. In general, it's common to define one layout for pages and another layout for posts, but for both of these layouts to inherit the `default` template (which usually defines the top and bottom parts of the site).
 
@@ -302,7 +317,7 @@ In your browser, go to `blog.html` and see the list of posts.
 Note that you don't have to use the method described here. You could have simply added the `for` loop to any page, such as `index.md`, to display these posts. But given that you may have more complex logic for other features, it can be helpful to store your logic in templates separate from the page area where you frequently type your content.
 
 {: .note .info}
-At minimum, a layout should contain `{% raw %}{{ content }}{% endraw %}`, which acts as a receiver for the *content* to be rendered.
+At minimum, a layout should contain {% raw %}`{{ content }}`{% endraw %}, which acts as a receiver for the *content* to be rendered.
 
 ### For loops
 
@@ -310,15 +325,17 @@ By the way, let's pause here to look at the `for` loop logic a little more close
 
 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:
 
+{% raw %}
 ```liquid
-{% raw %}<ul class="myposts">
+<ul class="myposts">
 {% for post in site.categories.podcasts limit:3 %}
     <li><a href="{{ post.url }}">{{ post.title}}</a>
     <span class="postDate">{{ post.date | date: "%b %-d, %Y" }}</span>
     </li>
 {% endfor %}
-</ul>{% endraw %}
+</ul>
 ```
+{% endraw %}
 
 This loop would get the latest three posts that have a category called `podcasts` in the front matter.
 
@@ -330,18 +347,20 @@ In this tutorial, we'll assume you've got a simple list of pages you want to gen
 
 Identify the part of your code where the list of pages appears. Usually this is a `<ul>` element with various child `<li>` elements. Replace the code with the following:
 
-```html
+{% raw %}
-{% raw %}<ul>
+```liquid
+<ul>
   {% assign mypages = site.pages | sort: "order" %}
     {% for page in mypages %}
     <li><a href="{{ page.url | absolute_url }}">{{ page.title }}</a></li>
     {% endfor %}
-  </ul>{% endraw %}
+</ul>
 ```
+{% endraw %}
 
 This example assumes each page would have front matter containing both a `title` and `order` property like this:
 
-```
+```yaml
 ---
 title: My page
 order: 2
@@ -372,13 +391,15 @@ You can store additional properties for each item in this data file as desired.
 
 To print the list of pages from the data file, use code like this:
 
-```html
+{% raw %}
-{% raw %}<ul>
+```liquid
+<ul>
     {% for link in site.data.navigation %}
     <li><a href="{{ link.url }}">{{ link.title }}</a></li>
     {% endfor %}
-</ul>{% endraw %}
+</ul>
 ```
+{% endraw %}
 
 If you have more sophisticated requirements around navigation, such as when building a documentation site, see the [detailed tutorial on navigation](/tutorials/navigation/).
 
@@ -392,9 +413,11 @@ Remove your sidebar code from your `default.html` layout and insert it into the
 
 Where the sidebar code previously existed in `default.html`, pull in your "include" like this:
 
+{% raw %}
 ```liquid
-{% raw %}{% include sidebar.html %}{% endraw %}
+{% include sidebar.html %}
 ```
+{% endraw %}
 
 You can break up other elements of your theme like this, such as your header or footer. Then you can apply these common elements to other layout files. This way you won't have duplicate code.
 
@@ -402,12 +425,13 @@ You can break up other elements of your theme like this, such as your header or
 
 Your Jekyll site needs an RSS feed. Here's the [basic RSS feed syntax](http://www.w3schools.com/xml/xml_rss.asp). To create an RSS file in Jekyll, create a file called `feed.xml` in your root directory and add the following:
 
-```xml
+{% raw %}
+```liquid
 ---
 layout: null
 ---
 
-{% raw %}<?xml version="1.0" encoding="UTF-8" ?>
+<?xml version="1.0" encoding="UTF-8" ?>
 <rss version="2.0">
 
     <channel>
@@ -431,8 +455,9 @@ layout: null
         </item>
         {% endfor %}
     </channel>
-</rss>{% endraw %}
+</rss>
 ```
+{% endraw %}
 
 Make sure your `_config.yml` file has properties for `title`, `url`, and `description`.
 
@@ -440,9 +465,11 @@ This code uses a `for` loop to look through your last 20 posts. The content from
 
 In your `default.html` layout, look for a reference to the RSS or Atom feed in your header, and replace it with a reference to the file you just created. For example:
 
-```html
+{% raw %}
-<link rel="alternate" type="application/rss+xml"  href="{% raw %}{{ site.url }}{% endraw %}/feed.xml" title="{% raw %}{{ site.title }}{% endraw %}">
+```liquid
+<link rel="alternate" type="application/rss+xml"  href="{{ site.url }}/feed.xml" title="{{ site.title }}">
 ```
+{% endraw %}
 
 You can also auto-generate your posts feed by adding a gem called [`jekyll-feed`](https://help.github.com/articles/atom-rss-feeds-for-github-pages/). This gem will also work on GitHub Pages.
 
@@ -450,13 +477,14 @@ You can also auto-generate your posts feed by adding a gem called [`jekyll-feed`
 
 Finally, add a [site map](https://www.sitemaps.org/protocol.html). Create a `sitemap.xml` file in your root directory and add this code:
 
-```xml
+{% raw %}
+```liquid
 ---
 layout: null
 search: exclude
 ---
 
-{% raw %}<?xml version="1.0" encoding="UTF-8"?>
+<?xml version="1.0" encoding="UTF-8"?>
 <urlset xmlns="http://www.sitemaps.org/schemas/sitemap/0.9">
 
     {% for page in site.pages %}
@@ -477,8 +505,9 @@ search: exclude
     </url>
     {% endfor %}
 
-</urlset>{% endraw %}
+</urlset>
 ```
+{% endraw %}
 
 Again, we're using a `for` loop here to iterate through all posts and pages to add them to the sitemap.
 
@@ -501,7 +530,7 @@ As you integrate code for these services, note that **if a page in your Jekyll s
 
 If you do want Jekyll to process some page content (for example, to populate a variable that you define in your site's config file), just add front matter tags to the page. If you don't want any layout applied to the page, specify `layout: null` like this:
 
-```
+```yaml
 ---
 layout: null
 ---

docs/_tutorials/custom-404-page.md

@@ -6,7 +6,6 @@ title: Custom 404 Page
 
 You can easily serve custom 404 error pages with Jekyll to replace the default **Error 404 -- File Not Found** page displayed when one tries to access a broken link on your site.
 
-
 ## On GitHub Pages
 
 Any `404.html` at the **root of your `_site` directory** will be served automatically by GitHub Pages and the local WEBrick development server.
@@ -48,7 +47,6 @@ Where the path is relative to your site's domain.
 
 More info on configuring Apache Error Pages can found in [official documentation](https://httpd.apache.org/docs/current/mod/core.html#errordocument).
 
-
 ## Hosting on Nginx server
 
 The procedure is just as simple as configuring Apache servers, but slightly different.
@@ -63,6 +61,7 @@ server {
   }
 }
 ```
+
 If the `server` block already exists, only add the code inside the `server` block given above.
 The `location` directive prevents users from directly browsing the 404.html page.
 

docs/_tutorials/index.md

@@ -31,5 +31,3 @@ We welcome your tutorial contributions. To add your tutorial:
 6. Follow the regular git workflow to submit the pull request.
 
 When you submit your pull request, the Jekyll documentation team will review your contribution and either merge it or suggest edits.
-
-

docs/_tutorials/navigation.md

@@ -371,12 +371,14 @@ For more information, see [Expressions and Variables](https://github.com/Shopify
 In addition to inserting items from the YAML data file into your list, you also usually want to highlight the current link if the user is viewing that page. You do this by inserting an `active` class for items that match the current page URL.
 
 **CSS**
+
 ```css
 .result li.active a {
     color: lightgray;
     cursor: default;
-  }
+}
 ```
+
 **Liquid**
 
 {% raw %}
@@ -408,13 +410,14 @@ In addition to inserting items from the YAML data file into your list, you also
 
 In this case, assume `Deployment` is the current page.
 
-To make sure the `item.url` (stored in the YAML file) matches the `page.url`, it can be helpful to print the `{% raw %}{{ page.url }}{% endraw %}` to the page.
+To make sure the `item.url` (stored in the YAML file) matches the `page.url`, it can be helpful to print the {% raw %}`{{ page.url }}`{% endraw %} to the page.
 
 ## Scenario 7: Including items conditionally
 
 You might want to include items conditionally in your list. For example, maybe you have multiple site outputs and only want to include the sidebar item for certain outputs. You can add properties in each list item and then use those properties to conditionally include the content.
 
 **YAML**
+
 ```yaml
 docs2_list_title: ACME Documentation
 docs2:
@@ -588,7 +591,7 @@ Let's walk through the code. First, we assign a variable (`mydocs`) to the colle
 
 The `group_by` filter groups the collection content by `category`. More specifically, the `group_by` filter converts `mydocs` into an array with `name`, `items`, and `size` properties, somewhat like this:
 
-```yaml
+```json
 [
   {"name": "getting-started", "items": [Sample 1, Sample 2],"size": 2},
   {"name": "configuration", "items": [Topic 1, Topic 2], "size": 2},

docs/_tutorials/orderofinterpretation.md

@@ -17,13 +17,13 @@ Jekyll converts your site in the following order:
 1. **Site variables**. Jekyll looks across your files and populates [site variables]({% link _docs/variables.md %}), such as `site`, `page`, `post`, and collection objects. (From these objects, Jekyll determines the values for permalinks, tags, categories, and other details.)
 
 2. **Liquid**. Jekyll processes any [Liquid](https://github.com/Shopify/liquid) formatting in pages that contain [front matter]({% link _docs/front-matter.md %}). You can identify Liquid as follows:
-   * **Liquid tags** start with `{% raw %}{%{% endraw %}` and end with a `{% raw %}%}{% endraw %}`. For example: `{% raw %}{% highlight %}{% endraw %}` or `{% raw %}{% seo %}{% endraw %}`. Tags can define blocks or be inline. Block-defining tags will also come with a corresponding end tag — for example, `{% raw %}{% endhighlight %}{% endraw %}`.
+   * **Liquid tags** start with {% raw %}`{%`{% endraw %} and end with a {% raw %}`%}`{% endraw %}. For example: {% raw %}`{% highlight %}`{% endraw %} or {% raw %}`{% seo %}`{% endraw %}. Tags can define blocks or be inline. Block-defining tags will also come with a corresponding end tag — for example, {% raw %}`{% endhighlight %}`{% endraw %}.
-   * **Liquid variables** start and end with double curly braces. For example: `{% raw %}{{ site.myvariable }}{% endraw %}` or `{% raw %}{{ content }}{% endraw %}`.
+   * **Liquid variables** start and end with double curly braces. For example: {% raw %}`{{ site.myvariable }}`{% endraw %} or {% raw %}`{{ content }}`{% endraw %}.
-   * **Liquid filters** start with a pipe character (`|`) and can only be used within **Liquid variables** after the variable string. For example: the `relative_url` filter in `{% raw %}{{ "css/main.css" | relative_url }}{% endraw %}`.
+   * **Liquid filters** start with a pipe character (`|`) and can only be used within **Liquid variables** after the variable string. For example: the `relative_url` filter in {% raw %}`{{ "css/main.css" | relative_url }}`{% endraw %}.
 
 3. **Markdown**. Jekyll converts Markdown to HTML using the Markdown filter specified in your config file. Files must have a Markdown file extension and front matter in order for Jekyll to convert them.
 
-4. **Layout**. Jekyll pushes content into the layouts specified by the page's front matter (or as specified in the config file). The content from each page gets pushed into the `{% raw %}{{ content }}{% endraw %}` tags within the layouts.
+4. **Layout**. Jekyll pushes content into the layouts specified by the page's front matter (or as specified in the config file). The content from each page gets pushed into the {% raw %}`{{ content }}`{% endraw %} tags within the layouts.
 
 5. **Files**. Jekyll writes the generated content into files in the [directory structure]({% link _docs/structure.md %}) in `_site`. Pages, posts, and collections get structured based on their [permalink]({% link _docs/permalinks.md %}) setting. Directories that begin with `_` (such as `_includes` and `_data`) are usually hidden in the output.
 
@@ -115,7 +115,7 @@ This won't work because the `assign` tag is only available during the Liquid ren
 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
+```javascript
 <button onclick="someFunction()">Click me</button>
 
 <p id="intro"></p>
@@ -129,7 +129,7 @@ function someFunction() {
 ```
 {% endraw %}
 
-When Jekyll builds the site, this `someContent` property populates the script's values, converting `{% raw %}{{ page.someContent }}{% endraw %}` to `"This is some content"`.
+When Jekyll builds the site, this `someContent` property populates the script's values, converting {% raw %}`{{ page.someContent }}`{% endraw %} to `"This is some content"`.
 
 The key to remember is that Liquid renders when Jekyll builds your site. Liquid is not available at run-time in the browser when a user executes an event.
 

docs/_tutorials/using-jekyll-with-bundler.md

@@ -105,4 +105,3 @@ _site/
 .bundle/
 vendor/
 ```
-

docs/_tutorials/video-walkthroughs.md

@@ -31,5 +31,3 @@ title: Video Walkthroughs
 17. [Data Files](https://www.youtube.com/watch?v=M6b0KmLB-pM&list=PLLAZ4kZ9dFpOPV5C5Ay0pHaa0RJFhcmcB&index=17)
 18. [Static Files](https://www.youtube.com/watch?v=knWjmVlVpso&index=18&list=PLLAZ4kZ9dFpOPV5C5Ay0pHaa0RJFhcmcB)
 19. [Hosting on Github Pages](https://www.youtube.com/watch?v=fqFjuX4VZmU&list=PLLAZ4kZ9dFpOPV5C5Ay0pHaa0RJFhcmcB&index=19)
-
-