diff --git a/advanced/subpath/cloudflare.mdx b/advanced/subpath/cloudflare.mdx index 549605e2..0ec1430a 100644 --- a/advanced/subpath/cloudflare.mdx +++ b/advanced/subpath/cloudflare.mdx @@ -1,16 +1,20 @@ --- 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. Before you begin, you need a Cloudflare account and a domain name (can be managed on or off Cloudflare). +## 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. @@ -43,7 +47,7 @@ Ensure that the `HOST` header is correctly forwarded in your Worker configuratio 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. - 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. ```javascript @@ -128,7 +132,7 @@ If you use Webflow to host your main site and want to serve Mintlify docs at `/d 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. - Replace `[SUBDOMAIN]` with your unique subdomain, `[YOUR_DOMAIN]` with your website's base URL, and `[LANDING_DOMAIN]` with your landing page URL. + 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. ```javascript addEventListener("fetch", (event) => { diff --git a/advanced/subpath/route53-cloudfront.mdx b/advanced/subpath/route53-cloudfront.mdx index 96fe460a..a39be3c4 100644 --- a/advanced/subpath/route53-cloudfront.mdx +++ b/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 @@ -80,9 +84,9 @@ By this point, you should have two Origins: one with `[SUBDOMAIN].mintlify.app` ## 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. @@ -109,9 +113,9 @@ If `.well-known/*` is too generic, it can be narrowed down to 2 behaviors at a m - `/.well-known/acme-challenge/*` - Required for Let's Encrypt certificate verification -### `/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 @@ Create a behavior with a **Path pattern** of `/docs` with **Origin and origin gr ![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) -### `/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 @@ You can now test if your distribution is set up properly by going to the "Genera ![CloudFront "General" tab with the "Distribution domain name" URL highlighted.](/images/cloudfront/preview-distribution.png) -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 @@ Now, we're going to bring the functionality of the CloudFront distribution into You may need to remove the existing A record if one currently exists. -Your documentation is now live at `/docs` for your primary domain. +Your documentation is now live at your chosen subpath for your primary domain. diff --git a/advanced/subpath/vercel.mdx b/advanced/subpath/vercel.mdx index f8c1aa68..9a8d8f0a 100644 --- a/advanced/subpath/vercel.mdx +++ b/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 { @@ -32,11 +40,16 @@ To host your documentation at a custom `/docs` subpath using Vercel, add the fol - **`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. + + + ## 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. diff --git a/snippets/vercel-json-generator.mdx b/snippets/vercel-json-generator.mdx new file mode 100644 index 00000000..e6c61100 --- /dev/null +++ b/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 ( +
+
+
+ + setSubdomain(e.target.value)} + placeholder="your-subdomain" + className="w-full p-1 text-sm rounded border dark:border-white/10 bg-transparent" + /> +
+
+ + setSubdirectory(e.target.value)} + placeholder="docs" + className="w-full p-1 text-sm rounded border dark:border-white/10 bg-transparent" + /> +
+
+
+ + 
+          {JSON.stringify(vercelConfig, null, 2)}
+
+
+
+ ) +}