Document scalable subdomains

advanced/subpath/cloudflare.mdx

@@ -1,36 +1,40 @@
 ---
 title: "Cloudflare"
-description: "Host documentation at a /docs subpath using Cloudflare Workers"
+description: "Host documentation at a custom subpath using Cloudflare Workers"
 ---
 
 import Propagating from "/snippets/custom-subpath-propagating.mdx";
 
-To host your documentation at a `/docs` subpath using Cloudflare, you will need to create and configure a Cloudflare Worker.
+To host your documentation at a custom subpath such as `yoursite.com/docs` using Cloudflare, you will need to create and configure a Cloudflare Worker.
 
 <Info>
   Before you begin, you need a Cloudflare account and a domain name (can be managed on or off Cloudflare).
 </Info>
 
+## 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.
+
 ## Set up a Cloudflare Worker
 
 Create a Cloudflare Worker by following the [Cloudflare Workers getting started guide](https://developers.cloudflare.com/workers/get-started/dashboard/), if you have not already.
 
 <Warning>
   If your DNS provider is Cloudflare, do not use proxying for the CNAME record.
 </Warning>
 
 ### Proxies with Vercel deployments
 
 If you use Cloudflare as a proxy with Vercel deployments, you must ensure proper configuration to avoid conflicts with Vercel's domain verification and SSL certificate provisioning.
 
 Improper proxy configuration can prevent Vercel from provisioning Let's Encrypt SSL certificates and cause domain verification failures.
 
 #### Required path allowlist
 
 Your Cloudflare Worker must allow traffic to these specific paths without blocking or redirecting:
 
 - `/.well-known/acme-challenge/*` - Required for Let's Encrypt certificate verification
 - `/.well-known/vercel/*` - Required for Vercel domain verification
 
 While Cloudflare automatically handles many verification rules, creating additional custom rules may inadvertently block this critical traffic.
 
@@ -43,7 +47,7 @@
 In your Cloudflare dashboard, select **Edit Code** and add the following script into your Worker's code. See the [Cloudflare documentation](https://developers.cloudflare.com/workers-ai/get-started/dashboard/#development) for more information on editing a Worker.
 
 <Tip>
-  Replace `[SUBDOMAIN]` with your unique subdomain and `[YOUR_DOMAIN]` with your website's base URL.
+  Replace `[SUBDOMAIN]` with your unique subdomain, `[YOUR_DOMAIN]` with your website's base URL, and `/docs` with your desired subpath if different.
 </Tip>
 
 ```javascript
@@ -104,7 +108,7 @@
 3. Add your domain. 
 
 <Tip>
   We recommend you add your domain both with and without `www.` prepended.
 </Tip>
 
 See [Add a custom domain](https://developers.cloudflare.com/workers/configuration/routing/custom-domains/#add-a-custom-domain) in the Cloudflare documentation for more information. 
@@ -116,19 +120,19 @@
 1. Delete the existing DNS record for your domain. See [Delete DNS records](https://developers.cloudflare.com/dns/manage-dns-records/how-to/create-dns-records/#delete-dns-records) in the Cloudflare documentation for more information.
 2. Return to your Worker and add your custom domain.
 
 ## Webflow custom routing
 If you use Webflow to host your main site and want to serve Mintlify docs at `/docs` on the same domain, you'll need to configure custom routing through Cloudflare Workers to proxy all non-docs traffic to your main site.
 
 <Warning>
   Make sure your main site is set up on a landing page before deploying this Worker, or visitors to your main site will see errors.
 </Warning>
 
 1. In Webflow, set up a landing page for your main site like `landing.yoursite.com`. This will be the page that visitors see when they visit your site.
 2. Deploy your main site to the landing page. This ensures that your main site remains accessible while you configure the Worker.
 3. To avoid conflicts, update any absolute URLs in your main site to be relative.
 4. In Cloudflare, select **Edit Code** and add the following script into your Worker's code.
 
-  <Tip> Replace `[SUBDOMAIN]` with your unique subdomain, `[YOUR_DOMAIN]` with your website's base URL, and `[LANDING_DOMAIN]` with your landing page URL. </Tip>
+  <Tip> Replace `[SUBDOMAIN]` with your unique subdomain, `[YOUR_DOMAIN]` with your website's base URL, `[LANDING_DOMAIN]` with your landing page URL, and `/docs` with your desired subpath if different. </Tip>
 
   ```javascript
   addEventListener("fetch", (event) => {

advanced/subpath/route53-cloudfront.mdx

@@ -1,12 +1,16 @@
 ---
 title: "AWS Route 53 and CloudFront"
 sidebarTitle: "AWS"
-description: "Host documentation at a /docs subdirectory using AWS services"
+description: "Host documentation at a custom subpath using AWS services"
 ---
 
 import Propagating from "/snippets/custom-subpath-propagating.mdx";
 
-To host your documentation at a `/docs` subpath using AWS Route 53 and CloudFront, you need to configure your DNS provider to point to your CloudFront distribution.
+To host your documentation at a custom subpath such as `yoursite.com/docs` using AWS Route 53 and CloudFront, you need to configure your DNS provider to point to your CloudFront distribution.
+
+## 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.
 
 ## High-level overview
 
@@ -14,8 +18,8 @@
 
 - `/.well-known/acme-challenge/*` - Required for Let's Encrypt certificate verification
 - `/.well-known/vercel/*` - Required for domain verification
 - `/docs/*` - Required for subpath routing
 - `/docs/` - Required for subpath routing
 
 Route traffic to this path with a Cache Policy of **CachingEnabled**:
 
@@ -61,9 +65,9 @@
 2. Find your staging URL that mirrors the main domain. This is highly variant depending on how your landing page is hosted. For example, the Mintlify staging URL is [mintlify-landing-page.vercel.app](https://mintlify-landing-page.vercel.app).
 
 <Info>
   If your landing page is hosted on Webflow, use Webflow's staging URL. It would look like `.webflow.io`.
 
   If you use Vercel, use the `.vercel.app` domain available for every project.
 </Info>
 
 3. Create a new Origin and add your staging URL as the "Origin domain".
@@ -80,9 +84,9 @@
 
 ## Set behaviors
 
-Behaviors in CloudFront enable control over the subpath logic. At a high level, we're looking to create the following logic.
+Behaviors in CloudFront enable control over the subpath logic. At a high level, we're looking to create the following logic:
 
-- **If a user lands on /docs**, go to `[SUBDOMAIN].mintlify.dev`.
+- **If a user lands on your custom subpath**, go to `[SUBDOMAIN].mintlify.dev`.
 - **If a user lands on any other page**, go the current landing page.
 
 1. Navigate to the "Behaviors" tab of your CloudFront distribution.
@@ -95,7 +99,7 @@
 
 ### `/.well-known/*`
 
 Create behaviors for Vercel domain verification paths with a **Path pattern** of `/.well-known/*` and set **Origin and origin groups** to your docs URL.
 
 For "Cache policy", select **CachingDisabled** to ensure these verification requests pass through without caching.
 
@@ -104,14 +108,14 @@
 </Frame>
 
 <Info>
 If `.well-known/*` is too generic, it can be narrowed down to 2 behaviors at a minimum for Vercel:
   - `/.well-known/vercel/*` - Required for Vercel domain verification
   - `/.well-known/acme-challenge/*` - Required for Let's Encrypt certificate verification
 </Info>
 
-### `/docs`
+### Your custom subpath
 
-Create a behavior with a **Path pattern** of `/docs` with **Origin and origin groups** pointing to the `.mintlify.dev` URL (in our case `acme.mintlify.dev`).
+Create a behavior with a **Path pattern** of your chosen subpath, for example `/docs`, with **Origin and origin groups** pointing to the `.mintlify.dev` URL (in our case `acme.mintlify.dev`).
 
 - Set "Cache policy" to **CachingOptimized**.
 - Set "Origin request policy" to **AllViewerExceptHostHeader**.
@@ -121,11 +125,11 @@
   ![CloudFront "Create behavior" page with a "Path pattern" of "/docs/*" and "Origin and origin groups" pointing to the `acme.mintlify.dev` URL.](/images/cloudfront/behavior-1.png)
 </Frame>
 
-### `/docs/*`
+### Your custom subpath with wildcard
 
-Create a behavior with a **Path pattern** of `/docs/*` and **Origin and origin groups** pointing to the same `.mintlify.dev` URL.
+Create a behavior with a **Path pattern** of your chosen subpath followed by `/*`, for example `/docs/*`, and **Origin and origin groups** pointing to the same `.mintlify.dev` URL.
 
-These settings should exactly match `/docs`. With the exception of the **Path pattern**.
+These settings should exactly match your base subpath behavior. With the exception of the **Path pattern**.
 
 - Set "Cache policy" to **CachingOptimized**.
 - Set "Origin request policy" to **AllViewerExceptHostHeader**.
@@ -169,7 +173,7 @@
   ![CloudFront "General" tab with the "Distribution domain name" URL highlighted.](/images/cloudfront/preview-distribution.png)
 </Frame>
 
-All pages should be directing to your main landing page, but if you append `/docs` to the URL, you should see it going to your Mintlify documentation instance.
+All pages should be directing to your main landing page, but if you append your chosen subpath, for example `/docs`, to the URL, you should see it going to your Mintlify documentation instance.
 
 ## Connect with Route53
 
@@ -201,6 +205,6 @@
   You may need to remove the existing A record if one currently exists.
 </Note>
 
-Your documentation is now live at `/docs` for your primary domain.
+Your documentation is now live at your chosen subpath for your primary domain.
 
 <Propagating />

advanced/subpath/vercel.mdx

@@ -1,19 +1,27 @@
 ---
 title: "Vercel"
-description: "Host documentation at a /docs subpath using Vercel"
+description: "Host documentation at a custom subpath using Vercel"
 ---
 
+import { VercelJsonGenerator } from "/snippets/vercel-json-generator.mdx";
+
 ## vercel.json file
 
-The `vercel.json` file is Vercel's configuration file that allows you to customize how your project is built and deployed. It sits in your project's root directory and controls various aspects of your deployment, including routing, redirects, headers, and build settings.
+The `vercel.json` file configures how your project is built and deployed. It sits in your project's root directory and controls various aspects of your deployment, including routing, redirects, headers, and build settings.
 
 We use the `rewrites` configuration to proxy requests from your main domain to your documentation.
 
-Rewrites allow you to 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 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.
+
+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 `/docs` subpath using Vercel, add the following configuration to your `vercel.json` file:
+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
 {
@@ -31,29 +39,34 @@
 ```
 
 - **`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 `/docs/`.
-
+- **`: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
+
+Enter your subdomain and custom subdirectory to generate the rewrites for your `vercel.json` file.
+
+<VercelJsonGenerator />
+
 ## Using external proxies with Vercel
 
 If you're using an external proxy (like Cloudflare or AWS CloudFront) in front of your Vercel deployment, you must configure it properly to avoid conflicts with Vercel's domain verification and SSL certificate provisioning.
 
 Improper proxy configuration can prevent Vercel from provisioning Let's Encrypt SSL certificates and cause domain verification failures.
 
 See the [supported providers](https://vercel.com/guides/how-to-setup-verified-proxy#supported-providers-verified-proxy-lite) in the Vercel documentation.
 
 ### Required path allowlist
 
 Your external proxy must allow traffic to these specific paths without blocking, redirecting, or heavily caching:
 
 - `/.well-known/acme-challenge/*` - Required for Let's Encrypt certificate verification
 - `/.well-known/vercel/*` - Required for Vercel domain verification
 - `/mintlify-assets/_next/static/*` - Required for static assets
 
 These paths should pass through directly to your Vercel deployment without modification.
 
 ### Header forwarding requirements
 
@@ -64,5 +77,5 @@
 To verify your proxy is correctly configured:
 
 1. Test that `https://[yourdomain].com/.well-known/vercel/` returns a response.
 2. Ensure SSL certificates are provisioning correctly in your Vercel dashboard.
 3. Check that domain verification completes successfully.

snippets/vercel-json-generator.mdx

@@ -0,0 +1,94 @@
+export const VercelJsonGenerator = () => {
+  const [subdomain, setSubdomain] = useState('[SUBDOMAIN]')
+  const [subdirectory, setSubdirectory] = useState('docs')
+
+  const vercelConfig = {
+    rewrites: [
+      {
+        source: "/api/request",
+        destination: `https://${subdomain}.mintlify.app/api/request`
+      },
+      {
+        source: `/${subdirectory}`,
+        destination: `https://${subdomain}.mintlify.app`
+      },
+      {
+        source: `/${subdirectory}/llms.txt`,
+        destination: `https://${subdomain}.mintlify.app/llms.txt`
+      },
+      {
+        source: `/${subdirectory}/llms-full.txt`,
+        destination: `https://${subdomain}.mintlify.app/llms-full.txt`
+      },
+      {
+        source: `/${subdirectory}/sitemap.xml`,
+        destination: `https://${subdomain}.mintlify.app/sitemap.xml`
+      },
+      {
+        source: `/${subdirectory}/robots.txt`,
+        destination: `https://${subdomain}.mintlify.app/robots.txt`
+      },
+      {
+        source: `/${subdirectory}/:path*`,
+        destination: `https://${subdomain}.mintlify.app/${subdirectory}/:path*`
+      },
+      {
+        source: "/mintlify-assets/:path+",
+        destination: `https://${subdomain}.mintlify.app/mintlify-assets/:path+`
+      }
+    ]
+  }
+
+  const copyToClipboard = () => {
+    navigator.clipboard
+      .writeText(JSON.stringify(vercelConfig, null, 2))
+      .then(() => {
+        console.log('Copied config to clipboard!')
+      })
+      .catch((err) => {
+        console.error("Failed to copy: ", err)
+      })
+  }
+
+  return (
+    <div className="p-4 border dark:border-white/10 rounded-2xl not-prose space-y-4">
+      <div className="space-y-4">
+        <div>
+          <label className="block text-sm text-zinc-950/70 dark:text-white/70 mb-1">
+            Subdomain
+          </label>
+          <input
+            type="text"
+            value={subdomain}
+            onChange={(e) => setSubdomain(e.target.value)}
+            placeholder="your-subdomain"
+            className="w-full p-1 text-sm rounded border dark:border-white/10 bg-transparent"
+          />
+        </div>
+        <div>
+          <label className="block text-sm text-zinc-950/70 dark:text-white/70 mb-1">
+            Subdirectory
+          </label>
+          <input
+            type="text"
+            value={subdirectory}
+            onChange={(e) => setSubdirectory(e.target.value)}
+            placeholder="docs"
+            className="w-full p-1 text-sm rounded border dark:border-white/10 bg-transparent"
+          />
+        </div>
+      </div>
+      <div className="relative">
+        <button
+          onClick={copyToClipboard}
+          className="absolute top-2 right-2 px-2 py-1 text-sm border dark:border-white/10 rounded hover:bg-zinc-950/5 dark:hover:bg-white/5 transition-colors bg-white"
+        >
+          Copy to Clipboard
+        </button>
+        <pre className="bg-zinc-950/5 dark:bg-white/5 p-4 rounded-lg overflow-auto text-xs">
+          <code>{JSON.stringify(vercelConfig, null, 2)}</code>
+        </pre>
+      </div>
+    </div>
+  )
+}