search

getzola / zola

A fast static site generator in a single binary with everything built-in. https://www.getzola.org
https://www.getzola.org
MIT License
13.53k stars 945 forks source link

`get_url` with @ only finds Markdown files #2530

Closed xpe closed 3 months ago

xpe commented 3 months ago

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 commented 3 months ago

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

xpe commented 3 months ago

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 commented 3 months ago

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 commented 3 months ago

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

xpe commented 3 months ago

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

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