diff --git a/deploy/vercel.mdx b/deploy/vercel.mdx index 9a8d8f0aa..dec5cafd3 100644 --- a/deploy/vercel.mdx +++ b/deploy/vercel.mdx @@ -11,32 +11,38 @@ The `vercel.json` file configures how your project is built and deployed. It sit We use the `rewrites` configuration to proxy requests from your main domain to your documentation. -Rewrites map incoming requests to different destinations without changing the URL in the browser. When someone visits `yoursite.com/docs`, Vercel will internally fetch content from `your-subdomain.mintlify.dev/docs` but the user will still see `yoursite.com/docs` in their browser. This is different from redirects, which would send users to a different URL entirely. +Rewrites map incoming requests to different destinations without changing the URL in the browser. When someone visits `yoursite.com/docs`, Vercel internally fetches content from `your-subdomain.mintlify.dev/docs`, but the user still sees `yoursite.com/docs` in their browser. This is different from redirects, which send users to another URL entirely. You can customize the subpath to any value you prefer, such as `/docs`, `/help`, or `/guides`. Additionally, you can use deeply nested subpaths like `/product/docs`. -## Repository structure - -Your documentation files must be organized within your repository to match your chosen subpath structure. For example, if you want your documentation at `yoursite.com/docs`, you would create a `docs/` directory with all of your documentation files. - ## Configuration -To host your documentation at a custom subpath using Vercel, add the following configuration to your `vercel.json` file. This example uses `/docs`, but you can replace it with any subpath: - -```json -{ - "rewrites": [ - { - "source": "/docs", - "destination": "https://[subdomain].mintlify.dev/docs" - }, - { - "source": "/docs/:match*", - "destination": "https://[subdomain].mintlify.dev/docs/:match*" - } - ] -} -``` +### Host from `/docs` + +1. Navigate to [Custom domain setup](https://dashboard.mintlify.com/settings/deployment/custom-domain) in your dashboard. +2. Click the **Host at `/docs`** toggle to the on position. + + Screenshot of the Custom domain setup page. The Host at `/docs` toggle is on and highlighted by an orange rectangle. + Screenshot of the Custom domain setup page. The Host at `/docs` toggle is on and highlighted by an orange rectangle. + +3. Enter your domain. +4. Select **Add domain**. +5. Add the following rewrites to your `vercel.json` file. Replace `[subdomain]` with your subdomain: + + ```json + { + "rewrites": [ + { + "source": "/docs", + "destination": "https://[subdomain].mintlify.dev/docs" + }, + { + "source": "/docs/:match*", + "destination": "https://[subdomain].mintlify.dev/docs/:match*" + } + ] + } + ``` - **`source`**: The path pattern on your domain that triggers the rewrite. - **`destination`**: Where the request should be proxied to. @@ -44,9 +50,11 @@ To host your documentation at a custom subpath using Vercel, add the following c For more information, see [Configuring projects with vercel.json: Rewrites](https://vercel.com/docs/projects/project-configuration#rewrites) in the Vercel documentation. -### Generate rewrites +### Host from custom path + +To use a custom subpath (any path other than `/docs`), you must organize your documentation files within your repository to match your subpath structure. For example, if your documentation is hosted at `yoursite.com/help`, your documentation files must be in a `help/` directory. -Enter your subdomain and custom subdirectory to generate the rewrites for your `vercel.json` file. +Use the generator below to create your rewrites configuration. Add the rewrites to your `vercel.json` file. diff --git a/images/subpath/toggle-dark.png b/images/subpath/toggle-dark.png new file mode 100644 index 000000000..7d7e4977d Binary files /dev/null and b/images/subpath/toggle-dark.png differ diff --git a/images/subpath/toggle-light.png b/images/subpath/toggle-light.png new file mode 100644 index 000000000..a0eeb2863 Binary files /dev/null and b/images/subpath/toggle-light.png differ diff --git a/snippets/vercel-json-generator.mdx b/snippets/vercel-json-generator.mdx index 196b16f6e..2a7e78e35 100644 --- a/snippets/vercel-json-generator.mdx +++ b/snippets/vercel-json-generator.mdx @@ -1,6 +1,6 @@ export const VercelJsonGenerator = () => { const [subdomain, setSubdomain] = useState('[SUBDOMAIN]') - const [subdirectory, setSubdirectory] = useState('docs') + const [subpath, setSubpath] = useState('[SUBPATH]') const vercelConfig = { rewrites: [ @@ -13,28 +13,28 @@ export const VercelJsonGenerator = () => { destination: `https://${subdomain}.mintlify.app/_mintlify/api/request` }, { - source: `/${subdirectory}`, + source: `/${subpath}`, destination: `https://${subdomain}.mintlify.app` }, { - source: `/${subdirectory}/llms.txt`, + source: `/${subpath}/llms.txt`, destination: `https://${subdomain}.mintlify.app/llms.txt` }, { - source: `/${subdirectory}/llms-full.txt`, + source: `/${subpath}/llms-full.txt`, destination: `https://${subdomain}.mintlify.app/llms-full.txt` }, { - source: `/${subdirectory}/sitemap.xml`, + source: `/${subpath}/sitemap.xml`, destination: `https://${subdomain}.mintlify.app/sitemap.xml` }, { - source: `/${subdirectory}/robots.txt`, + source: `/${subpath}/robots.txt`, destination: `https://${subdomain}.mintlify.app/robots.txt` }, { - source: `/${subdirectory}/:path*`, - destination: `https://${subdomain}.mintlify.app/${subdirectory}/:path*` + source: `/${subpath}/:path*`, + destination: `https://${subdomain}.mintlify.app/${subpath}/:path*` }, { source: "/mintlify-assets/:path+", @@ -71,12 +71,12 @@ export const VercelJsonGenerator = () => {
setSubdirectory(e.target.value)} + value={subpath} + onChange={(e) => setSubpath(e.target.value)} placeholder="docs" className="w-full p-1 text-sm rounded border dark:border-white/10 bg-transparent" />