Merge branch 'main' into ricky/advanced-footer

Author: hahnbeelee

.DS_Store

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

.gitignore

@@ -9,9 +9,9 @@ description: 'Add JavaScript functionality globally'
 
 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/custom/js.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/rest-api/overview.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
+    - 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">
@@ -25,8 +25,54 @@ If you don’t have a dashboard, or if you want to keep your dashboard and docs
 
 ## 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`

advanced/user-auth/jwt.mdx

@@ -9,6 +9,8 @@ You can add an authentication method to your mint.json to enable it on every pag
 
 The page's authentication method will override mint.json if both are set.
 
+### Bearer Token
+
 <CodeGroup>
 
 ```json mint.json
@@ -19,7 +21,7 @@ The page's authentication method will override mint.json if both are set.
 }
 ```
 
-```md page metadata
+```md Page Metadata
 ---
 title: "Your page title"
 authMethod: "bearer"
@@ -28,36 +30,58 @@ authMethod: "bearer"
 
 </CodeGroup>
 
-## Supported Authentication Methods
-
-- bearer
-- basic
-- none
-
-The "none" authentication method is useful to disable authentication on a specific endpoint after setting a default in mint.json.
-
-## Authentication Name
+### Basic Authentication
 
-By default, basic authentication asks for username and password. However, basic authentication can use a different name for username and password. For example, you could have called it `user-id:user-key`.
-
-You can set the name property in mint.json to override the default functionality. Use colons to separate each property you want to request.
+<CodeGroup>
 
-```json Custom username and password
+```json mint.json
 "api": {
     "auth": {
-        "method": "basic",
-        "name": "user-id:user-key"
+        "method": "basic"
     }
 }
 ```
 
-You can also request a single API key by excluding the colon.
+```md Page Metadata
+---
+title: "Your page title"
+authMethod: "basic"
+---
+```
+
+</CodeGroup>
 
-```json Custom username and password
+### API Key
+
+<CodeGroup>
+
+```json mint.json
 "api": {
     "auth": {
         "method": "key",
-        "name": "my-api-key"
+        "name": "x-api-key"
     }
 }
 ```
+
+```md Page Metadata
+---
+title: "Your page title"
+authMethod: "key"
+---
+```
+
+</CodeGroup>
+
+### None
+
+The "none" authentication method is useful to disable authentication on a specific endpoint after setting a default in mint.json.
+
+<CodeGroup>
+```md Page Metadata
+---
+title: "Your page title"
+authMethod: "none"
+---
+```
+</CodeGroup>

api-playground/mdx/authentication.mdx

@@ -0,0 +1,84 @@
+---
+title: "Troubleshooting"
+description: "Common issues with API References"
+icon: "triangle-exclamation"
+---
+
+API pages are complicated. As a result, there are a lot of things that can go wrong.
+Here's a list of common issues we've seen customers run into:
+
+<AccordionGroup>
+  <Accordion title="All of my OpenAPI pages are completely blank">
+    In this scenario, it's likely that either Mintlify cannot find your OpenAPI document,
+    or your OpenAPI document is invalid.
+
+    Running `mintlify dev` locally should reveal some of these issues.
+
+    To verify your OpenAPI document will pass validation:
+
+    1. Visit [this validator](https://apitools.dev/swagger-parser/online/)
+    2. Switch to the "Validate text" tab
+    3. Paste in your OpenAPI document
+    4. Click "Validate it!"
+
+    If the text box that appears below has a green border, your document has passed validation.
+    This is the exact validation package Mintlify uses to validate OpenAPI documents, so if your document
+    passes validation here, there's a great chance the problem is elsewhere.
+
+    Additionally, Mintlify does not support OpenAPI 2.0. If your document uses this version of the specification,
+    you could encounter this issue. You can convert your document at [editor.swagger.io](https://editor.swagger.io/) (under Edit > Convert to OpenAPI 3):
+
+    <Frame>
+      <img src="/images/convert-oas-3.png" />
+    </Frame>
+
+  </Accordion>
+
+  <Accordion title="One of my OpenAPI pages is completely blank">
+    This is usually caused by a misspelled `openapi` field in the page metadata. Make sure
+    the HTTP method and path match the HTTP method and path in the OpenAPI document exactly.
+
+    Here's an example of how things might go wrong:
+
+```md get-user.mdx
+---
+openapi: "GET /users/{id}/"
+---
+```
+
+```yaml openapi.yaml
+paths:
+  "/users/{id}":
+    get: ...
+```
+
+    Notice that the path in the `openapi` field has a trailing slash, whereas the path in the OpenAPI
+    document does not.
+
+    Another common issue is a misspelled filename. If you are specifying a particular OpenAPI document
+    in the `openapi` field, ensure the filename is correct. For example, if you have two OpenAPI
+    documents `openapi/v1.json` and `openapi/v2.json`, your metadata might look like this:
+
+```md api-reference/v1/users/get-user.mdx
+---
+openapi: "v1 GET /users/{id}"
+---
+```
+
+  </Accordion>
+
+  <Accordion title="Requests from the API Playground don't work">
+    If you have a custom domain configured, this could be an issue with your reverse proxy. By
+    default, requests made via the API Playground start with a `POST` request to the
+    `/api/request` path on the docs site. If your reverse proxy is configured to only allow `GET`
+    requests, then all of these requests will fail. To fix this, configure your reverse proxy to
+    allow `POST` requests to the `/api/request` path.
+
+    Alternatively, if your reverse proxy prevents you from accepting `POST` requests, you can configure
+    Mintlify to send requests directly to your backend with the `api.playground.disableProxy`
+    setting in the `mint.json`, as described [here](/settings/global#api-configurations). This will
+    likely require you to configure CORS on your server, as these requests will now come directly
+    from your users' browsers.
+
+  </Accordion>
+</AccordionGroup>

api-playground/troubleshooting.mdx

@@ -0,0 +1,30 @@
+---
+title: "July 2024"
+description: "Introducing the Mintlify Widget and the Pro plan"
+---
+
+## Mintlify Widget
+
+For `Pro` users, we introduced Mintlify Widget, an extension of your docs to
+answer your users' questions when and where they asked. You can add this
+AI-powered chatbot to any web page: your landing page, inside your product, or
+on your existing documentation pages.
+
+- [Read the blog announcement](https://mintlify.com/blog/widget)
+- [Learn how to install the Widget](/advanced/widget/chat#getting-started)
+
+## Pro Plan
+
+We also updated our pricing plans for better customizability and scale.
+
+- [Read the blog announcement](https://mintlify.com/blog/pro-plan)
+
+## API Playground Code Example Sync
+
+When you browse API docs, the selected code example now syncs across your pages.
+
+## Insights
+
+Currently in beta, this feature summarizes common user questions and patterns
+into easy-to-digest reports with AI-powered suggestions on how to improve your
+product.

changelog/2024-07.mdx

@@ -0,0 +1,38 @@
+---
+title: "August 2024"
+description: "Web Editor UI, API Playground Update, and AI Chat"
+---
+
+## OpenAPI Reference Pages
+
+- Endpoints defined by OpenAPI that are complex and recursive are now 98%
+  smaller.
+- We now show
+  [additionalProperties](https://swagger.io/docs/specification/data-models/dictionaries/)
+  in OpenAPI pages.
+
+## File Uploads in API Playground
+
+By default, API playground requests are proxied by Mintlify. Now you can use
+`disableProxy` to disable this behavior and support request types like file
+uploads.
+
+- [Learn more about API configurations](/settings/global#api-configurations)
+
+## Mobile SEO improvements
+
+We've fixed the mobile layout of our docs so that they are more SEO-friendly -
+including adding proper aria tags to elements.
+
+## Support Form
+
+We added a more detailed support form to the Mintlify dashboard. You can now
+submit a form to get in touch with us.
+
+## Bug Fixes
+
+- Fixed a bug for the Segment integration functionality.
+- We now raise more granular error messages for GitHub permissions when
+  interacting with the editor.
+- Fixed bugs where the navigation would not properly expand when a direct link
+  was used.

changelog/2024-08.mdx

@@ -0,0 +1,23 @@
+---
+title: "September 2024"
+description: "Speed improvements and JWT Auth"
+---
+
+<Info>Last updated on: **2024-09-15**</Info>
+
+## Update Speed Performances
+
+For large projects (~3,000 files), the download step for docs updates is now
+~440x faster - a 99.8% time reduction. Across the board, file downloads during
+updates are now ~5.5x faster - an 81.8% time reduction.
+
+## Desktop SEO improvements
+
+The navbar hierarchy follows the aria hierarchy. We also added an aria label to
+the light/dark mode toggle.
+
+## More
+
+- **Troubleshooting for API pages**: API pages could be complicated so we listed
+  common issues to help you sort them out quickly —
+  [Read the docs](/api-playground/troubleshooting)