dan
/
jekyll
1
0
Fork 0
Code Issues Pull Requests Packages Projects Releases Wiki Activity

Improve template docs 

See https://github.com/jekyll/jekyll/pull/5630 for more details on the update. 

@jekyll/documentation
@DirtyF
This commit is contained in:
Tom Johnson 2016-12-25 20:37:24 -08:00 committed by GitHub
parent 52c2645abb
commit 9e1c613818
1 changed files with 71 additions and 102 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

173
docs/_docs/templates.md
View File

@ -421,56 +421,15 @@ The default is `default`. They are as follows (with what they filter):
### Includes ### Includes
If you have small page fragments that you wish to include in multiple places on If you have small page fragments that you want to include in multiple places on your site, you can use the `include` tag:
your site, you can use the `include` tag.
```liquid ```liquid
{% raw %}{% include footer.html %}{% endraw %} {% raw %}{% include footer.html %}{% endraw %}
``` ```
Jekyll expects all include files to be placed in an `_includes` directory at the 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.
root of your source directory. This will embed the contents of
`<source>/_includes/footer.html` into the calling file.
<div class="note"> For more advanced information on using includes, see [Includes](../includes).
<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.
### Code snippet highlighting ### Code snippet highlighting
@ -530,64 +489,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 definition for the `.lineno` class in `syntax.css` to distinguish the line
numbers from the highlighted code. numbers from the highlighted code.
### Link
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.
You must include the file extension when using the `link` tag.
```liquid
{% raw %}
{{ 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 %}
```
You can also use this tag to create a link in Markdown as follows:
```liquid
{% raw %}
[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 %}
```
### Post URL
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.
```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:
```liquid
{% raw %}
{{ site.baseurl }}{% post_url /subdir/2010-07-21-name-of-post %}
{% 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 %}
[Name of Link]({{ site.baseurl }}{% post_url 2010-07-21-name-of-post %})
{% endraw %}
```
### Gist ### Gist
Use the `gist` tag to easily embed a GitHub Gist onto your site. This works Use the `gist` tag to easily embed a GitHub Gist onto your site. This works
@ -609,3 +510,71 @@ You may also optionally specify the filename in the gist to display:
To use the `gist` tag, you'll need to add the To use the `gist` tag, you'll need to add the
[jekyll-gist](https://github.com/jekyll/jekyll-gist) gem to your project. [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 %}
{{ 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 %}
```
You can also use the `link` tag to create a link in Markdown as follows:
```liquid
{% raw %}
[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 %}
```
Including `{% raw %}{{site.baseurl}}{% endraw %}` is optional &mdash; it depends on whether you want the link to be absolute or root-relative.
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.
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:
```liquid
{% raw %}
{{ site.baseurl }}{% post_url /subdir/2010-07-21-name-of-post %}
{% 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 %}
[Name of Link]({{ site.baseurl }}{% post_url 2010-07-21-name-of-post %})
{% endraw %}
```