get_url with @ only finds Markdown files

[xpe]

Documentation issue

Summary

It is not clear from the documentation that using @ with get_url only will find Markdown files.

Why I care

I want to get a build-time verified hyperlink to an image file. get_url won't do this at present. I'll ask on the forum for other ways to do it.

Commentary

The name get_url is indeed generic and works as expected as long as @ is not used. The @ implies additional meaning, but this implied meaning is not made clear in the documentation.

[Keats]

I guess we should link to https://www.getzola.org/documentation/content/linking/#internal-links in there

[xpe]

Ooops. I made a mistake above:

I want to get a build-time verified hyperlink to an image file. get_url won't [provide build-time verification]

Actually get_url does do build-time checking.

[xpe]

I guess we should link to https://www.getzola.org/documentation/content/linking/#internal-links in there

I don't see how this addresses my core concern.

Here is my suggested verbiage to add to the docs for get_url:

Note: get_url with a @ prefix only searches for Markdown files

[Keats]

A link starting with @/ is an internal link and how they work is described in that page

[xpe]

@Keats Have you tried to understand this from another person's point of view?

Here is an example of what a user might do:

1. A person visits https://www.getzola.org/documentation/templates/overview/#get-url

2. The person sees mention of @ and reads the description.

Gets the permalink for the given path. If the path starts with @/, it will be treated as an internal link like the ones used in Markdown, starting from the root content directory as well as validated.

3. The user might reasonably expect that @ can be used to link to any file underneath content.

This is what I've done. And the documentation isn't clear from my POV. Remember, the documentation is for users, which have their own points of view.

If this sounds... overly spelled out or even preachy, it is only because my earlier messages didn't get the point across, so I'm trying the "be more direct" approach.