[site] Document link Liquid tag

[DirtyF]

Following #4624

Documentation for new link tag introduced in v3.2.0

cc @jekyll/documentation

[parkr]

@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.

[DirtyF]

@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]

@parkr Documentation has been updated as you asked.

depends on #5199

[parkr]

depends on #5199

Can you mention in the documentation that this is unreleased?

[tomjoht]

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.

[tomjoht]

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]

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)