Merge pull request #5694 from tomjohnson1492/patch-8

Merge pull request 5694

docs/_docs/templates.md

@@ -420,56 +420,15 @@ The default is `default`. They are as follows (with what they filter):
 
 ### Includes
 
-If you have small page fragments that you wish to include in multiple places on
-your site, you can use the `include` tag.
+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:
 
 ```liquid
 {% raw %}{% include footer.html %}{% endraw %}
 ```
 
-Jekyll expects all include files to be placed in an `_includes` directory at the
-root of your source directory. This will embed the contents of
-`<source>/_includes/footer.html` into the calling file.
+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.
 
-<div class="note">
-  <h5>ProTip™: Use variables as file name</h5>
-  <p>
-
-    The name of the file you wish to embed can be literal (as in the example above),
-    or you can use a variable, using liquid-like variable syntax as in
-    <code>{% raw %}{% include {{my_variable}} %}{% endraw %}</code>.
-
-  </p>
-</div>
-
-You can also pass parameters to an include. Omit the quotation marks to send a variable's value. Liquid curly brackets should not be used here:
-
-```liquid
-{% raw %}{% include footer.html param="value" variable-param=page.variable %}{% endraw %}
-```
-
-These parameters are available via Liquid in the include:
-
-```liquid
-{% raw %}{{ include.param }}{% endraw %}
-```
-
-#### Including files relative to another file
-
-You can also choose to include file fragments relative to the current file:
-
-```liquid
-{% raw %}{% 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,
-if `_posts/2014-09-03-my-file.markdown` uses the `include_relative` tag, the included file
-must be within the `_posts` directory, or one of its subdirectories. You cannot include
-files in other locations.
-
-All the other capabilities of the `include` tag are available to the `include_relative` tag,
-such as using variables.
+For more advanced information on using includes, see [Includes](../includes).
 
 ### Code snippet highlighting
 
@@ -529,13 +488,35 @@ 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.
 
-### Link
+### Gist
 
-If you want to include a link to a collection's document, a post, a page
-or a file the `link` tag will generate the correct permalink URL for the path
-you specify.
+Use the `gist` tag to easily embed a GitHub Gist onto your site. This works
+with public or secret gists:
 
-You must include the file extension when using the `link` tag.
+```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
+
+### Linking to pages {#link}
+
+To link to a post, a page, collection item, or file, the `link` tag will generate the correct permalink URL for the path you specify. For example, if you use the `link` tag to link to `mypage.html`, even if you change your permalink style to include the file extension or omit it, the URL formed by the `link` tag will always be valid.
+
+You must include the file's original extension when using the `link` tag. Here are some examples:
 
 ```liquid
 {% raw %}
@@ -546,7 +527,7 @@ You must include the file extension when using the `link` tag.
 {% endraw %}
 ```
 
-You can also use this tag to create a link in Markdown as follows:
+You can also use the `link` tag to create a link in Markdown as follows:
 
 ```liquid
 {% raw %}
@@ -557,19 +538,29 @@ You can also use this tag to create a link in Markdown as follows:
 {% endraw %}
 ```
 
-### Post URL
+(Including `{% raw %}{{ site.baseurl }}{% endraw %}` is optional &mdash; it depends on whether you want to preface the page URL with the `baseurl` value.)
+
+The path to the post, page, or collection is defined as the path relative to the root directory (where your config file is) to the file, not the path from your existing page to the other page.
+
+For example, suppose you're creating a link `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 would like 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.
+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).
+
+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
+
+If you want like 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 %}
 {{ site.baseurl }}{% post_url 2010-07-21-name-of-post %}
 {% endraw %}
 ```
 
-If you organize your posts in subdirectories, you need to include subdirectory
-path to the post:
+If you organize your posts in subdirectories, you need to include subdirectory path to the post:
 
 ```liquid
 {% raw %}
@@ -586,25 +577,3 @@ You can also use this tag to create a link to a post in Markdown as follows:
 [Name of Link]({{ site.baseurl }}{% post_url 2010-07-21-name-of-post %})
 {% endraw %}
 ```
-
-### 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.