diff --git a/website/app/docs/configuration/page.mdx b/website/app/docs/configuration/page.mdx
index ea4a2d34..039b7920 100644
--- a/website/app/docs/configuration/page.mdx
+++ b/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`.
+
+
+ `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.
+
+
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
diff --git a/website/app/docs/reference/page.mdx b/website/app/docs/reference/page.mdx
index df8114c2..5c63e411 100644
--- a/website/app/docs/reference/page.mdx
+++ b/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.
+
+
+ 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`.
+
+
+---
+
`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).
---