docs: clarify Astro.url and Astro.params runtime behavior

[Prayaksh]

Description (required)

This PR clarifies the runtime behavior of URL decoding in Astro v6 dynamic routes.

The original issue was reported in the withastro/astro repository, and after maintainer confirmation it was identified as a documentation gap rather than a runtime bug.

In Astro v6, Astro.url returns a normalized and partially decoded URL, which may differ from new URL(Astro.request.url). Additionally, Astro.params values 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)

• Closes URL Decoding in Dynamic Routes (SSR) astro#16313
• Suggested label: documentation

---

[netlify]

✅ Deploy Preview for astro-docs-2 ready!

Built without sensitive environment variables

Name	Link
🔨 Latest commit	4c68460
🔍 Latest deploy log	https://app.netlify.com/projects/astro-docs-2/deploys/6a09b42dfac0c10008cfb3c6
😎 Deploy Preview	https://deploy-preview-13903--astro-docs-2.netlify.app
📱 Preview on mobile	Toggle QR Code... Use your smartphone camera to open QR code link.
🤖 Make changes	Run an agent on this branch

---

To edit notification comments on pull requests, go to your Netlify project configuration.

[astrobot-houston]

Hello! Thank you for opening your first PR to Astro’s Docs! 🎉

Here’s what will happen next:

1. Our GitHub bots will run to check your changes.
   If they spot any broken links you will see some error messages on this PR.
   Don’t hesitate to ask any questions if you’re not sure what these mean!

2. In a few minutes, you’ll be able to see a preview of your changes on Netlify 🥳.

3. One or more of our maintainers will take a look and may ask you to make changes.
   We try to be responsive, but don’t worry if this takes a few days.

[astrobot-houston]

Lunaria Status Overview

🌕 This pull request will trigger status changes.

Learn more

By default, every PR changing files present in the Lunaria configuration's files property will be considered and trigger status changes accordingly.

You can change this by adding one of the keywords present in the ignoreKeywords property in your Lunaria configuration file in the PR's title (ignoring all files) or by including a tracker directive in the merged commit's description.

Tracked Files

File	Note
en/guides/upgrade-to/v6.mdx	Source changed, localizations will be marked as outdated.

Warnings reference

Icon	Description
🔄️	The source for this localization has been updated since the creation of this pull request, make sure all changes in the source have been applied.

[ArmandPhilippot]

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 ?

[Prayaksh]

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.

[ematipico]

The documentation update is still valid, because not all characters can be safely decoded e.g. %25AB. Even after my fix, there are still cases that are uncertain, so Astro play it safe and returns an error.

[ArmandPhilippot]

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