Merge branch 'main' into docs/update-changelog-233fc24c

Author: ruhanponnada

advanced/subpath/vercel.mdx

@@ -28,7 +28,7 @@ following configuration to your `vercel.json` file.
 ```
 
 <Note>
-  For more information, you can also refer to Vercel's offical guide on check
-  out the [Project Configuration:
+  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>

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

@@ -3,7 +3,7 @@ title: 'Choosing an Auth Method'
 description: 'How to decide which auth method is right for your docs'
 ---
 
-Before your users can access personalized content, they must be authenticated. Mintlify supports two methods of authenticating users:
+Before your users can access personalized content, they must be authenticated. Mintlify supports three methods of authenticating users:
 
 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.

advanced/user-auth/jwt.mdx

@@ -15,7 +15,7 @@ If you don’t have a dashboard, or if you want to keep your dashboard and docs
     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, using the ES256 algorithm
+    - Sign the JWT with the secret, using the EdDSA algorithm
     - Create a redirect URL back to your docs, including the JWT as the hash
   </Step>
   <Step title="Configure your User Auth settings">
@@ -46,7 +46,7 @@ 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');
+const signingKey = await jose.importPKCS8(process.env.MINTLIFY_PRIVATE_KEY, 'EdDSA');
 
 export async function handleRequest(req: Request, res: Response) {
   const userInfo = {
@@ -59,7 +59,7 @@ export async function handleRequest(req: Request, res: Response) {
   };
 
   const jwt = await new jose.SignJWT(userInfo)
-    .setProtectedHeader({ alg: 'ES256' })
+    .setProtectedHeader({ alg: 'EdDSA' })
     .setExpirationTime('10 s')
     .sign(signingKey);
 

advanced/user-auth/overview.mdx

@@ -3,19 +3,22 @@ title: 'Introduction'
 description: 'Give your users a personalized docs experience'
 ---
 
-User Auth allows you to identify and authenticate your users so that you can personalize docs content for them. your users. 
+User Auth allows you to identify and authenticate your users so that you can personalize docs content for them. Your users.
 
 Example use cases:
 
 1. **Customize MDX content** with a user's information, such as their name, plan, or title.
+
 2. **Prefill API keys** in the API Playground for streamlined use.
+
 3. **Selectively show pages** in the navigation based on a user's groups.
 
 ## What *isn't* User Auth
 
 At this time, User Auth is not meant for the following use cases:
 
 1. **Private docs content.** While you can hide pages from unauthenticated users, those pages are still accessible by anyone who can guess the URL. If your documentation contains sensitive information, User Auth is not enough to hide it.
+
 2. **A Mintlify-backed user database.** Mintlify does not store *any* information about your users. Rather, it relies on your existing infrastructure to serve as the source-of-truth for user data.
 
 <Note>If you are interested in private docs content, [contact our team](mailto:[email protected]) to explore solutions.</Note>
@@ -35,11 +38,11 @@ Hello, {userContext.name ?? 'reader'}!
 This feature becomes even more powerful when paired with custom data about the user. Here's a real world example that allows us to give specific instructions on how to access the User Auth feature based on the customer's existing plan:
 
 User Auth is an enterprise feature. {
-  userContext.org === undefined
-    ? <>To access this feature, first create an account at the <a href="https://dashboard.mintlify.com/login">Mintlify dashboard</a>.</>
-    : userContext.org.plan !== 'enterprise'
-      ? <>You are currently on the ${userContext.org.plan ?? 'free'} plan. To speak to our team about upgrading, <a href="mailto:[email protected]">contact our sales team</a>.</>
-      : <>To request this feature for your enterprise org, <a href="mailto:[email protected]">contact our team</a>.</>
+userContext.org === undefined
+? <>To access this feature, first create an account at the <a href="https://dashboard.mintlify.com/login">Mintlify dashboard</a>.</>
+: userContext.org.plan !== 'enterprise'
+  ? <>You are currently on the ${userContext.org.plan ?? 'free'} plan. To speak to our team about upgrading, <a href="mailto:[email protected]">contact our sales team</a>.</>
+  : <>To request this feature for your enterprise org, <a href="mailto:[email protected]">contact our team</a>.</>
 }
 
 ```jsx
@@ -59,6 +62,7 @@ User Auth is an enterprise feature. {
 ### Prefilling API Keys
 
 If you return API Playground inputs in the user info, they will automatically be prefilled in the API Playground. Make sure the name of the field in the user info is an exact match of the name in the API Playground.
+
 ### Showing/Hiding Pages
 
 By default, every page is visible to every user. If you want to restrict which pages are visible to your users, you can add a `groups` field in your page metadata.
@@ -75,10 +79,10 @@ groups: ['admin']
 
 Here's a table that displays whether a page is shown for different combinations of `groups` in UserInfo and page metadata:
 
-|                                    | `groups` not in UserInfo | `groups: []` in UserInfo | `groups: ['admin']` in UserInfo |
-|:-----------------------------------|:------------------------:|:-------------------------:|:--------------------------------:|
-| `groups` not in metadata           |                        ✅ |                        ✅ |                               ✅ |
-| `groups: []` in metadata           |                        ❌ |                        ❌ |                               ❌ |
-| `groups: ['admin']` in metadata    |                        ❌ |                        ❌ |                               ✅ |
+|                                 | `groups` not in UserInfo | `groups: []` in UserInfo | `groups: ['admin']` in UserInfo |
+| :------------------------------ | :----------------------: | :----------------------: | :-----------------------------: |
+| `groups` not in metadata        |             ✅            |             ✅            |                ✅                |
+| `groups: []` in metadata        |             ❌            |             ❌            |                ❌                |
+| `groups: ['admin']` in metadata |             ❌            |             ❌            |                ✅                |
 
-<Note>Note that an empty array in the page metadata is interpreted as "No groups should see this page."</Note>
+<Note>Note that an empty array in the page metadata is interpreted as "No groups should see this page."</Note>

api-playground/openapi/setup.mdx

@@ -10,16 +10,9 @@ document in either JSON or YAML format that follows the
 [OpenAPI specification](https://swagger.io/specification/). Your document must
 follow OpenAPI specification 3.0+.
 
-## Autogenerating the API playground
+## Auto-populate API pages
 
-You can either [autogenerate the API playground](/settings/navigation#tabs) or
-create MDX files for the individual OpenAPI endpoints.
-
-### Auto-populate API pages
-
-You can add an `openapi` field to an object in the `tabs` or `anchors` array in
-the `mint.json`. This can either be with OpenAPI documents that are in the docs
-repo (json or yaml) or hosted at a link.
+The fastest way to get started with OpenAPI is to add an `openapi` field to a tab or anchor in the `mint.json`. This field can contain either the path to an OpenAPI document in your docs repo, or the URL of a hosted OpenAPI document. Mintlify will automatically generate a page for each OpenAPI operation and place them in the tab/anchor.
 
 **Example with Anchors:**
 
@@ -54,25 +47,29 @@ repo (json or yaml) or hosted at a link.
 
 ![](/images/autogeneration-with-tabs.png)
 
-### Create MDX files for OpenAPI endpoints
+When using this option, the metadata for the generated pages will have the following default values:
+
+* `title`: The `summary` field from the OpenAPI operation, if present. Otherwise a title generated from the HTTP method and endpoint.
+
+* `description`: The `description` field from the OpenAPI operation, if present.
 
-You can also create MDX files associated with each OpenAPI endpoint if you would
-like to add additional context to specific pages or have more granular control
-over the navigation. Here is
-[the code](https://github.com/elevenlabs/elevenlabs-docs/blob/e5e267c97b8d1e4c21db1dcdb8b005eb1dfed7da/api-reference/speech-to-speech.mdx?plain=1#L2)
-from [Elevenlabs](https://elevenlabs.io/docs/api-reference/speech-to-speech).
+* `version`: The `version` value from the anchor or tab, if present.
+
+There are some scenarios in which the default behavior isn't sufficient. If you need more customizability, you can create an MDX page for your OpenAPI operation, and modify it just like any other MDX page.
+
+## Create MDX files for API pages
+
+If you want to customize the page metadata, add additional content, omit certain OpenAPI operations, or reorder OpenAPI pages in your navigation, you'll need an MDX page for each operation. Here is [an example MDX OpenAPI page](https://github.com/elevenlabs/elevenlabs-docs/blob/e5e267c97b8d1e4c21db1dcdb8b005eb1dfed7da/api-reference/speech-to-speech.mdx?plain=1#L2) from [Elevenlabs](https://elevenlabs.io/docs/api-reference/speech-to-speech). 
 
 ![](/images/elevenlabs-mdx-autogeneration-example.png)
 
-If you want to autogenerate MDX files for every endpoint in your OpenAPI
-document you can use our scraper.
+### Autogenerate files
 
-#### Autogenerate files
+For large OpenAPI documents, creating one MDX page for each OpenAPI operation can be a lot of work. To make it easier, we created a local OpenAPI page scraper.
 
 Our Mintlify [scraper](https://www.npmjs.com/package/@mintlify/scraping)
 autogenerates MDX files for your OpenAPI endpoints. Use the relative path to the
-OpenAPI document in your codebase. If you're using a publicly-hosted OpenAPI
-document, you can supply the URL in place of a path.
+OpenAPI document in your codebase.
 
 ```bash
 npx @mintlify/scraping@latest openapi-file <path-to-openapi-file>
@@ -85,8 +82,7 @@ not specified, the files will populate in the working directory.
 npx @mintlify/scraping@latest openapi-file <path-to-openapi-file> -o api-reference
 ```
 
-Learn more about our scraping package
-[here](https://www.npmjs.com/package/@mintlify/scraping).
+Learn more about our scraping package [here](https://www.npmjs.com/package/@mintlify/scraping).
 
 The scraper will output an array of
 [Navigation entries](/settings/global#structure) containing your OpenAPI MDX
@@ -97,38 +93,39 @@ reorder and add the files to your navigation manually.
   If your OpenAPI document is invalid, the files will not autogenerate.
 </Note>
 
-#### Manually specify files
+### Manually specify files
+
+You can always create an MDX page manually, and reference the OpenAPI operation in the page's metadata using the `openapi` field.
 
 <Snippet file="api-playground/openapi.mdx" />
 
 By using the OpenAPI reference, the name, description, parameters, responses,
-and the API playground will be automatically generated using the specifications.
+and the API playground will be automatically generated from the OpenAPI document.
 
-If you have multiple OpenAPI files, include the path to the OpenAPI file to map
-the MDX file to the appropriate OpenAPI file. This is not required if you have
+If you have multiple OpenAPI files, include the path to the OpenAPI file to ensure Mintlify finds the correct OpenAPI document. This is not required if you have
 only one OpenAPI file - it will automatically detect your OpenAPI file.
 
 <CodeGroup>
-
-```md Example
----
-title: "Get users"
-openapi: "/path/to/openapi-1.json GET /users"
----
-```
-
-```md Format
----
-title: "title of the page"
-openapi: openapi-file-path method path
----
-```
-
+  ```md Example
+  ---
+  title: "Get users"
+  openapi: "/path/to/openapi-1.json GET /users"
+  ---
+  ```
+
+  ```md Format
+  ---
+  title: "title of the page"
+  openapi: openapi-file-path method path
+  ---
+  ```
 </CodeGroup>
+
 <br />
+
 <Note>
-  The method endpoint must match the endpoint specified in the OpenAPI
-  specifications exactly. If the endpoint doesn't exist in the OpenAPI file,
+  The method and path must match the method and path specified in the OpenAPI
+  document exactly. If the endpoint doesn't exist in the OpenAPI file,
   the page will be empty.
 </Note>
 
@@ -138,17 +135,15 @@ Mintlify also allows you to create individual pages for any OpenAPI schema
 defined in an OpenAPI document's `components.schemas` field:
 
 <CodeGroup>
-
-```md Example
----
-openapi-schema: OrderItem
----
-```
-
-```md Format
----
-openapi-schema: "schema-key"
----
-```
-
-</CodeGroup>
+  ```md Example
+  ---
+  openapi-schema: OrderItem
+  ---
+  ```
+
+  ```md Format
+  ---
+  openapi-schema: "schema-key"
+  ---
+  ```
+</CodeGroup>