Merge branch 'main' into x-mint

Author: ethanpalm

advanced/subpath/cloudflare.mdx

@@ -19,6 +19,25 @@ Create a Cloudflare Worker by following the [Cloudflare Workers getting started
   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.
+
+#### Header forwarding requirements
+
+Ensure that the `HOST` header is correctly forwarded in your Worker configuration. Failure to properly forward headers will cause verification requests to fail.
+
 ### Configure routing
 
 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.
@@ -35,6 +54,12 @@ addEventListener("fetch", (event) => {
 async function handleRequest(request) {
   try {
     const urlObject = new URL(request.url);
+    
+    // If the request is to a Vercel verification path, allow it to pass through
+    if (urlObject.pathname.startsWith('/.well-known/')) {
+      return await fetch(request);
+    }
+    
     // If the request is to the docs subdirectory
     if (/^\/docs/.test(urlObject.pathname)) {
       // Then Proxy to Mintlify
@@ -49,11 +74,13 @@ async function handleRequest(request) {
       proxyRequest.headers.set("Host", DOCS_URL);
       proxyRequest.headers.set("X-Forwarded-Host", CUSTOM_URL);
       proxyRequest.headers.set("X-Forwarded-Proto", "https");
+      // If deploying to Vercel, preserve client IP
+      proxyRequest.headers.set("CF-Connecting-IP", request.headers.get("CF-Connecting-IP"));
 
       return await fetch(proxyRequest);
     }
   } catch (error) {
-    // if no action found, play the regular request
+    // If no action found, play the regular request
     return await fetch(request);
   }
 }
@@ -110,6 +137,12 @@ If you use Webflow to host your main site and want to serve Mintlify docs at `/d
   async function handleRequest(request) {
   try {
     const urlObject = new URL(request.url);
+    
+    // If the request is to a Vercel verification path, allow it to pass through
+    if (urlObject.pathname.startsWith('/.well-known/')) {
+      return await fetch(request);
+    }
+    
     // If the request is to the docs subdirectory
     if (/^\/docs/.test(urlObject.pathname)) {
       // Proxy to Mintlify
@@ -121,6 +154,8 @@ If you use Webflow to host your main site and want to serve Mintlify docs at `/d
       proxyRequest.headers.set("Host", DOCS_URL);
       proxyRequest.headers.set("X-Forwarded-Host", CUSTOM_URL);
       proxyRequest.headers.set("X-Forwarded-Proto", "https");
+      // If deploying to Vercel, preserve client IP
+      proxyRequest.headers.set("CF-Connecting-IP", request.headers.get("CF-Connecting-IP"));
       return await fetch(proxyRequest);
     }
     // Route everything else to main site

advanced/subpath/route53-cloudfront.mdx

@@ -6,6 +6,31 @@ description: "Host documentation at a /docs subdirectory 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.
+
+## Proxies with Vercel deployments
+
+If you use AWS CloudFront as a proxy with Vercel deployments, you must configure CloudFront to avoid interfering with Vercel's domain verification and SSL certificate provisioning.
+
+Improper CloudFront configuration can prevent Vercel from provisioning Let's Encrypt SSL certificates and cause domain verification failures.
+
+### Required path allowlist
+
+CloudFront must allow traffic to these specific paths without caching or blocking:
+
+- `/.well-known/acme-challenge/*` - Required for Let's Encrypt certificate verification
+- `/.well-known/vercel/*` - Required for Vercel domain verification
+
+These paths should be configured to bypass CloudFront caching and pass through directly to your origin.
+
+### Header forwarding requirements
+
+Ensure that CloudFront forwards the `HOST` header and client IP information correctly. This is critical for Vercel's verification processes.
+
+When using CloudFront with Vercel deployments, CloudFront automatically adds the `CloudFront-Viewer-Address` header containing the original client's IP address.
+
+Make sure your CloudFront distribution is configured to forward this header to your origin by including it in your origin request policy or cache policy headers configuration.
+
 ## Create Cloudfront Distribution
 
 Navigate to [Cloudfront](https://aws.amazon.com/cloudfront) inside the AWS console and click on `Create distribution`
@@ -70,19 +95,25 @@ Behaviors in Cloudfront enables control over the subpath logic. At a high level,
 - **If a user lands on /docs**, go to `[SUBDOMAIN].mintlify.dev`
 - **If a user lands on any other page**, go the current landing page
 
-We're going to create three behaviors by clicking on the `Create behavior` button.
+Select the **Create behavior** button and create the following behaviors.
+
+### `/.well-known/*`
+
+If you are deploying to Vercel, create a behavior for Vercel verification paths with a **Path pattern** of `/.well-known/*` and **Origin and origin groups** pointing to your main origin (the staging URL).
+
+For **Cache policy**, select `CachingDisabled` to ensure these verification requests pass through without caching.
 
 ### `/docs/*`
 
-The first behavior should have 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 `/docs/*` with **Origin and origin groups** pointing to the `.mintlify.dev` URL (in our case `acme.mintlify.dev`)
 
 <Frame>![Cloudfront Behavior 1](/images/cloudfront/behavior-1.png)</Frame>
 
 For **Cache policy**, select `CachingOptimized` and create behavior.
 
 ### `/docs`
 
-The second behavior should be the same as the first one but 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 `/docs` and **Origin and origin groups** pointing to the same `.mintlify.dev` URL.
 
 <Frame>![Cloudfront Behavior 2](/images/cloudfront/behavior-2.png)</Frame>
 

advanced/subpath/vercel.mdx

@@ -3,10 +3,17 @@ title: "Vercel"
 description: "Host documentation at a /docs subpath using Vercel"
 ---
 
-## vercel.json Configuration
+## vercel.json file
 
-To host your documentation at a custom subpath using Vercel, you need to add the
-following configuration to your `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.
+
+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.
+
+## Configuration
+
+To host your documentation at a custom `/docs` subpath using Vercel, add the following configuration to your `vercel.json` file:
 
 ```json
 {
@@ -23,8 +30,38 @@ following configuration to your `vercel.json` file.
 }
 ```
 
-<Note>
-  For more information, you can also refer to Vercel's offical guide on
-  rewrites: [Project Configuration:
-  Rewrites](https://vercel.com/docs/projects/project-configuration#rewrites)
-</Note>
+- **`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/`.
+
+
+For more information, see [Configuring projects with vercel.json: Rewrites](https://vercel.com/docs/projects/project-configuration#rewrites) in the Vercel documentation.
+
+## 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
+
+These paths should pass through directly to your Vercel deployment without modification.
+
+### Header forwarding requirements
+
+Ensure that your proxy correctly forwards the `HOST` header. Without proper header forwarding, verification requests will fail.
+
+### Testing your proxy setup
+
+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.

api-reference/introduction.mdx

@@ -1,28 +1,37 @@
 ---
-title: Introduction
+title: "Introduction"
+description: "Trigger updates, embed AI assistant, and more"
 icon: "book-open"
 ---
 
+The Mintlify REST API enables you to programmatically interact with your documentation, trigger updates, and embed AI-powered chat experiences.
+
+## Endpoints
+
+- [Trigger Update](/api-reference/update/trigger): Trigger an update of your site when desired.
+- [Get Update Status](/api-reference/update/status): Get the status of an update and other details about your docs.
+- [Generate Assistant Message](/api-reference/chat/create-assistant-message): Embed the assistant, trained on your docs, into any application of your choosing.
+
 ## Authentication
 
-You can generate an API key through [the dashboard](https://dashboard.mintlify.com/settings/organization/api-keys). The API key is associated with an entire organization and can be used across multiple deployments.
+You can generate an API key through [the dashboard](https://dashboard.mintlify.com/settings/organization/api-keys). API keys are associated with an entire organization and can be used across multiple deployments.
+
+### Admin API key
+
+The admin API key is used for the majority of the API. It is used to trigger updates and get update status.
 
-<Frame>
-  <img alt="Screenshot of the API keys page in the Mintlify dashboard." src="/images/external-api-key.png" />
-</Frame>
+Admin API keys begin with the `mint_` prefix. Keep your admin API keys secret.
 
-## Admin API key
+### Assistant API key
 
-The Admin API key is used for the majority of the API. It is used to trigger updates via the [Update endpoint](/api-reference/update/trigger).
+The assistant API key is used for generating assistant chat messages through the API. Responses include citations so you can point your users to the right destinations for more information.
 
-## Assistant API key
+Assistant API keys begin with the `mint_dsc_` prefix.
 
-The assistant API allows you to embed the AI assistant, trained on your docs and continually kept up to date, into any application of your choosing.
+The assistant API **key** is a server-side token that should be kept secret.
 
-Responses include citations so you can point your users to the right destinations for more information.
+The assistant API **token** is a public token that can be referenced in your frontend code.
 
 <Note>
-  The assistant API **token** is a public token that can be referenced in your frontend code. The API **key** is a server-side token that should be kept secret.
-  
   Calls using the assistant API token can incur costs: either using your AI chat credits or incurring overages.
 </Note>

navigation.mdx

@@ -435,9 +435,7 @@ We currently support the following languages:
 
 ## Nesting
 
-It's important to note that you can use any combination of anchors, tabs, and dropdowns - either one can be nested within each other interchangeably.
-
-This way, you can create a very complex navigation structure that is easy to manage.
+You can use any combination of anchors, tabs, and dropdowns. The components can be nested within each other interchangeably to create your desired navigation structure.
 
 <CodeGroup>
 
@@ -512,7 +510,6 @@ This way, you can create a very complex navigation structure that is easy to man
 }
 ```
 
-
 ```json Tabs with external anchors
 {
   "navigation": {
@@ -557,3 +554,17 @@ This way, you can create a very complex navigation structure that is easy to man
 ```
 
 </CodeGroup>
+
+---
+
+## Breadcrumbs
+
+Control how breadcrumbs display on individual pages to orient users in your documentation.
+
+```json
+{
+  "styling": {
+    "eyebrows": "breadcrumbs"
+  }
+}
+```