deprecate Astro.canonicalURL, add Astro.url

src/pages/en/migrate.md

@@ -25,6 +25,17 @@ npm install astro@next--rc
 
 Astro v1.0 RC has upgraded from Vite 2 to [Vite 3](https://vitejs.dev/). We've handled most of the upgrade for you inside of Astro, however some subtle Vite behaviors may still change between versions. Refer to the official [Vite Migration Guide](https://vitejs.dev/guide/migration.html#general-changes) if you run into trouble.
 
+### Deprecated: `Astro.canonicalURL`
+
+You can now use the new [`Astro.url`](#astrourl) helper to construct your own canonical URL from the current page/request URL.
+
+```js
+// Before:
+const canonicalURL = Astro.canonicalURL;
+// After:
+const canonicalURL = new URL(Astro.url.pathname, Astro.site);
+```
+
 ## Astro 1.0 Beta
 
 On April 4, 2022 we released the Astro 1.0 Beta! 🎉

src/pages/en/reference/api-reference.md

@@ -97,13 +97,13 @@ const data = await Astro.glob<CustomDataFile>('../data/**/*.js');
 
 ### `Astro.request`
 
-`Astro.request` is a standard [Request](https://developer.mozilla.org/en-US/docs/Web/API/Request) object. It can be used to get the `url`, `headers`, `method`, and even body of the request. Use `new URL(Astro.request.url)` to get a URL object.
+`Astro.request` is a standard [Request](https://developer.mozilla.org/en-US/docs/Web/API/Request) object. It can be used to get the `url`, `headers`, `method`, and even body of the request. 
+
+See [`Astro.url`](#astrourl) for a full URL object of the current `Astro.request.url` value. This can be useful for accessing individual properties of the request URL, like pathname and origin.
 
 ```astro
----
-const url = new URL(Astro.request.url);
----
-<h1>Origin {url.origin}</h1>
+<h1>The current URL is: {Astro.request.url}</h1>
+<h1>The current URL pathname is: {Astro.url.pathname}</h1>
 ```
 
 ### `Astro.response`
@@ -129,16 +129,33 @@ Astro.response.headers.set('Set-Cookie', 'a=b; Path=/;');
 
 ### `Astro.canonicalURL`
 
-The [canonical URL][canonical] of the current page. If the `site` option is set, the site's origin will be the origin of this URL.
+:::caution[Deprecated]
+Use [`Astro.url`](#astrourl) to construct your own canonical URL. 
+:::
+
+The [canonical URL][canonical] of the current page.
 
-You can also use the `canonicalURL` to grab the current page's `pathname`.
+### `Astro.url`
+
+A full URL object of the current `Astro.request.url` value. Equivalent to `new URL(Astro.request.url)`. Useful for accessing individual properties of the request URL, like pathname and origin.
+
+```astro
+<h1>The current URL is: {Astro.url}</h1>
+<h1>The current URL pathname is: {Astro.url.pathname}</h1>
+<h1>The current URL origin is: {Astro.url.origin}</h1>
+```
+
+You can use `Astro.url` to create new URLs using the [`new URL()`](https://developer.mozilla.org/en-US/docs/Web/API/URL/URL) constructor. This is useful for creating canonical URLs, SEO meta tag URLs, links and more.
 
 ```astro
 ---
-const path = Astro.canonicalURL.pathname;
+// Example: Construct a canonical URL using your production domain
+const canonicalURL = new URL(Astro.url.pathname, Astro.site);
+// Example: Construct a URL for SEO meta tags
+const socialImageURL = new URL('/images/preview.png', Astro.url);
 ---
-
-<h1>Welcome to {path}</h1>
+<link rel="canonical" href={canonicalURL} />
+<meta property="og:image" content={socialImageURL} />
 ```
 
 ### `Astro.clientAddress`