Merge branch 'main' into improve-documentation-readability-and-onboarding-84e45ba7

Author: hahnbeelee

.github/workflows/index-sitemap.yml

@@ -0,0 +1,24 @@
+name: Index docs
+
+on:
+  schedule:
+    - cron: "0 */3 * * *"  
+
+jobs:
+  lint:
+    name: Lint
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v2
+
+      - uses: actions/setup-node@v3
+        with:
+          node-version: '18'
+
+      - name: Install CLI
+        run: npm install -g @team-plain/cli@latest
+        
+      - name: Index Docs
+        run: plain index-sitemap https://mintlify.com/docs/sitemap.xml
+        env:
+          PLAIN_API_KEY: ${{ secrets.PLAIN_API_KEY }}

advanced/rest-api/discovery/create-topic.mdx renamed to advanced/rest-api/chat/create-topic.mdx

@@ -19,24 +19,24 @@ associated with the entire org and can be used across multiple deployments.
   <img src="/images/external-api-key.png" />
 </Frame>
 
-## Discovery API
+## Chat API
 
-The Discovery API allows you to embed an AI chat experience grounded in your docs and continually kept up to date into any application of your choosing.
+The Chat API allows you to embed an AI chat experience grounded in your docs and continually kept up to date into any application of your choosing.
 Responses include citations so you can point your users to the right places they need to get help.
 
 ## Getting Started
 
-To get started, you'll need to generate a Discovery API key in the [dashboard](https://dashboard.mintlify.com/products/chat/widget):
+To get started, you'll need to generate a Chat API key in the [dashboard](https://dashboard.mintlify.com/products/chat/widget):
 
 <Frame>
   <img
-    alt="Create a Discovery API key"
+    alt="Create a Chat API key"
     src="/images/generate-discovery-api-key.png"
   />
 </Frame>
 
 <Note>
-  The Discovery API token is a public token that can be referenced in your
+  The Chat API token is a public token that can be referenced in your
   frontend code whereas the API key is a server-side token that should be kept
   secret.
 </Note>

advanced/rest-api/discovery/generate-message.mdx renamed to advanced/rest-api/chat/generate-message.mdx

@@ -5,18 +5,20 @@ description: "You can set authentication parameters to let users use their real
 
 ## Enabling Authentication
 
-You can add an authentication method to your mint.json to enable it on every page or you can set it on a per-page basis.
+You can add an authentication method to your docs.json to enable it on every page or you can set it on a per-page basis.
 
-The page's authentication method will override mint.json if both are set.
+The page's authentication method will override docs.json if both are set.
 
 ### Bearer Token
 
 <CodeGroup>
 
-```json mint.json
+```json docs.json
 "api": {
-    "auth": {
+    "mdx": {
+      "auth": {
         "method": "bearer"
+      }
     }
 }
 ```
@@ -34,10 +36,12 @@ authMethod: "bearer"
 
 <CodeGroup>
 
-```json mint.json
+```json docs.json
 "api": {
-    "auth": {
+    "mdx": {
+      "auth": {
         "method": "basic"
+      }
     }
 }
 ```
@@ -55,11 +59,13 @@ authMethod: "basic"
 
 <CodeGroup>
 
-```json mint.json
+```json docs.json
 "api": {
-    "auth": {
+    "mdx": {
+      "auth": {
         "method": "key",
         "name": "x-api-key"
+      }
     }
 }
 ```
@@ -75,7 +81,7 @@ authMethod: "key"
 
 ### None
 
-The "none" authentication method is useful to disable authentication on a specific endpoint after setting a default in mint.json.
+The "none" authentication method is useful to disable authentication on a specific endpoint after setting a default in docs.json.
 
 <CodeGroup>
 ```md Page Metadata

advanced/rest-api/overview.mdx

@@ -3,18 +3,19 @@ title: 'MDX Setup'
 description: 'Generate docs pages for your API endpoints using MDX'
 ---
 
-Mintlify allows you to define your API endpoints using a combination of `mint.json` configuration, MDX metadata fields, and the `<ParamFields />` component. From the defined endpoints, we generate an API playground, request examples, and response examples.
+Mintlify allows you to define your API endpoints using a combination of `docs.json` configuration, MDX metadata fields, and the `<ParamFields />` component. From the defined endpoints, we generate an API playground, request examples, and response examples.
 
 <Steps>
   <Step title="Configure your API">
-    In your `mint.json` file, define your base URL and auth method:
+    In your `docs.json` file, define your base URL and auth method:
 
     ```json
-    {
-      "api": {
-        "baseUrl": "https://mintlify.com/api", // string array for multiple base URLs
+     "api": {
+      "mdx": {
+        "server": "https://mintlify.com/api", // string array for multiple base URLs
         "auth": {
-          "method": "bearer" // options: bearer, basic, key.
+          "method": "key",
+          "name": "x-api-key" // options: bearer, basic, key.
         }
       }
     }
@@ -23,16 +24,14 @@ Mintlify allows you to define your API endpoints using a combination of `mint.js
     If you would not like to show an API playground, you don't need to include auth types. Hide the playground with the following field:
 
     ```json
-    {
-      "api": {
-        "playground": {
-          "mode": "hide"
-        }
+    "api": {
+      "playground": {
+        "display": "none"
       }
     }
     ```
 
-    Find a full list of API configurations [here](/settings/global#api-configurations).
+    Find a full list of API configurations [here](/settings/global#param-api).
   </Step>
 
   <Step title="Create your endpoint pages">
@@ -54,12 +53,12 @@ Mintlify allows you to define your API endpoints using a combination of `mint.js
 
     <Note>
 
-    If you have `baseUrl` configured in [mint.json](/settings/global), you can use relative paths like `/v1/endpoint`.
+    If you have `server` configured in [docs.json](/settings/global), you can use relative paths like `/v1/endpoint`.
 
     </Note>
   </Step>
 
   <Step title="Add your endpoints to your docs">
-    Add your endpoint pages to the sidebar by adding the paths to the `navigation` field in your `mint.json`. Learn more about structuring your docs [here](/settings/navigation).
+    Add your endpoint pages to the sidebar by adding the paths to the `navigation` field in your `docs.json`. Learn more about structuring your docs [here](/settings/navigation).
   </Step>
 </Steps>

api-playground/mdx/authentication.mdx

@@ -8,48 +8,47 @@ description: "Reference OpenAPI endpoints in your docs pages"
 To describe your endpoints with OpenAPI, make sure you have a valid OpenAPI
 document in either JSON or YAML format that follows the
 [OpenAPI specification](https://swagger.io/specification/). Your document must
-follow OpenAPI specification 3.0+.
+follow OpenAPI specification 3.0+. 
+<Tip>To validate your OpenAPI spec, use our [CLI](https://www.npmjs.com/package/mintlify) and run this command: <br/>`mintlify openapi-check <openapiFilenameOrUrl>`</Tip>
 
 ## Auto-populate API pages
 
-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.
+The fastest way to get started with OpenAPI is to add an `openapi` field to a tab in the `docs.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.
 
-**Example with Anchors:**
 
+**Example with Tabs:**
 ```json {5}
-{
-  "anchors": [
+"navigation": {
+  "tabs": [
     {
-      "name": "API Reference",
-      "openapi": "/path/to/openapi.json",
-      "url": "api-reference",
-      "icon": "square-terminal"
+        "tab": "API Reference",
+        "openapi": "https://petstore3.swagger.io/api/v3/openapi.json"
     }
   ]
 }
 ```
+![](/images/autogeneration-with-tabs.png)
 
-![](/images/anchors-autogeneration-anchors.png)
-
-**Example with Tabs:**
-
-```json {6}
-{
+**Example with Groups:**
+```json {8-11}
+"navigation": {
   "tabs": [
     {
-      "name": "API Reference",
-      "url": "api-reference",
-      "openapi": "https://petstore3.swagger.io/api/v3/openapi.json"
+      "tab": "API Reference",
+      "groups": [
+        {
+          "group": "Endpoints",
+          "openapi": {
+            "source": "/path/to/openapi-1.json",
+            "directory": "api-reference"
+          }
+        }
+      ]
     }
   ]
 }
 ```
 
-![](/images/autogeneration-with-tabs.png)
-
-<Tip>To validate your OpenAPI spec, you can use this command: <br/>`mintlify openapi-check <openapiFilenameOrUrl>`</Tip>
-
-
 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.
@@ -62,39 +61,9 @@ There are some scenarios in which the default behavior isn't sufficient. If you
 
 ## 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).&#x20;
-
-![](/images/elevenlabs-mdx-autogeneration-example.png)
-
-### 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.
-
-```bash
-npx @mintlify/scraping@latest openapi-file <path-to-openapi-file>
-```
-
-Add the `-o` flag to specify a folder to populate the files into. If a folder is
-not specified, the files will populate in the working directory.
-
-```bash
-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).
-
-The scraper will output an array of
-[Navigation entries](/settings/global#structure) containing your OpenAPI MDX
-files. You can either append these entries to your existing Navigation, or
-reorder and add the files to your navigation manually.
+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/mindsdb/mindsdb/blob/main/docs/rest/databases/create-databases.mdx) from [MindsDB](https://docs.mindsdb.com/rest/databases/create-databases).&#x20;
 
-<Note>
-  If your OpenAPI document is invalid, the files will not autogenerate.
-</Note>
+![](/images/mindsdb.png)
 
 ### Manually specify files
 
@@ -132,6 +101,38 @@ only one OpenAPI file - it will automatically detect your OpenAPI file.
   the page will be empty.
 </Note>
 
+### 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.
+
+```bash
+npx @mintlify/scraping@latest openapi-file <path-to-openapi-file>
+```
+
+Add the `-o` flag to specify a folder to populate the files into. If a folder is
+not specified, the files will populate in the working directory.
+
+```bash
+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).
+
+The scraper will output an array of
+[Navigation entries](/settings/global#structure) containing your OpenAPI MDX
+files. You can either append these entries to your existing Navigation, or
+reorder and add the files to your navigation manually.
+
+<Note>
+  If your OpenAPI document is invalid, the files will not autogenerate.
+</Note>
+
+
+
 ## Create MDX files for OpenAPI schemas
 
 Mintlify also allows you to create individual pages for any OpenAPI schema

api-playground/mdx/configuration.mdx

@@ -76,7 +76,7 @@ openapi: "v1 GET /users/{id}"
 
     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
+    setting in the `docs.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.