Merge branch 'main' into do_not_merge_anahita_secret_customer_onboarding_page

Author: hahnbeelee

.github/workflows/check-links.yml

@@ -0,0 +1,18 @@
+name: Check links
+
+on: pull_request
+
+jobs:
+  check-links:
+    name: Check links
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+      - name: Set up Node
+        uses: actions/setup-node@v4
+        with:
+          node-version: "latest"
+      - name: Install Mintlify CLI
+        run: npm i -g mintlify
+      - name: Run broken link checker
+        run: mintlify broken-links

.gitignore

@@ -0,0 +1,3 @@
+.DS_Store
+node_modules
+package-lock.json

advanced/custom/css.mdx

@@ -4,7 +4,7 @@ description: 'Fully customize your documentation with custom CSS'
 ---
 
 <Check>
-  Custom CSS is available on the [growth plan](https://mintlify.com/pricing).
+  Custom CSS is available as an add-on to the [pro plan](https://mintlify.com/pricing).
 </Check>
 
 Add any number of CSS files to your repository and the defined class names will be applied and available across all of your MDX files.

advanced/custom/js.mdx

@@ -4,14 +4,14 @@ description: 'Add JavaScript functionality globally'
 ---
 
 <Check>
-  Custom JS is available on the [growth plan](https://mintlify.com/pricing).
+  Custom JS is available as an add-on to the [pro plan](https://mintlify.com/pricing).
 </Check>
 
 Custom JS allows you to add custom executable code globally. It is the equivalent of adding a `<script>` tag with JS code into every page.
 
-## Adding script.js
+## Adding Custom JavaScript
 
-For example, you can add the following `script.js` file to enable [Google Analytics](https://marketingplatform.google.com/about/analytics) across the entire documentation.
+Any `.js` file inside the content directory of your docs will be included in every documentation page. For example, you can add the following `ga.js` file to enable [Google Analytics](https://marketingplatform.google.com/about/analytics) across the entire documentation.
 
 ```js
 window.dataLayer = window.dataLayer || [];

advanced/rest-api/overview.mdx

@@ -14,7 +14,7 @@ functionality to the API overtime. Let us know what else you want to see in
 ## Authentication
 
 You can generate an API key through
-[the dashboard](https://dashboard.mintlify.com/settings/api). The API key is
+[the dashboard](https://dashboard.mintlify.com/settings/integrations). The API key is
 associated with the entire org and can be used across multiple deployments.
 
 <Frame>

advanced/subpath/cloudflare.mdx

@@ -5,7 +5,7 @@ description: "Host documentation at a /docs subpath using Cloudflare Workers"
 
 import SubpathGatingSnippet from "/snippets/custom-subpath-gating.mdx";
 
-<SubpathGatingSnippet />
+<SubpathGatingSnippet platform="Cloudflare" />
 
 ## Create Cloudflare Worker
 
@@ -21,7 +21,7 @@ Cloudlfare worker.
 
 Once the worker is created, click `Configure worker`. Navigate to the worker
 `Settings > Triggers`. Click on `Add Custom Domain` to add your desired domain
-into the list - we reccommend you add both the version with and without `www.`
+into the list - we recommend you add both the version with and without `www.`
 prepended to the domain.
 
 <Frame>
@@ -77,16 +77,8 @@ async function handleRequest(request) {
     // if no action found, play the regular request
     return await fetch(request);
   }
-
-  return await fetch(request);
 }
 ```
 
 Click on `Deploy` and wait for the changes to propagate (it can take up to a few
 hours).
-
-## Reach out to Mintlify team
-
-Once completing the Cloudflare setup, the Mintlify team will setup the
-subdirectory settings in your deployment. Reach out over
-[email](mailto:[email protected]).

advanced/subpath/route53-cloudfront.mdx

@@ -5,7 +5,7 @@ description: "Host documentation at a /docs subdirectory using AWS services"
 
 import SubpathGatingSnippet from "/snippets/custom-subpath-gating.mdx";
 
-<SubpathGatingSnippet />
+<SubpathGatingSnippet platform="AWS Services" />
 
 ## Create Cloudfront Distribution
 

advanced/subpath/vercel.mdx

@@ -0,0 +1,34 @@
+---
+title: "Vercel"
+description: "Host documentation at a /docs subpath using Vercel"
+---
+
+import SubpathGatingSnippet from "/snippets/custom-subpath-gating.mdx";
+
+<SubpathGatingSnippet platform="Vercel" />
+
+## vercel.json Configuration
+
+To host your documentation at a custom subpath using Vercel, you need to add the
+following configuration to your `vercel.json` file.
+
+```json
+{
+  "rewrites": [
+    {
+      "source": "/docs",
+      "destination": "https://[subdomain].mintlify.dev/docs"
+    },
+    {
+      "source": "/docs/:match*",
+      "destination": "https://[subdomain].mintlify.dev/docs/:match*"
+    }
+  ]
+}
+```
+
+<Note>
+  For more information, you can also refer to Vercel's offical guide on check
+  out the [Project Configuration:
+  Rewrites](https://vercel.com/docs/projects/project-configuration#rewrites)
+</Note>

advanced/user-auth/choosing-an-auth-method.mdx

@@ -7,6 +7,7 @@ Before your users can access personalized content, they must be authenticated. M
 
 1. **Shared Session**: Utilize the same session token used by your dashboard to authenticate users.
 2. **JWT**: Use your own login flow to send user info to your docs via a JWT in the URL.
+3. **OAuth 2.0**: Integrate with your OAuth server to enable user login via the PKCE flow.
 
 ## Prerequisites
 
@@ -23,10 +24,15 @@ Before your users can access personalized content, they must be authenticated. M
       - If your dashboard is at `*.foo.com`, your **docs** must be hosted at `foo.com` or `*.foo.com`
   </Tab>
   <Tab title="JWT">
-  
+
     - You have some existing login flow.
     - You can add a final step in this login flow that creates a JWT and redirects to the docs.
   </Tab>
+  <Tab title="OAuth 2.0">
+
+    - You have an existing OAuth server that supports the PKCE flow.
+    - You can create a new API endpoint that can be accessed by the returned OAuth access token.
+  </Tab>
 </Tabs>
 
 ## Pros & Cons
@@ -42,20 +48,34 @@ Before your users can access personalized content, they must be authenticated. M
     Cons:
 
     - Your docs will make a request to your backend, which may be undesirable
+    - You must have a dashboard that uses session authentication
+    - CORS configuration is usually required
   </Tab>
   <Tab title="JWT">
     Pros:
 
-    - No dashboard needed
     - Reduced risk of API endpoint abuse
     - Zero CORS configuration
+    - No restrictions on API URLs
 
     Cons:
 
-    - Must build new functionality around your existing login flow
+    - Must be able to hook into your existing login flow
     - Dashboard sessions and docs authentication are completely decoupled, so users will need to log in to your dashboard and your docs separately
     - Every time you want to refresh user data, your users must re-login to your docs
       - If your users' data changes frequently, you must require your users to log in frequently or risk having stale data in the docs
       - If your users' data rarely changes, this shouldn't be a problem
   </Tab>
+  <Tab title="OAuth 2.0">
+    Pros:
+
+    - Heightened security standard
+    - No restrictions on API URLs
+
+    Cons:
+
+    - Requires significant work if setting up OAuth server for the first time
+    - Dashboard sessions and docs authentication are completely decoupled, so users will need to log in to your dashboard and your docs separately
+    - Might be overkill for some applications
+  </Tab>
 </Tabs>

advanced/user-auth/jwt.mdx

@@ -9,24 +9,70 @@ If you don’t have a dashboard, or if you want to keep your dashboard and docs
 
 <Steps>
   <Step title="Generate a private key">
-    Go to your [Mintlify dashboard settings](https://dashboard.mintlify.com/settings/integrations) and generate a private key. Store this key somewhere secure where it can be accessed by your backend.
+    Go to your [Mintlify dashboard settings](https://dashboard.mintlify.com/mintlify/mintlify/settings/deployment/user-authentication) and generate a private key. Store this key somewhere secure where it can be accessed by your backend.
   </Step>
   <Step title="Create a login flow">
     Create a login flow that does the following:
     - Authenticate the user
     - Create a JWT containing the authenticated user's info in the [UserInfo](./sending-data) format
-    - Sign the JWT with the secret
+    - Sign the JWT with the secret, using the ES256 algorithm
     - Create a redirect URL back to your docs, including the JWT as the hash
   </Step>
   <Step title="Configure your User Auth settings">
-    Return to your [Mintlify dashboard settings](https://dashboard.mintlify.com/settings/integrations) and add the login URL to your User Auth settings.
+    Return to your [Mintlify dashboard settings](https://dashboard.mintlify.com/mintlify/mintlify/settings/deployment/user-authentication) and add the login URL to your User Auth settings.
   </Step>
 </Steps>
 
 ## Example
 
-I want to set up authentication for my docs hosted at `docs.foo.com`. I want my docs to be completely separate from my dashboard (or I don’t have a dashboard at all).
+I want to set up authentication for my docs hosted at `docs.foo.com`. I want my docs
+to be completely separate from my dashboard (or I don’t have a dashboard at all).
 
-To set up authentication with Mintlify, I go to my Mintlify dashboard and generate a JWT secret. I create a web URL `https://foo.com/docs-login` that initiates a login flow for my users. At the end of this login flow, once I have verified the identity of the user, I create a JWT containing the user’s custom data according to Mintlify’s specification. I sign this JWT with my Mintlify secret, create a redirect URL of the form `https://docs.foo.com#{SIGNED_JWT}`, and redirect the user.
+To set up authentication with Mintlify, I go to my Mintlify dashboard and generate a
+JWT secret. I create a web URL `https://foo.com/docs-login` that initiates a login flow
+for my users. At the end of this login flow, once I have verified the identity of the user,
+I create a JWT containing the user’s custom data according to Mintlify’s specification.
+I use a JWT library to sign this JWT with my Mintlify secret, create a redirect URL of the
+form `https://docs.foo.com#{SIGNED_JWT}`, and redirect the user.
 
-I then go to the Mintlify dashboard settings and enter `https://foo.com/docs-login` for the Login URL field.
+I then go to the Mintlify dashboard settings and enter `https://foo.com/docs-login` for the
+Login URL field.
+
+Here's what the code might look like:
+
+```ts
+import * as jose from 'jose';
+import { Request, Response } from 'express';
+
+const TWO_WEEKS_IN_MS = 1000 * 60 * 60 * 24 * 7 * 2;
+
+const signingKey = await jose.importPKCS8(process.env.MINTLIFY_PRIVATE_KEY, 'ES256');
+
+export async function handleRequest(req: Request, res: Response) {
+  const userInfo = {
+    expiresAt: Math.floor((Date.now() + TWO_WEEKS_IN_MS) / 1000),
+    groups: res.locals.user.groups,
+    content: {
+      firstName: res.locals.user.firstName,
+      lastName: res.locals.user.lastName,
+    },
+  };
+
+  const jwt = await new jose.SignJWT(userInfo)
+    .setProtectedHeader({ alg: 'ES256' })
+    .setExpirationTime('10 s')
+    .sign(signingKey);
+
+  return res.redirect(`https://docs.foo.com#${jwt}`);
+}
+
+```
+
+## Preserving Anchors
+
+Post-login, if you'd like to redirect to a specific anchor on the page, you can use the following format to create the redirect URL: `https://docs.foo.com/page#jwt={SIGNED_JWT}&anchor={ANCHOR}`.
+
+Example:
+
+- Original: `https://docs.foo.com/quickstart#step-one`
+- Redirect: `https://docs.foo.com/quickstart#jwt={SIGNED_JWT}&anchor=step-one`