[docs] explain ramifications of base path

.changeset/metal-adults-pay.md

@@ -0,0 +1,5 @@
+---
+'@sveltejs/kit': patch
+---
+
+[docs] explain ramifications of base path

documentation/docs/16-configuration.md

@@ -243,7 +243,7 @@ export default config;
 An object containing zero or more of the following `string` values:
 
 - `assets` — an absolute path that your app's files are served from. This is useful if your files are served from a storage bucket of some kind
-- `base` — a root-relative path that must start, but not end with `/` (e.g. `/base-path`), unless it is the empty string. This specifies where your app is served from and allows the app to live on a non-root path
+- `base` — a root-relative path that must start, but not end with `/` (e.g. `/base-path`), unless it is the empty string. This specifies where your app is served from and allows the app to live on a non-root path. Note that you need to prepend all your root-relative links with the base value or they will point to the root of your domain, not your `base` (this is how the browser works). You can use [`base` from `$app/paths`](/docs/modules#$app-paths-base) for that: `<a href={base}/your-page>Link</a>`. If you find yourself writing this often, it may make sense to extract this into a `Link` component.
 
 ### prerender
 

packages/kit/src/core/prerender/prerender.js

@@ -28,7 +28,7 @@ prerender();
 function format_error({ status, path, referrer, referenceType }, config) {
 	const message =
 		status === 404 && !path.startsWith(config.paths.base)
-			? `${path} does not begin with \`base\`, which is configured in \`paths.base\` and can be imported from \`$app/paths\``
+			? `${path} does not begin with \`base\`, which is configured in \`paths.base\` and can be imported from \`$app/paths\` - see https://kit.svelte.dev/docs/configuration#paths for more info`
 			: path;
 
 	return `${status} ${message}${referrer ? ` (${referenceType} from ${referrer})` : ''}`;

packages/kit/types/ambient.d.ts

@@ -174,7 +174,7 @@ declare module '$app/navigation' {
 	/**
 	 * Returns a Promise that resolves when SvelteKit navigates (or fails to navigate, in which case the promise rejects) to the specified `url`.
 	 *
-	 * @param url Where to navigate to
+	 * @param url Where to navigate to. Note that if you've set [`config.kit.paths.base`](https://kit.svelte.dev/docs/configuration#paths) and the URL is root-relative, you need to prepend the base path, if you want to navigate within the app.
 	 * @param opts.replaceState If `true`, will replace the current `history` entry rather than creating a new one with `pushState`
 	 * @param opts.noscroll If `true`, the browser will maintain its scroll position rather than scrolling to the top of the page after navigation
 	 * @param opts.keepfocus If `true`, the currently focused element will retain focus after navigation. Otherwise, focus will be reset to the body
@@ -255,7 +255,9 @@ declare module '$app/navigation' {
  */
 declare module '$app/paths' {
 	/**
-	 * A string that matches [`config.kit.paths.base`](https://kit.svelte.dev/docs/configuration#paths). It must start, but not end with `/` (e.g. `/base-path`), unless it is the empty string.
+	 * A string that matches [`config.kit.paths.base`](https://kit.svelte.dev/docs/configuration#paths).
+	 *
+	 * Example usage: `<a href={base}/your-page>Link</a>`
 	 */
 	export const base: `/${string}`;
 	/**