From a0848eac6cc2238690abcf5acb59cb3aa4deeaf6 Mon Sep 17 00:00:00 2001
From: Martin <martinwinkler82@web.de>
Date: Sat, 23 Mar 2024 20:09:19 +0100
Subject: [PATCH] added section explaining path merging of url and base
 parameters (#32473)

* added section explaining path merging of url and base parameters

The path merging behavior was not documented here up until now. The simple but erroneous assumption that url and base are simply concatenated is a mistake easy enough to make. The documentation page should have a section or a note addressing this.

* Make Prettier happy

Co-authored-by: github-actions[bot] <41898282+github-actions[bot]@users.noreply.github.com>

* added examples for './path' and '../path'

* Update files/en-us/web/api/url/url/index.md

Co-authored-by: github-actions[bot] <41898282+github-actions[bot]@users.noreply.github.com>

* moved text into a **Note:** under ##Syntax -> ### Parameters

* Update files/en-us/web/api/url/url/index.md

Co-authored-by: wbamberg <will@bootbonnet.ca>

* turned the **Note:** into regular document text

---------

Co-authored-by: wbamberg <will@bootbonnet.ca>
Co-authored-by: github-actions[bot] <41898282+github-actions[bot]@users.noreply.github.com>
---
 files/en-us/web/api/url/url/index.md | 40 ++++++++++++++++++++++++++++
 1 file changed, 40 insertions(+)

diff --git a/files/en-us/web/api/url/url/index.md b/files/en-us/web/api/url/url/index.md
index afc2b47585f3905..0c0e75e84c74275 100644
--- a/files/en-us/web/api/url/url/index.md
+++ b/files/en-us/web/api/url/url/index.md
@@ -39,6 +39,14 @@ new URL(url, base)
 > {{domxref("URL")}} object for either argument, and it will stringify to the
 > object's {{domxref("URL.href", "href")}} property.
 
+The resulting URL is not simply a concatenation of `url` and `base`.
+The path sections of both arguments are merged according to
+[RFC 3986 - Relative Resolution](https://datatracker.ietf.org/doc/html/rfc3986.html#section-5.2).
+Therefore a trailing slash in `base` or a leading slash in `url` affect how the resulting path is constructed.
+If you need a strict concatenation of the two arguments the `url` must not have a leading slash
+and the `base` must have a trailing slash.
+See the examples under [Examples - Merging of url and base paths](#merging_of_url_and_base_paths).
+
 ### Exceptions
 
 | Exception               | Explanation                                                                                               |
@@ -98,6 +106,38 @@ new URL("//foo.com", "https://example.com");
 // => 'https://foo.com/' (see relative URLs)
 ```
 
+### Merging of url and base paths
+
+```js
+/* base path without trailing slash */
+
+const A = new URL("articles", "https://developer.mozilla.org/api/v1");
+// => 'https://developer.mozilla.org/api/articles'
+
+const B = new URL("/articles", "https://developer.mozilla.org/api/v1");
+// => 'https://developer.mozilla.org/articles'
+
+const C = new URL("./articles", "https://developer.mozilla.org/api/v1");
+// => 'https://developer.mozilla.org/api/articles'
+
+const D = new URL("../articles", "https://developer.mozilla.org/api/v1");
+// => 'https://developer.mozilla.org/articles'
+
+/* base path with trailing slash */
+
+const E = new URL("articles", "https://developer.mozilla.org/api/v1/");
+// => 'https://developer.mozilla.org/api/v1/articles'
+
+const F = new URL("/articles", "https://developer.mozilla.org/api/v1/");
+// => 'https://developer.mozilla.org/articles'
+
+const G = new URL("./articles", "https://developer.mozilla.org/api/v1/");
+// => 'https://developer.mozilla.org/api/v1/articles'
+
+const H = new URL("../articles", "https://developer.mozilla.org/api/v1/");
+// => 'https://developer.mozilla.org/api/articles'
+```
+
 ## Specifications
 
 {{Specifications}}