docs: clarify Astro.url and Astro.params runtime behavior#13903
docs: clarify Astro.url and Astro.params runtime behavior#13903Prayaksh wants to merge 5 commits into
Conversation
✅ Deploy Preview for astro-docs-2 ready!Built without sensitive environment variables
To edit notification comments on pull requests, go to your Netlify project configuration. |
|
Hello! Thank you for opening your first PR to Astro’s Docs! 🎉 Here’s what will happen next:
|
Lunaria Status Overview🌕 This pull request will trigger status changes. Learn moreBy default, every PR changing files present in the Lunaria configuration's You can change this by adding one of the keywords present in the Tracked Files
Warnings reference
|
There was a problem hiding this comment.
Thanks for your contribution!
If this is indeed a documentation issue (I wouldn't say "probably" means "confirmation"), this addition can be helpful but it doesn't fully fix the issue.
The issue mentions a misleading description in https://docs.astro.build/en/reference/api-reference/#url and potentially in https://docs.astro.build/en/reference/api-reference/#params
@ematipico can you confirm we should fix the docs? Or the fix mentioned by the bot could work and no docs change is required?
Edit: I hadn't followed the linked PR, it seems this might have been fixed in withastro/astro#16808 ?
|
I realize now that I acted on the “probably” comment before the issue was fully confirmed. Thank you for clarifying. I’m still learning the process and will make sure to verify before updating the docs in the future. |
|
The documentation update is still valid, because not all characters can be safely decoded e.g. |
|
Okay, thanks Ema! And no problem @Prayaksh! Are you still willing to check if other pages require an update? It seems we at least need to update https://docs.astro.build/en/reference/api-reference/#url |
|
Thanks @ArmandPhilippot ! I’ve updated the Astro.url and Astro.params API reference docs to clarify the normalization/decoding behavior as well. |
ArmandPhilippot
left a comment
There was a problem hiding this comment.
Thanks for the update! But, I think the upgrade guide addition is misplaced and your description for Astro.params doesn't seem correct.
|
tried to change as suggested. thanks! |
| A normalized [URL](https://developer.mozilla.org/en-US/docs/Web/API/URL) object derived from the current `request.url` value. It is useful for interacting with individual properties of the request URL, like pathname and origin. | ||
|
|
||
| `Astro.url` is equivalent to doing `new URL(Astro.request.url)`. | ||
| Since Astro v6, the pathname is partially decoded during route normalization. This means `Astro.url.pathname` may differ from `new URL(Astro.request.url).pathname` for percent-encoded route segments. |
There was a problem hiding this comment.
| Since Astro v6, the pathname is partially decoded during route normalization. This means `Astro.url.pathname` may differ from `new URL(Astro.request.url).pathname` for percent-encoded route segments. | |
| Since Astro v6, the pathname may be partially decoded during route normalization. This means `Astro.url.pathname` may differ from `new URL(Astro.request.url).pathname` for percent-encoded route segments. |
It's not always the case, so maybe using "may" sounds better
ArmandPhilippot
left a comment
There was a problem hiding this comment.
Thanks for the update but, in addition to Ema suggestion, I see two issues:
configuration-reference.mdxcontains unrelated changes- the upgrade guide section is misplaced:
440fed4 to
16481ea
Compare
|
Sorry for the confusion — my previous commit accidentally included an unrelated change. I've corrected the commit and updated the branch so the PR now only contains the intended documentation changes. I also wasn't able to identify the source PR for this behavior change. If there's a specific PR number that should be referenced, please let me know. |
ArmandPhilippot
left a comment
There was a problem hiding this comment.
Because this is a breaking change, I don't think users want to know how to access the encoded path, but rather the decoded one (see my suggestions).
I'm not sure about the implementation PR, maybe Ema have more info on this.
|
|
||
| ### Changed: Route pathname normalization | ||
|
|
||
| <SourcePR number="???" title="???"/> |
There was a problem hiding this comment.
Maybe Ema could confirm as he has a better overall view of the changes that have taken place in the main repository, but I guess we can use the same PR as Percent-Encoding in routes.
| <SourcePR number="???" title="???"/> | |
| <SourcePR number="14306" title="feat: integrate vite environments"/> |
|
|
||
| <SourcePR number="???" title="???"/> | ||
|
|
||
| Since Astro v6, route pathnames are partially decoded during route normalization. This means `Astro.url.pathname` may differ from `new URL(Astro.request.url).pathname` for percent-encoded route segments. |
There was a problem hiding this comment.
Ema suggestion should be applied here too:
| Since Astro v6, route pathnames are partially decoded during route normalization. This means `Astro.url.pathname` may differ from `new URL(Astro.request.url).pathname` for percent-encoded route segments. | |
| Since Astro v6, route pathnames may be partially decoded during route normalization. This means `Astro.url.pathname` may differ from `new URL(Astro.request.url).pathname` for percent-encoded route segments. |
Co-authored-by: Armand Philippot <git@armand.philippot.eu>
Co-authored-by: Armand Philippot <git@armand.philippot.eu>
Description (required)
This PR clarifies the runtime behavior of URL decoding in Astro v6 dynamic routes.
The original issue was reported in the
withastro/astrorepository, and after maintainer confirmation it was identified as a documentation gap rather than a runtime bug.In Astro v6,
Astro.urlreturns a normalized and partially decoded URL, which may differ fromnew URL(Astro.request.url). Additionally,Astro.paramsvalues are automatically decoded. This behavior was not clearly documented in the v6 upgrade guide section covering percent-encoded routes.This update adds a runtime clarification under the “Percent-Encoding in routes” section to reflect the actual behavior and avoid confusion for users working with encoded dynamic route segments.
Related issues & labels (optional)
documentation