chore: docsPath rewrite docs

website/app/docs/configuration/page.mdx

@@ -120,7 +120,8 @@ All configuration lives in a single `docs.config.ts` file.
 
 | Option         | Type                           | Default         | Description                                        |
 | -------------- | ------------------------------ | --------------- | -------------------------------------------------- |
-| `entry`        | `string`                       | `"docs"`        | The docs URL path prefix (e.g. `"docs"` → `/docs`) |
+| `entry`        | `string`                       | `"docs"`        | Docs source route and folder (e.g. `"docs"` -> `app/docs`) |
+| `docsPath`     | `string`                       | same as `entry` | Public docs route prefix in Next.js. Use `""` for root-mounted docs |
 | `contentDir`   | `string`                       | same as `entry` | Path to content files (TanStack Start, SvelteKit, Astro, Nuxt) |
 | `staticExport` | `boolean`                      | `false`         | Set `true` for full static builds (see [Static export](#static-export)) |
 | `theme`        | `DocsTheme`                    | —               | Theme preset from a theme factory                  |
@@ -148,6 +149,60 @@ All configuration lives in a single `docs.config.ts` file.
 | `metadata`    | `DocsMetadata`                 | —               | SEO metadata template and JSON-LD page inputs      |
 | `og`          | `OGConfig`                     | —               | Dynamic Open Graph images (see [API Reference](/docs/reference#ogconfig)) |
 
+## Public docs path
+
+In Next.js, `entry` controls where the docs live in your app directory. `docsPath` controls the
+public URL where readers see those pages.
+
+The default keeps both values aligned:
+
+```tsx title="docs.config.tsx"
+import { defineDocs } from "@farming-labs/docs";
+import { fumadocs } from "@farming-labs/theme";
+
+export default defineDocs({
+  entry: "docs",
+  theme: fumadocs(),
+});
+```
+
+With the default config, `app/docs/quickstart/page.mdx` is available at `/docs/quickstart`.
+
+Set `docsPath: ""` when the whole deployment is docs-only and should publish pages from the site
+root:
+
+```tsx title="docs.config.tsx"
+import { defineDocs } from "@farming-labs/docs";
+import { fumadocs } from "@farming-labs/theme";
+
+export default defineDocs({
+  entry: "docs",
+  docsPath: "",
+  theme: fumadocs(),
+});
+```
+
+The files still live under `app/docs`, but readers see root URLs:
+
+| Source file                        | Public URL    |
+| ---------------------------------- | ------------- |
+| `app/docs/page.mdx`                | `/`           |
+| `app/docs/quickstart/page.mdx`     | `/quickstart` |
+| `app/docs/reference/auth/page.mdx` | `/reference/auth` |
+
+This is useful for a docs subdomain. Attach `docs.example.com` to the docs deployment, then set
+`docsPath: ""` so the subdomain serves clean URLs like `https://docs.example.com/quickstart`
+instead of `https://docs.example.com/docs/quickstart`.
+
+`withDocs({})` reads this from `docs.config.tsx`, so you do not need to add custom rewrites to
+`next.config.ts`.
+
+<Callout type="warning" title="Use root docs only for docs-first deployments">
+  `docsPath: ""` makes the docs own `/` and other root-level page paths on that deployment. If the
+  same Next.js app also serves a marketing site at `/`, keep the default `/docs` path or use a
+  separate docs deployment for your subdomain.
+</Callout>
+
 For sidebar folder parents that have their own landing page, use
 `sidebar.folderIndexBehavior: "toggle"` if you want parent rows to only open and close their
 children instead of navigating. Use `sidebar.folderIndexBehaviorOverrides` when only selected

website/app/docs/reference/page.mdx

@@ -38,7 +38,8 @@ Top-level configuration object passed to `defineDocs()`.
 
 | Property       | Type                                            | Default          | Description                                                                          |
 | -------------- | ----------------------------------------------- | ---------------- | ------------------------------------------------------------------------------------ |
-| `entry`        | `string`                                        | **required**     | URL path prefix for docs (e.g. `"docs"` → `/docs`)                                   |
+| `entry`        | `string`                                        | **required**     | Docs source route and folder (e.g. `"docs"` -> `app/docs`)                           |
+| `docsPath`     | `string`                                        | same as `entry`  | Public docs route prefix in Next.js. Use `""` to serve docs from `/`                 |
 | `contentDir`   | `string`                                        | same as `entry`  | Path to content files. TanStack Start, SvelteKit, Astro, and Nuxt use it; Next.js uses `app/{entry}/` |
 | `staticExport` | `boolean`                                       | `false`          | Set `true` for full static builds; hides search and AI (see [Configuration](/docs/configuration#static-export)) |
 | `theme`        | `DocsTheme`                                     | —                | Theme preset from a factory (`fumadocs()`, `darksharp()`, `pixelBorder()`, etc.)    |
@@ -69,6 +70,45 @@ Top-level configuration object passed to `defineDocs()`.
 
 ---
 
+## `entry` and `docsPath`
+
+`entry` is the source route and app folder. In a Next.js app with `entry: "docs"`, the framework
+expects docs pages under `app/docs`.
+
+`docsPath` changes the public route where those pages are exposed. It defaults to the same path as
+`entry`, so `app/docs/quickstart/page.mdx` is served at `/docs/quickstart`.
+
+For a docs-only deployment or a docs subdomain, set `docsPath: ""`:
+
+```tsx title="docs.config.tsx"
+import { defineDocs } from "@farming-labs/docs";
+import { fumadocs } from "@farming-labs/theme";
+
+export default defineDocs({
+  entry: "docs",
+  docsPath: "",
+  theme: fumadocs(),
+});
+```
+
+That keeps the files under `app/docs` and serves them from the public root:
+
+| Source file                    | Public URL    |
+| ------------------------------ | ------------- |
+| `app/docs/page.mdx`            | `/`           |
+| `app/docs/quickstart/page.mdx` | `/quickstart` |
+
+`withDocs({})` reads `docsPath` from `docs.config.tsx`. You do not need host-specific rewrites in
+`next.config.ts` for a docs-only deployment. Attach the docs deployment to a subdomain like
+`docs.example.com`, then root URLs resolve on that subdomain.
+
+<Callout type="warning" title="Root docs own root routes">
+  Use `docsPath: ""` when the deployment is dedicated to docs. If the same app needs a marketing
+  homepage at `/`, keep `docsPath` unset so docs stay under `/docs`.
+</Callout>
+
+---
+
 `components` is merged into the default MDX component map, so you can both add your own components and replace built-ins such as `Callout`, `Tabs`, `HoverLink`, or `Prompt`. For built-in defaults like `theme.ui.components.HoverLink` and `theme.ui.components.Prompt`, see [Creating themes](/docs/themes/creating-themes). For usage examples and a live demo, see [Components](/docs/customization/components).
 
 ---