mintlify · ricardonunez-io · Jun 11, 2025 · Jun 11, 2025 · Jun 11, 2025
diff --git a/api-playground/customization/adding-sdk-examples.mdx b/api-playground/customization/adding-sdk-examples.mdx
@@ -1,6 +1,6 @@
 ---
 title: "Adding SDK examples"
 description: "Display language-specific code samples alongside your API endpoints to show developers how to use your SDKs"
 ---

 If your users interact with your API using an SDK rather than directly through a network request, you can use the `x-codeSamples` extension to add code samples to your OpenAPI document and display them in your OpenAPI pages.
@@ -25,7 +25,7 @@
 paths:
   /plants:
     get:
-      ...
+      # ...
       x-codeSamples:
         - lang: bash
           label: List all unwatered plants

diff --git a/api-playground/customization/complex-data-types.mdx b/api-playground/customization/complex-data-types.mdx
@@ -32,7 +32,7 @@
         users:
           type: array
           description: An array containing all users in the organization
-...
+# ...
 components:
   schemas:
     Org:
@@ -56,7 +56,7 @@

 ### Providing options with `oneOf` and `anyOf`

 When you use `oneOf` or `anyOf`, the options are displayed in a tabbed container. Specify a `title` field in each subschema to give your options names. For example, here's how you might display two different types of delivery addresses:

 ```yaml
 delivery_address:
@@ -67,14 +67,14 @@
         address_line_1:
           type: string
           description: The street address of the recipient
-        ...
+        # ...
     - title: POBox
       type: object
       properties:
         box_number:
           type: string
           description: The number of the PO Box
-        ...
+        # ...
 ```
 
 <ParamField body="delivery_address" type="object">

diff --git a/api-playground/customization/managing-page-visibility.mdx b/api-playground/customization/managing-page-visibility.mdx
@@ -5,7 +5,7 @@

 You can control which OpenAPI operations get published as documentation pages and their visibility in navigation. This is useful for internal-only endpoints, deprecated operations, beta features, or endpoints that should be accessible via direct URL but not discoverable through site navigation.

 If your pages are autogenerated from an OpenAPI document, you can manage page visibility with the `x-hidden` and `x-excluded` extensions.

 ## `x-hidden`

@@ -39,24 +39,24 @@
   "/plants": {
     "get": {
       "description": "Returns all plants from the store",
-      "parameters": { ... },
-      "responses": { ... }
+      "parameters": { /*...*/ },
+      "responses": { /*...*/ }
     }
   },
   "/hidden_plants": {
     "get": {
       "x-hidden": true,
       "description": "Returns all somewhat secret plants from the store",
-      "parameters": { ... },
-      "responses": { ... }
+      "parameters": { /*...*/ },
+      "responses": { /*...*/ }
     }
   },
   "/secret_plants": {
     "get": {
       "x-excluded": true,
       "description": "Returns all top secret plants from the store (do not publish this endpoint!)",
-      "parameters": { ... },
-      "responses": { ... }
+      "parameters": { /*...*/ },
+      "responses": { /*...*/ }
     }
   }
 },

diff --git a/api-playground/customization/multiple-responses.mdx b/api-playground/customization/multiple-responses.mdx
@@ -28,4 +28,4 @@ responses:
               countryCode: "GB"
               currencyCode: "GBP"
               taxRate: 0.20
-```
+```
diff --git a/api-playground/mdx/authentication.mdx b/api-playground/mdx/authentication.mdx
@@ -23,7 +23,7 @@
 }
 ```
 
-```md Page Metadata
+```mdx Page Metadata
 ---
 title: "Your page title"
 authMethod: "bearer"
@@ -46,7 +46,7 @@
 }
 ```
 
-```md Page Metadata
+```mdx Page Metadata
 ---
 title: "Your page title"
 authMethod: "basic"
@@ -70,7 +70,7 @@
 }
 ```
 
-```md Page Metadata
+```mdx Page Metadata
 ---
 title: "Your page title"
 authMethod: "key"
@@ -84,10 +84,10 @@
 The "none" authentication method is useful to disable authentication on a specific endpoint after setting a default in docs.json.
 
 <CodeGroup>
-```md Page Metadata
+```mdx Page Metadata
 ---
 title: "Your page title"
 authMethod: "none"
 ---
 ```
 </CodeGroup>
diff --git a/api-playground/mdx/configuration.mdx b/api-playground/mdx/configuration.mdx
@@ -40,7 +40,7 @@
 
     Each API endpoint page should have a corresponding `MDX` file. At the top of each file, define `title` and `api`:
 
-    ```md
+    ```mdx
     ---
     title: 'Create new user'
     api: 'POST https://api.mintlify.com/user'
@@ -61,11 +61,12 @@
 
     You can override the globally-defined display mode for the API playground per page by adding `playground` at the top of the `MDX` file:
 
-    ```md
+    ```mdx
     ---
     title: 'Create new user'
     api: 'POST https://api.mintlify.com/user'
     playground: 'none'
+    ---
     ```
 
   </Step>
@@ -95,7 +96,7 @@
 }
 ```
 
-```md Page Metadata
+```mdx Page Metadata
 ---
 title: "Your page title"
 authMethod: "bearer"
@@ -118,7 +119,7 @@
 }
 ```
 
-```md Page Metadata
+```mdx Page Metadata
 ---
 title: "Your page title"
 authMethod: "basic"
@@ -142,7 +143,7 @@
 }
 ```
 
-```md Page Metadata
+```mdx Page Metadata
 ---
 title: "Your page title"
 authMethod: "key"
@@ -156,10 +157,10 @@
 The `none` authentication method is useful to disable authentication on a specific endpoint after setting a default in docs.json.
 
 <CodeGroup>
-```md Page Metadata
+```mdx Page Metadata
 ---
 title: "Your page title"
 authMethod: "none"
 ---
 ```
 </CodeGroup>
diff --git a/api-playground/openapi-setup.mdx b/api-playground/openapi-setup.mdx
@@ -25,7 +25,7 @@

 ### Specifying the URL for your API

 To enable Mintlify features like the API playground, add a `servers` field to your OpenAPI document with your API's base URL.

 ```json
 {
@@ -162,7 +162,7 @@
 
 <CodeGroup>
 
-```md Example
+```mdx Example
 ---
 title: "Get users"
 description: "Returns all plants from the system that the user has access to"
@@ -172,7 +172,7 @@
 ---
 ```
 
-```md Format
+```mdx Format
 ---
 title: "title of the page"
 description: "description of the page"
@@ -192,10 +192,10 @@

 ### Autogenerate `MDX` files

 Use our Mintlify [scraper](https://www.npmjs.com/package/@mintlify/scraping) to autogenerate `MDX` pages for large OpenAPI documents.

 <Note>
  Your OpenAPI document must be valid or the files will not autogenerate.
 </Note>

 The scraper generates:
@@ -207,12 +207,12 @@
 <Steps>
  <Step title="Generate `MDX` files.">
    ```bash
    npx @mintlify/scraping@latest openapi-file <path-to-openapi-file>
    ```
  </Step>
  <Step title="Specify an output folder.">
    ```bash
    npx @mintlify/scraping@latest openapi-file <path-to-openapi-file> -o api-reference
    ```

    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.
@@ -225,14 +225,14 @@
 
 <CodeGroup>
 
-```md Example
+```mdx Example
 ---
 openapi-schema: OrderItem
 ---
 ```
 
 
-```md Format
+```mdx Format
 ---
 openapi-schema: "schema-key"
 ---

diff --git a/api-playground/overview.mdx b/api-playground/overview.mdx
@@ -25,7 +25,7 @@
     Make sure that your OpenAPI specification file is valid using the [Swagger Editor](https://editor.swagger.io/) or [Mint CLI](https://www.npmjs.com/package/mint).
     </Info>
 
-    ``` {2}
+    ```bash {2}
     /your-project
       |- docs.json
       |- openapi.json
@@ -73,10 +73,10 @@
 </ResponseField>

 <ResponseField name="examples" type="object">
    Configurations for the autogenerated API examples.
    <Expandable title="examples" defaultOpen="True">
    <ResponseField name="languages" type="array of string">
        Example languages for the autogenerated API snippets.

        Languages display in the order specified.
    </ResponseField>
@@ -90,7 +90,7 @@

 ```json
 {
 "api": {
   "playground": {
     "display": "interactive"
   },

diff --git a/api-playground/troubleshooting.mdx b/api-playground/troubleshooting.mdx
@@ -37,7 +37,7 @@ If your API pages aren't displaying correctly, check these common configuration
 
     Here's an example of how things might go wrong:
 
-    ```md get-user.mdx
+    ```mdx get-user.mdx
     ---
     openapi: "GET /users/{id}/"
     ---
@@ -56,7 +56,7 @@ If your API pages aren't displaying correctly, check these common configuration
     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
+    ```mdx api-reference/v1/users/get-user.mdx
     ---
     openapi: "v1 GET /users/{id}"
     ---
@@ -73,4 +73,4 @@ If your API pages aren't displaying correctly, check these common configuration
     likely require you to configure CORS on your server, as these requests will now come directly
     from your users' browsers.
   </Accordion>
-</AccordionGroup>
+</AccordionGroup>
diff --git a/authentication-personalization/overview.mdx b/authentication-personalization/overview.mdx
@@ -115,17 +115,17 @@
  fields. For example, `{user.org?.plan}`.
 </Note>

 ### API key prefilling

 Automatically populate API playground fields with user-specific values by returning matching field names in your user data. The field names in your user data must exactly match the names in the API playground for automatic prefilling to work.

 ### Page visibility

 Restrict which pages are visible to your users by adding `groups` fields to your pages' frontmatter. By default, every page is visible to every user.
 
 Users will only see pages for `groups` that they are in.
 
-```md
+```mdx
 ---
 title: "Managing your users"
 description: "Adding and removing users from your organization"

diff --git a/changelog.mdx b/changelog.mdx
@@ -83,7 +83,7 @@
  - Improved styling nits for dashboard border for mobile-tablet-desktop responsiveness
  - Show code examples even when in simple mode for API playground
  - Support "command \+ k" shortcut for search in web editor
  - Codeblocks within callouts expand to fill the width of the callout area
 </Update>

 <Update label="February 2025">
@@ -98,13 +98,13 @@
 
   1. Make sure your CLI is the latest version
 
-  ```
+  ```bash
   npm i mint@latest -g
   ```
 
   1. In your docs repository, run
 
-  ```
+  ```bash
   mint upgrade
   ```
 
@@ -114,9 +114,9 @@

  Automatically lint your docs to find broken links, discover spelling and grammar issues, or enforce writing styles with your own Vale config. Learn more in our [docs](settings/ci).

  ## .md support for LLMs

  All documentation pages are now automatically available as plain Markdown files—just append `.md` to the URL. This makes it easier for LLMs to ingest individual pages from your documentation.

  ## More Themes

@@ -198,7 +198,7 @@
  <Frame>
    ![llms.txt support](/images/changelog/llms.jpg)
  </Frame>
  All docs instances are now automatically hosted at /llms.txt and /llms-full.txt so that LLMs can easily ingest your documentation. For more information, read the [docs on the new llms.txt standard.](https://llmstxt.org)

  ## Localization

@@ -230,7 +230,7 @@
   sayHello();
   ```
 
-  ````md
+  ````mdx
   ```javascript Line Highlighting Example {1,3-5}
   const greeting = "Hello, World!";
   function sayHello() {
@@ -270,7 +270,7 @@
  ## Dashboard Improvements

  - Added ability to change custom domain to be /docs directly through dashboard settings.
  - Consolidated the login and signup pages to decrease friction and confusion.
  - Implemented the discovery login flow so that users that are members of multiple organizations can now switch between them.
  - Added login with Google OAuth
  - Added ability to add new deployment through dashboard settings.
@@ -284,7 +284,7 @@
  - Don't allow search engines to crawl user-auth protected pages.
  - Revalidate the cache when an org is deleted.
  - We now use the Scalar OpenAPI parser to parse OpenAPI definitions which improves the performance, fixes parsing issues, and surfaces better error messages.
  - Top-level descriptions are now supported in API reference pages autogenerated from OpenAPI definitions.
  - Add in-line-style support for icons
  - Fixed the pop-in of custom CSS in docs.
  - Properly show in-line code styling in conjunction with links.
@@ -317,7 +317,7 @@
  <Frame>
    ![SEO Improvements](/images/changelog/seo-improvements.jpeg)
  </Frame>
  We've fixed  both the mobile and desktop layout of our docs so that they are more SEO-friendly - including adding proper aria tags to navbar and toggle elements.

  ## Dashboard Improvements

@@ -351,7 +351,7 @@

  ## 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.

@@ -384,7 +384,7 @@
  </Frame>
  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)
@@ -419,7 +419,7 @@
 <Update label="May 2024">
  ## Okta SSO

  We now support sign-on via Okta SAML and OIDC.

  ## Mintlify REST API

@@ -442,7 +442,7 @@
 <Update label="March 2024">
  ## Mintlify MDX for VSCode

  Call snippets of our pre-built components and callouts without leaving VSCode. [Install the extension here](https://marketplace.visualstudio.com/items?itemName=mintlify.mintlify-snippets).
 </Update>

 <Update label="February 2024">
@@ -451,7 +451,7 @@
  - Dashboard upgrades: view update logs to see what's changed and status of an update, toggle between Mintlify projects to manage deployments
  - Versioning with tabs fully supported
  - Wildcard redirects now supported
  - CLI Error Detection: we now show the position of invalid frontmatter when there are parsing issues during local development
 </Update>

 <Update label="January 2024">
@@ -461,4 +461,4 @@
   - Snippets V2: We now support fully reusable components and variables for snippets.
   - Open-source MDX Engine: We've exposed two APIs—getCompiledMdx and MDXComponent—so you can access Mintlify markdown and code syntax highlighting. [Contributions to the project](https://github.com/mintlify/mdx) are welcome.
   - AI Chat Insights: Segment chat history by date and increase AI Chat quota from the dashboard, and see how often a specific query appears.
-</Update>
+</Update>
diff --git a/code.mdx b/code.mdx
@@ -10,7 +10,7 @@ icon: "code"
 
 To denote a `word` or `phrase` as code, enclose it in backticks (\`).
 
-```
+```mdx
 To denote a `word` or `phrase` as code, enclose it in backticks (`).
 ```
 
@@ -26,7 +26,7 @@ class HelloWorld {
 }
 ```
 
-````md
+````mdx
 ```java HelloWorld.java
 class HelloWorld {
     public static void main(String[] args) {
@@ -48,7 +48,7 @@ class HelloWorld {
 }
 ```
 
-````md
+````mdx
 ```java
 class HelloWorld {
     public static void main(String[] args) {
@@ -165,7 +165,7 @@ Add a title after the programming language to set the name of your code example.
 const hello = "world";
 ```
 
-````md Code Block Example
+````mdx Code Block Example
 ```javascript Code Block Example
 const hello = "world";
 ```
@@ -183,7 +183,7 @@ function sayHello() {
 sayHello();
 ```
 
-````md
+````mdx
 ```javascript Line Highlighting Example {1,3-5}
 const greeting = "Hello, World!";
 function sayHello() {
@@ -287,7 +287,7 @@ if __name__ == "__main__":
     main()
 ```
 
-````md
+````mdx
 ```javascript Expandable Example [expandable]
 const greeting = "Hello, World!";
 function sayHello() {

diff --git a/components/accordions.mdx b/components/accordions.mdx
@@ -17,7 +17,7 @@
 
 <RequestExample>
 
-````jsx Accordion Example
+````mdx Accordion Example
 <Accordion title="I am an Accordion.">
   You can put any content in here, including other components, like code:
 
@@ -31,7 +31,7 @@
 </Accordion>
 ````
 
-````jsx Accordion Group Example
+````mdx Accordion Group Example
 <AccordionGroup>
   <Accordion title="FAQ without Icon">
     You can put other components inside Accordions.
@@ -74,7 +74,7 @@
 </ResponseField>

 <ResponseField name="icon" type="string or svg">
  A [Font Awesome icon](https://fontawesome.com/icons), [Lucide
  icon](https://lucide.dev/icons), or SVG code
 </ResponseField>


diff --git a/components/callouts.mdx b/components/callouts.mdx
@@ -1,38 +1,38 @@
 ---
 title: 'Callouts'
 description: 'Use callouts to add eye-catching context to your content'
 icon: 'info'
 ---

 Callouts can be styled as a Note, Warning, Info, Tip, or Check:
 
 <Note>This adds a note in the content</Note>
 
-```jsx
+```mdx
 <Note>This adds a note in the content</Note>
 ```
 
 <Warning>This raises a warning to watch out for</Warning>
 
-```jsx
+```mdx
 <Warning>This raises a warning to watch out for</Warning>
 ```
 
 <Info>This draws attention to important information</Info>
 
-```jsx
+```mdx
 <Info>This draws attention to important information</Info>
 ```
 
 <Tip>This suggests a helpful tip</Tip>
 
-```jsx
+```mdx
 <Tip>This suggests a helpful tip</Tip>
 ```
 
 <Check>This brings us a checked status</Check>
 
-```jsx
+```mdx
 <Check>This brings us a checked status</Check>
 ```
 
@@ -44,8 +44,8 @@
 
 <RequestExample>
 
-```jsx Callout Example
+```mdx Callout Example
 <Note>This adds a note in the content</Note>
 ```
 
-</RequestExample>
+</RequestExample>