propertiesToHash missing from Image Service API Docs

amxmln commented 2 months ago

📚 Subject area/topic

Image Service API

📋 Page(s) affected (or suggested, for new content)

https://docs.astro.build/en/reference/image-service-reference/

📋 Description of content that is out-of-date or incorrect

According to this PR, the Image Service API has a property propertiesToHash which is used to control which properties are included in the filename hash of an optimised asset.

There doesn’t seem to be a mention on the page in the docs, although I believe there should be, since it’s important information to know when creating a custom image service that supports more options than the standard one.

On a related note, I believe the built-in sharpService is not using the propertiesToHash? I couldn’t find a mention in the source code. Is that intentional and if so, why?

Edit: looking at the patch that introduced the change, it seems like if an image service doesn’t define propertiesToHash, Astro will fall back on the default ones defined in packages/astro/src/assets/consts.ts. Perhaps this could also be added to the updated documentation.

🖥️ Reproduction in StackBlitz (if reporting incorrect content or code samples)

No response

sarah11918 commented 2 months ago

Hi @amxmln , thank you for reporting this as a docs issue! I'm going to ask @Princesseuh about how best to proceed with these features, since she is the one that knows the API best.

We can work with her suggestions and would love to make sure that page is updated with all the accurate information people need!

Princesseuh commented 2 months ago

It is missing yes. I said I would add it and never did, oops.

The method optionally returns an array of strings, which represents the keys that should be included to generate the hash of the image. Its default value is everything that counts for the base services, width height format quality etc.

sarah11918 commented 1 month ago

Hi @amxmln , I'm just following up and seeing whether you are interested in making a PR to add this to the Image Services API page! If not, no worries of course. I have added the help wanted label so that anyone knows they are welcome to make a PR to add, and you have provided the link to the original PR which is already a wonderful help!

amxmln commented 1 month ago

Hi @sarah11918, I have opened a PR for this issue. I wasn’t quite sure where to put the new content in the document, since it isn’t really a hook. So I added the information in the section about local image services.

sarah11918 commented 1 month ago

Thank you @amxmln ! I will ask @Princesseuh to review it. Really appreciate you jumping in here. :rocket:

withastro / docs