diff --git a/fern/products/docs/pages/self-hosted/self-hosted-set-up.mdx b/fern/products/docs/pages/self-hosted/self-hosted-set-up.mdx
index 965a50168..b85517b5c 100644
--- a/fern/products/docs/pages/self-hosted/self-hosted-set-up.mdx
+++ b/fern/products/docs/pages/self-hosted/self-hosted-set-up.mdx
@@ -142,7 +142,7 @@ Configure the self-hosted container's behavior by setting environment variables
| `CUSTOM_DOMAIN` | Override the `custom-domain` from `docs.yml` at runtime. Useful when the hostname where the docs are actually served differs from the domain in `docs.yml`. Accepts a bare hostname (e.g., `docs.plantstore.dev`); any `https://` or `http://` prefix is stripped automatically. | Value from `docs.yml` `custom-domain` |
| `FERN_LOG_LEVEL` | Log level for the Fern CLI during docs generation. Options: `debug`, `info`, `warn`, `error`. | `debug` |
| `NODE_MEMORY_LIMIT` | Node.js heap size in MB for the Next.js server. Increase for large documentation sites with many API versions. | `4096` |
-| `NEXT_PUBLIC_BASE_PATH` | Serve the documentation from a sub-path instead of root. The value must start with `/` and have no trailing slash (e.g., `/docs`). See [Base path](#base-path) for details. | none (serves from `/`) |
+| `NEXT_PUBLIC_BASE_PATH` | Override the base path inferred from your `docs.yml` sub-path, or serve from a sub-path without configuring `docs.yml`. The value must start with `/` and have no trailing slash (e.g., `/docs`). See [Base path](#base-path) for details. | Inferred from `docs.yml` sub-path (else serves from `/`) |
### Cache warmup
@@ -230,9 +230,21 @@ The following sections cover optional configurations for specific deployment sce
### Base path
-By default, the self-hosted container serves documentation from root (`/`). Set `NEXT_PUBLIC_BASE_PATH` to serve from a sub-path instead, such as `/docs`. This is useful when your documentation shares a domain with other applications behind a reverse proxy.
+By default, the self-hosted container serves documentation from root (`/`). To serve from a sub-path instead, such as `/docs`, add the sub-path to your `docs.yml` instance. Fern infers the base path from that sub-path, with no environment variable required. This is the preferred approach.
-The value must start with `/` and must not end with a trailing slash.
+Apply the sub-path to both the instance `url` and its `custom-domain`:
+
+```yaml docs.yml
+instances:
+ - url: plantstore.docs.buildwithfern.com/docs
+ custom-domain: docs.plantstore.dev/docs
+```
+
+`fern generate --docs` validates that an instance's `url` and `custom-domain` share the same base path, so the sub-path must be on both or neither. With this configuration, the documentation is accessible at `http://localhost:3000/docs` instead of `http://localhost:3000/`.
+
+#### Override the base path with an environment variable
+
+Set `NEXT_PUBLIC_BASE_PATH` when you need a base path that differs from the `docs.yml` sub-path, such as reusing one prebuilt image across environments that serve from different paths. The environment variable overrides the sub-path inferred from `docs.yml`. The value must start with `/` and must not end with a trailing slash.
@@ -258,18 +270,12 @@ Pass `NEXT_PUBLIC_BASE_PATH` when starting the container. The base path is patch
docker run -p 3000:3000 -e NEXT_PUBLIC_BASE_PATH=/docs self-hosted-docs
```
-
-Runtime patching modifies files inside the container on startup, so it is not compatible with `readOnlyRootFilesystem: true` in Kubernetes. Use build-time patching if your security context requires a read-only root filesystem.
-
+Runtime patching modifies files inside the container on startup, so it's not compatible with `readOnlyRootFilesystem: true` in Kubernetes. Use build-time patching if your security context requires a read-only root filesystem.
-With `NEXT_PUBLIC_BASE_PATH=/docs`, the documentation is accessible at `http://localhost:3000/docs` instead of `http://localhost:3000/`.
-
-
-A single Docker image built **without** `NEXT_PUBLIC_BASE_PATH` can be configured at runtime to serve from any path. This lets you reuse one image across environments that may need different base paths.
-
+A single Docker image built without a base path can be patched at runtime to serve from any path, letting you reuse one image across environments that need different base paths.
### Runtime generation