[site] Document `link` Liquid tag #5182

Merged
merged 3 commits into from Aug 7, 2016

Projects

None yet

3 participants

@DirtyF
Member
DirtyF commented Aug 2, 2016 edited

Following #4624

Documentation for new link tag introduced in v3.2.0

cc @jekyll/documentation

@DirtyF DirtyF [docs] Document link Liquid tag
bf8c15f
@parkr
Member
parkr commented Aug 2, 2016

@DirtyF I like it! A couple thoughts:

  1. Should this go above post_url as it's a superset of its functionality?
  2. Should we show an example with linking to a page or post? It works with everything AFAIR.
@parkr parkr added the documentation label Aug 2, 2016
@DirtyF
Member
DirtyF commented Aug 2, 2016 edited

@parkr Done but you should know that It does not seem to work with everything yet.

One can link to collection's document or a post but I didn't manage to link to a page.

For example on the jekyll website, if I try to link to the help index page:
{% link help/index.md %}

Jekyll will throw an error:
Liquid Exception: Could not find document 'help/index.md' in tag 'link'. Make sure the document exists and the path is correct.

Update : fixed with #5199

@DirtyF DirtyF [docs] link tag example for a post
* put link tag before post_url
* example of link to a post with link tag
d5e9675
@jeffkole jeffkole added a commit to jeffkole/jekyll that referenced this pull request Aug 3, 2016
@jeffkole jeffkole Adds ability to link to all files
Fixes request made in #4624 and bug found in #5182
82d6657
@DirtyF DirtyF add more link tag usage examples
50854d2
@DirtyF
Member
DirtyF commented Aug 4, 2016

@parkr Documentation has been updated as you asked.

depends on #5199

@parkr
Member
parkr commented Aug 7, 2016

depends on #5199

Can you mention in the documentation that this is unreleased?

@parkr parkr merged commit 50854d2 into jekyll:master Aug 7, 2016

1 of 3 checks passed

continuous-integration/appveyor/pr AppVeyor build failed
Details
jekyll/lgtm Awaiting approval from at least 2 maintainers.
continuous-integration/travis-ci/pr The Travis CI build passed
Details
@parkr parkr added a commit that referenced this pull request Aug 7, 2016
@parkr parkr templates.md: {% link %} tag only accepts collection documents
Remove examples of pages/static file links until it's released.
#5182 #5199
ab4abb1
@parkr parkr added a commit that referenced this pull request Aug 7, 2016
@parkr parkr Update history to reflect merge of #5182
[ci skip]
de64768
@DirtyF DirtyF deleted the DirtyF:doc-link-tag branch Aug 7, 2016
@tomjohnson1492
Contributor

In looking at the Templates page, it's unclear how the Post URL section that immediately follows the Link section differs. Does Link provide a way to link to a collection that was not possible with post_url?

Now that we have link, do we still need the post_url approach? I think the post_url section may just need to be deleted. At the very least, some kind of note needs to appear in Post URL that that explains the difference between using link or post_url.

@tomjohnson1492
Contributor

Also, there's a small typo:

If you would like to include a link to a collection’s document, or a post the

Should be:

If you would like to include a link to a collection’s document or a post, the

@DirtyF
Member
DirtyF commented Aug 8, 2016

some kind of note needs to appear in Post URL that that explains the difference between using link or post_url.

The only difference is that you don't need to specify file extension with post_url whereas you have to specify the extension with link. It is duly noted in the documentation.

The tag names seem pretty explanatory to me. If it's not obvious enough, we could add something like:

link is a generic tag that will allow you to link to different type of resources : pages, posts, collection's documents and static files whereas post_urlcan only link to posts. (depends on #5199)

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment