Missing documentation for addUrlTransform

[darthmall]

I noticed the addUrlTransform function being used in a few examples in the docs, but I can’t seem to find any documentation on the method itself.

[Snapstromegon]

I admit, the documentation for this is fairly hidden and could be improved upon.
The basic documentation is located here: https://v2.11ty.dev/docs/permalinks/#mapping-one-url-to-multiple-files-for-internationalization

[darthmall]

This is not really documentation for addUrlTransform, it’s one of the examples I found that clued me in to its existence. Documentation for addUrlTransform would explain what it does, what arguments it takes, what argument the transform callback receives when it’s called, and perhaps when in the build process it is run.

In the internationalization example, the only thing we learn about the callback is that it receives an object with a url property. We have no idea what else is in that object. In the other example I found on removing trailing slashes, the use of page as the parameter name kind of implied that the argument passed to the callback is Eleventy’s page variable, but looking at the implementation, that doesn’t appear to be the case. The argument is an object with just a url property and a urlStem property. I haven’t dug any deeper to understand what the urlStem might be.

[Snapstromegon]

I think the location I mentioned is kind of the only meaningful place in the docs where it's not just used, but where also at least comments describe the behavior of the function in more detail, telling you about the param and return behavior.

But I agree, the docs are not only lacking, but also seem to be missing the urlStem property. Also objects with properties that are a subset of a page variable are used across the API at places where the complete page variable might not yet be available (only a few cases).

Takeaway would be, that we should probably add a section about urlTransforms here: https://v2.11ty.dev/docs/config/#transforms

[Ryuno-Ki]

When looking into 11ty/buildawesome#4235 I noticed that this method was undocumented, too.

(Introduced with 9d0e373 )

It might not even match the implementation as

11ty/buildawesome@dc79939

only knows of setUrlTransform!