docs(router): clarify how base href is used to construct targets (angular#38123)

atscott · Splaktar · commit 17841959f53a · 2020-08-07T22:10:55.000-04:00
The documentation is not clear on how the base href and APP_BASE_HREF are used. This commit should help clarify more complicated use-cases beyond the most common one of just a '/' PR Close angular#38123
diff --git a/aio/content/guide/router.md b/aio/content/guide/router.md
@@ -541,6 +541,15 @@ set the `href` value in `index.html` as shown here.
 
 ### HTML5 URLs and the  `<base href>`
 
+The guidelines that follow will refer to different parts of a URL. This diagram outlines what those parts refer to:
+
+```
+foo://example.com:8042/over/there?name=ferret#nose
+\_/   \______________/\_________/ \_________/ \__/
+ |           |            |            |        |
+scheme    authority      path        query   fragment
+```
+
 While the router uses the <a href="https://developer.mozilla.org/en-US/docs/Web/API/History_API#Adding_and_modifying_history_entries" title="Browser history push-state">HTML5 pushState</a> style by default, you must configure that strategy with a `<base href>`.
 
 The preferred way to configure the strategy is to add a <a href="https://developer.mozilla.org/en-US/docs/Web/HTML/Element/base" title="base href">&lt;base href&gt; element</a> tag in the `<head>` of the `index.html`.
@@ -554,8 +563,16 @@ Some developers may not be able to add the `<base>` element, perhaps because the
 
 Those developers may still use HTML5 URLs by taking the following two steps:
 
-1. Provide the router with an appropriate [APP_BASE_HREF][] value.
-1. Use root URLs for all web resources: CSS, images, scripts, and template HTML files.
+1. Provide the router with an appropriate `APP_BASE_HREF` value.
+1. Use root URLs (URLs with an `authority`) for all web resources: CSS, images, scripts, and template HTML files.
+
+* The `<base href>` `path` should end with a "/", as browsers ignore characters in the `path` that follow the right-most "/".
+* If the `<base href>` includes a `query` part, the `query` is only used if the `path` of a link in the page is empty and has no `query`.
+This means that a `query` in the `<base href>` is only included when using `HashLocationStrategy`.
+* If a link in the page is a root URL (has an `authority`), the `<base href>` is not used. In this way, an `APP_BASE_HREF` with an authority will cause all links created by Angular to ignore the `<base href>` value.
+* A fragment in the `<base href>` is _never_ persisted.
+
+For more complete information on how `<base href>` is used to construct target URIs, see the [RFC](https://tools.ietf.org/html/rfc3986#section-5.2.2) section on transforming references.
 
 {@a hashlocationstrategy}
 
diff --git a/packages/common/src/location/location_strategy.ts b/packages/common/src/location/location_strategy.ts
@@ -81,17 +81,21 @@ export const APP_BASE_HREF = new InjectionToken<string>('appBaseHref');
  * browser's URL.
  *
  * If you're using `PathLocationStrategy`, you must provide a {@link APP_BASE_HREF}
- * or add a base element to the document. This URL prefix that will be preserved
- * when generating and recognizing URLs.
+ * or add a `<base href>` element to the document.
  *
- * For instance, if you provide an `APP_BASE_HREF` of `'/my/app'` and call
+ * For instance, if you provide an `APP_BASE_HREF` of `'/my/app/'` and call
  * `location.go('/foo')`, the browser's URL will become
- * `example.com/my/app/foo`.
+ * `example.com/my/app/foo`. To ensure all relative URIs resolve correctly,
+ * the `<base href>` and/or `APP_BASE_HREF` should end with a `/`.
  *
- * Similarly, if you add `<base href='/my/app'/>` to the document and call
+ * Similarly, if you add `<base href='/my/app/'/>` to the document and call
  * `location.go('/foo')`, the browser's URL will become
  * `example.com/my/app/foo`.
  *
+ * Note that when using `PathLocationStrategy`, neither the query nor
+ * the fragment in the `<base href>` will be preserved, as outlined
+ * by the [RFC](https://tools.ietf.org/html/rfc3986#section-5.2.2).
+ *
  * @usageNotes
  *
  * ### Example

Original file line number	Diff line number	Diff line change
`@@ -81,17 +81,21 @@ export const APP_BASE_HREF = new InjectionToken<string>('appBaseHref');`
`81`	`81`	`* browser's URL.`
`82`	`82`	`*`
`83`	`83`	* If you're using `PathLocationStrategy`, you must provide a {@link APP_BASE_HREF}
`84`		`- * or add a base element to the document. This URL prefix that will be preserved`
`85`		`- * when generating and recognizing URLs.`
	`84`	+ * or add a `<base href>` element to the document.
`86`	`85`	`*`
`87`		- * For instance, if you provide an `APP_BASE_HREF` of `'/my/app'` and call
	`86`	+ * For instance, if you provide an `APP_BASE_HREF` of `'/my/app/'` and call
`88`	`87`	* `location.go('/foo')`, the browser's URL will become
`89`		- * `example.com/my/app/foo`.
	`88`	+ * `example.com/my/app/foo`. To ensure all relative URIs resolve correctly,
	`89`	+ * the `<base href>` and/or `APP_BASE_HREF` should end with a `/`.
`90`	`90`	`*`
`91`		- * Similarly, if you add `<base href='/my/app'/>` to the document and call
	`91`	+ * Similarly, if you add `<base href='/my/app/'/>` to the document and call
`92`	`92`	* `location.go('/foo')`, the browser's URL will become
`93`	`93`	* `example.com/my/app/foo`.
`94`	`94`	`*`
	`95`	+ * Note that when using `PathLocationStrategy`, neither the query nor
	`96`	+ * the fragment in the `<base href>` will be preserved, as outlined
	`97`	`+ * by the [RFC](https://tools.ietf.org/html/rfc3986#section-5.2.2).`
	`98`	`+ *`
`95`	`99`	`* @usageNotes`
`96`	`100`	`*`
`97`	`101`	`* ### Example`