Clarify "Generate rewrites" tool to only be used for custom base paths (#1485)

* clarify rewrite methods

* add images

* copyedits

* move note about repository structure

* add missing `/docs` from rewrites

* update snippet to use `subpath`

* consolidate /docs steps

* copyedit

Author: ethanpalm

deploy/vercel.mdx

@@ -11,42 +11,50 @@ 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.
+  <Frame>
+    <img alt="Screenshot of the Custom domain setup page. The Host at `/docs` toggle is on and highlighted by an orange rectangle." src="/images/subpath/toggle-light.png" className="block dark:hidden" />
+    <img alt="Screenshot of the Custom domain setup page. The Host at `/docs` toggle is on and highlighted by an orange rectangle." src="/images/subpath/toggle-dark.png" className="hidden dark:block" />
+  </Frame>
+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.
 - **`:match*`**: A wildcard that captures any path segments after your subpath.
 
 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.
 
 <VercelJsonGenerator />
 

images/subpath/toggle-dark.png

@@ -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 = () => {
         </div>
         <div>
           <label className="block text-sm text-zinc-950/70 dark:text-white/70 mb-1">
-            Subdirectory
+            Subpath
           </label>
           <input
             type="text"
-            value={subdirectory}
-            onChange={(e) => 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"
           />