From 40d10fd6905e023b7defed2a0a140aa481f82e68 Mon Sep 17 00:00:00 2001 From: Kinfe123 Date: Wed, 20 May 2026 00:57:53 +0300 Subject: [PATCH] chore: docs about path rewrite --- website/app/docs/configuration/page.mdx | 57 ++++++++++++++++++++++++- website/app/docs/reference/page.mdx | 42 +++++++++++++++++- 2 files changed, 97 insertions(+), 2 deletions(-) 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). ---