trim plugins page, clarify intention of templates (#6311)

Merge pull request 6311

docs/_docs/plugins.md

@@ -31,21 +31,26 @@ Jekyll generates your site.
 values of the gem names of the plugins you'd like to use. An example:
 
 
-        plugins: [jekyll-coffeescript, jekyll-watch, jekyll-assets]
+        plugins:
+          - jekyll-gist
+          - jekyll-coffeescript
+          - jekyll-assets
+          - another-jekyll-plugin
         # This will require each of these plugins automatically.
 
-    Then install your plugins using `gem install jekyll-coffeescript jekyll-watch jekyll-assets`
+    Then install your plugins using `gem install jekyll-gist jekyll-coffeescript jekyll-assets another-jekyll-plugin`
 
 3. Add the relevant plugins to a Bundler group in your `Gemfile`. An
     example:
 
         group :jekyll_plugins do
-          gem "my-jekyll-plugin"
+          gem "jekyll-gist"
+          gem "jekyll-coffeescript"
+          gem "jekyll-assets"
           gem "another-jekyll-plugin"
         end
 
-    Now you need to install all plugins from your Bundler group by running single command `bundle install`
+    Now you need to install all plugins from your Bundler group by running single command `bundle install`.
-
 
 <div class="note info">
   <h5>
@@ -59,7 +64,7 @@ values of the gem names of the plugins you'd like to use. An example:
   </p>
 </div>
 
-In general, plugins you make will fall into one of five categories:
+In general, plugins you make will fall broadly into one of five categories:
 
 1. [Generators](#generators)
 2. [Converters](#converters)
@@ -67,6 +72,8 @@ In general, plugins you make will fall into one of five categories:
 4. [Tags](#tags)
 5. [Hooks](#hooks)
 
+See the bottom of the page for a [list of available plugins](#available-plugins)
+
 ## Generators
 
 You can create a generator when you need Jekyll to create additional content
@@ -810,6 +817,9 @@ LESS.js files during generation.
 
 #### Tags
 
+You can find a few useful plugins at the following locations:
+
+- [Jekyll-gist](https://github.com/jekyll/jekyll-gist): Use the `gist` tag to easily embed a GitHub Gist onto your site. This works with public or secret gists.
 - [Asset Path Tag](https://github.com/samrayner/jekyll-asset-path-plugin) by [Sam Rayner](http://www.samrayner.com/): Allows organisation of assets into subdirectories by outputting a path for a given file relative to the current post or page.
 - [Delicious Plugin by Christian Hellsten](https://github.com/christianhellsten/jekyll-plugins): Fetches and renders bookmarks from delicious.com.
 - [Ultraviolet Plugin by Steve Alex](https://gist.github.com/480380): Jekyll tag for the [Ultraviolet](https://github.com/grosser/ultraviolet) code highligher.
@@ -930,14 +940,6 @@ LESS.js files during generation.
 - [jekyll-numbered-headings](https://github.com/muratayusuke/jekyll-numbered-headings): Adds ordered number to headings.
 - [jekyll-pre-commit](https://github.com/mpchadwick/jekyll-pre-commit): A framework for running checks against your posts using a git pre-commit hook before you publish them.
 
-#### Editors
-
-- [sublime-jekyll](https://github.com/23maverick23/sublime-jekyll): A Sublime Text package for Jekyll static sites. This package should help creating Jekyll sites and posts easier by providing access to key template tags and filters, as well as common completions and a current date/datetime command (for dating posts). You can install this package manually via GitHub, or via [Package Control](https://packagecontrol.io/packages/Jekyll).
-- [vim-jekyll](https://github.com/parkr/vim-jekyll): A vim plugin to generate
-  new posts and run `jekyll build` all without leaving vim.
-- [markdown-writer](https://atom.io/packages/markdown-writer): An Atom package for Jekyll. It can create new posts/drafts, manage tags/categories, insert link/images and add many useful key mappings.
-- [Wordpress2Jekyll](https://wordpress.org/plugins/wp2jekyll/): A Wordpress plugin that allows you to use Wordpress as your editor and (automatically) export content in to Jekyll. WordPress2Jekyll attempts to marry these two systems together in order to make a site that can be easily managed from all devices.
-
 <div class="note info">
   <h5>Jekyll Plugins Wanted</h5>
   <p>

docs/_docs/resources.md

@@ -5,6 +5,14 @@ permalink: /docs/resources/
 
 Jekyll’s growing use is producing a wide variety of tutorials, frameworks, extensions, examples, and other resources that can be very helpful. Below is a collection of links to some of the most popular Jekyll resources.
 
+#### Editors
+
+- [sublime-jekyll](https://github.com/23maverick23/sublime-jekyll): A Sublime Text package for Jekyll static sites. This package should help creating Jekyll sites and posts easier by providing access to key template tags and filters, as well as common completions and a current date/datetime command (for dating posts). You can install this package manually via GitHub, or via [Package Control](https://packagecontrol.io/packages/Jekyll).
+- [vim-jekyll](https://github.com/parkr/vim-jekyll): A vim plugin to generate
+  new posts and run `jekyll build` all without leaving vim.
+- [markdown-writer](https://atom.io/packages/markdown-writer): An Atom package for Jekyll. It can create new posts/drafts, manage tags/categories, insert link/images and add many useful key mappings.
+- [Wordpress2Jekyll](https://wordpress.org/plugins/wp2jekyll/): A Wordpress plugin that allows you to use Wordpress as your editor and (automatically) export content in to Jekyll. WordPress2Jekyll attempts to marry these two systems together in order to make a site that can be easily managed from all devices.
+
 ### Useful Guides
 
 - [Jekyll Tips](http://jekyll.tips) is a set of resources created by [CloudCannon](https://cloudcannon.com) to help folks get up and running with Jekyll. They cover all skill levels, and even include some great video tutorials.

docs/_docs/templates.md

@@ -6,8 +6,9 @@ permalink: /docs/templates/
 Jekyll uses the [Liquid](https://shopify.github.io/liquid/) templating language to
 process templates. All of the standard Liquid [tags](https://shopify.github.io/liquid/tags/control-flow/) and
 [filters](https://shopify.github.io/liquid/filters/abs/) are
-supported. Jekyll even adds a few handy filters and tags of its own to make
+supported. To make common tasks easier, Jekyll even adds a few handy filters
-common tasks easier.
+and tags of its own, all of which you can find on this page. Jekyll even lets
+you come up with your own tags via plugins.
 
 ## Filters
 
@@ -418,6 +419,11 @@ The default is `default`. They are as follows (with what they filter):
 
 ## Tags
 
+* [Includes](#includes)
+* [Code snippet highlighting](#code-snippet-highlighting)
+* [Linking to pages, collections and posts (the new and improved way)](#links)
+* [Linking to posts (the old way)](#linking-to-posts)
+
 ### Includes
 
 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:
@@ -488,27 +494,6 @@ site. If you use `linenos`, you might want to include an additional CSS class
 definition for the `.lineno` class in `syntax.css` to distinguish the line
 numbers from the highlighted code.
 
-### Gist
-
-Use the `gist` tag to easily embed a GitHub Gist onto your site. This works
-with public or secret gists:
-
-```liquid
-{% raw %}
-{% gist parkr/931c1c8d465a04042403 %}
-{% endraw %}
-```
-
-You may also optionally specify the filename in the gist to display:
-
-```liquid
-{% raw %}
-{% gist parkr/931c1c8d465a04042403 jekyll-private-gist.markdown %}
-{% endraw %}
-```
-
-To use the `gist` tag, you'll need to add the
-[jekyll-gist](https://github.com/jekyll/jekyll-gist) gem to your project.
 
 ## Links
 
@@ -546,7 +531,7 @@ For example, suppose you're creating a link in `page_a.md` (stored in `pages/fol
 
 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` 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).
+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.