mintlify · ethanpalm · Nov 26, 2025 · Nov 26, 2025 · Nov 26, 2025 · Nov 26, 2025
diff --git a/api-playground/mdx-setup.mdx b/api-playground/mdx-setup.mdx
@@ -4,7 +4,7 @@
 keywords: ["API documentation", "endpoint documentation"]
 ---
 
-You can manually define API endpoints in individual pages. This approach is useful for small APIs or prototyping.
+You can manually define API endpoints in individual MDX pages. This approach is useful for small APIs or prototyping.
 
 ## Setup
 
@@ -38,7 +38,7 @@
   </Step>
 
   <Step title="Create your endpoint pages">
-    Create an `MDX` file for each endpoint. Define the `title` and `api` in the frontmatter:
+    Create an MDX file for each endpoint. Define the `title` and `api` in the frontmatter:
 
     ```mdx
     ---
@@ -175,7 +175,7 @@

 ### None

 To disable authentication on a specific page, set `authMethod` to `none`:

 ```mdx Page Metadata
 ---

diff --git a/api-playground/overview.mdx b/api-playground/overview.mdx
@@ -17,7 +17,7 @@

 The playground generates interactive pages for your endpoints based on your OpenAPI specification or AsyncAPI schema. If you modify your API, the playground automatically updates the relevant pages.

 We recommend generating your API playground from an OpenAPI specification. However, you can manually create API reference pages after defining a base URL and authentication method in your `docs.json`.

 ## Get started

@@ -83,7 +83,7 @@
    <Expandable title="playground" defaultOpen="True">
    <ResponseField name="display" type="&quot;interactive&quot; | &quot;simple&quot; | &quot;none&quot;">
        The display mode of the API playground.
        - `"interactive"`: Display the interactive playground.
        - `"simple"`: Display a copyable endpoint with no playground.
        - `"none"`: Display nothing.

@@ -114,7 +114,7 @@

 ### Example configuration

 This example configures the API playground to be interactive with example code snippets for cURL, Python, and JavaScript. Only required parameters are shown in the code snippets, and the playground prefills the request body with example values.

 ```json
 {
@@ -133,7 +133,7 @@
 
 ### Custom endpoint pages
 
-When you need more control over your API documentation, use the `x-mint` extension in your OpenAPI specification or create individual `MDX` pages for your endpoints.
+When you need more control over your API documentation, use the `x-mint` extension in your OpenAPI specification or create individual MDX pages for your endpoints.
 
 Both options allow you to:
 
@@ -143,7 +143,7 @@
 
 The `x-mint` extension is recommended so that all of your API documentation is automatically generated from your OpenAPI specification and maintained in one file.
 
-Individual `MDX` pages are recommended for small APIs or when you want to experiment with changes on a per-page basis.
+Individual MDX pages are recommended for small APIs or when you want to experiment with changes on a per-page basis.
 
 ## Further reading
 

diff --git a/customize/custom-scripts.mdx b/customize/custom-scripts.mdx
@@ -6,7 +6,7 @@

 Use CSS to style HTML elements or add custom CSS and JavaScript to fully customize the look and feel of your documentation.

 ## Styling with Tailwind CSS

 Use Tailwind CSS v3 to style HTML elements. You can control layout, spacing, colors, and other visual properties. Some common classes are:

@@ -16,15 +16,15 @@
 - `block`, `hidden` - Display control
 - `dark:hidden`, `dark:block` - Dark mode visibility

 Tailwind CSS arbitrary values are not supported. For custom values, use the `style` prop instead.

 ```html
 <img style={{ width: '350px', margin: '12px auto' }} src="/path/image.jpg" />
 ```
 
 ## Custom CSS
 
-Add CSS files to your repository and their defined class names will be applied and available in all of your `MDX` files.
+Add CSS files to your repository and their defined class names will be applied and available in all of your MDX files.
 
 ### Adding `style.css`
 
@@ -160,11 +160,11 @@

 ## Custom JavaScript

 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 custom JavaScript

 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 || [];

diff --git a/customize/react-components.mdx b/customize/react-components.mdx
@@ -10,7 +10,7 @@
 
 ## Using React components
 
-You can build React components directly in your `MDX` files using [React hooks](https://react.dev/reference/react/hooks).
+You can build React components directly in your MDX files using [React hooks](https://react.dev/reference/react/hooks).
 
 ### Example
 
@@ -92,11 +92,11 @@
 
 ## Importing components
 
-To import React components in your `MDX` files, the component files must be located in the `snippets` folder. You can then import them into any `MDX` page in your documentation. Learn more about [reusable snippets](/create/reusable-snippets).
+To import React components in your MDX files, the component files must be located in the `snippets` folder. You can then import them into any MDX page in your documentation. Learn more about [reusable snippets](/create/reusable-snippets).
 
 ### Example
 
-This example declares a `ColorGenerator` component that uses multiple React hooks and then uses it in an `MDX` file.
+This example declares a `ColorGenerator` component that uses multiple React hooks and then uses it in an MDX file.
 
 Create `color-generator.jsx` file in the `snippets` folder:
 
@@ -213,7 +213,7 @@
 }
 ```
 
-Import the `ColorGenerator` component and use it in an `MDX` file:
+Import the `ColorGenerator` component and use it in an MDX file:
 
 ```mdx
 import { ColorGenerator } from "/snippets/color-generator.jsx"
@@ -236,9 +236,9 @@
    - **Accessibility**: Ensure dynamic content changes are announced to screen readers.
  </Accordion>
  <Accordion title="Performance best practices">
    - **Optimize dependency arrays**: Include only necessary dependencies in your `useEffect` dependency arrays.
    - **Memoize complex calculations**: Use `useMemo` or `useCallback` for expensive operations.
    - **Reduce re-renders**: Break large components into smaller ones to prevent cascading re-renders.
    - **Lazy loading**: Consider lazy loading complex components to improve initial page load time.
  </Accordion>
 </AccordionGroup>
diff --git a/deploy/personalization-setup.mdx b/deploy/personalization-setup.mdx
@@ -4,7 +4,7 @@
 keywords: ["content personalization", "user data", "prefilling", "dynamic"]
 ---

 Personalization customizes your documentation for each user when they are logged in. For example, you can prefill their API keys, show content specific to their plan or role, or hide sections they don't need access to.

 ## Personalization features

@@ -28,7 +28,7 @@

 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.

 ```mdx
 ---
@@ -40,7 +40,7 @@

 ## User data format

 When implementing personalization, your system returns user data in a specific format that enables content customization. This data can be sent as either a raw JSON object or within a signed JWT, depending on your handshake method. The shape of the data is the same for both.

 ```tsx
 type User = {
@@ -61,7 +61,7 @@
  type="number"
 >
  Session expiration time in **seconds since epoch**. If the user loads a page after this time, their stored data is automatically deleted and they must reauthenticate.
  <Warning><b>For JWT handshakes:</b> This differs from the JWT's `exp` claim, which determines when a JWT is considered invalid. Set the JWT `exp` claim to a short duration (10 seconds or less) for security. Use `expiresAt` for the actual session length (hours to weeks).</Warning>
 </ParamField>
 <ParamField
  path="groups"
@@ -69,24 +69,24 @@
 >
  List of groups the user belongs to. Pages with matching `groups` in their frontmatter are visible to this user.

  **Example**: User with `groups: ["admin", "engineering"]` can access pages tagged with either the `admin` or `engineering` groups.
 </ParamField>
 <ParamField
   path="content"
   type="object"
 >
-  Custom data accessible in your `MDX` content via the `user` variable. Use this for dynamic personalization throughout your documentation.
+  Custom data accessible in your MDX content via the `user` variable. Use this for dynamic personalization throughout your documentation.
 
   **Basic example**:
   ```json
   { "firstName": "Ronan", "company": "Acme Corp", "plan": "Enterprise" }
   ```
 
-  **Usage in `MDX`**:
+  **Usage in MDX**:
   ```mdx
   Welcome back, {user.firstName}! Your {user.plan} plan includes...
   ```
  With the example `user` data, this would render as: Welcome back, Ronan! Your Enterprise plan includes...

  **Advanced conditional rendering**:
  ```jsx
@@ -117,7 +117,7 @@
    "query": { "org_id": "12345" }
  }
  ```
  If a user makes requests at a specific subdomain, you can send `{ server: { subdomain: 'foo' } }` as an `apiPlaygroundInputs` field. This value will be prefilled on any API page with the `subdomain` value.

  <Note>The `header`, `query`, and `cookie` fields will only prefill if they are part of your [OpenAPI security scheme](https://swagger.io/docs/specification/authentication/). If a field is in either the `Authorization` or `Server` sections, it will prefill. Creating a standard header parameter named `Authorization` will not enable this feature.</Note>
 </ParamField>
@@ -173,7 +173,7 @@
  <Step title="Integrate Mintlify personalization into your login flow.">
    Modify your existing login flow to include these steps after user login:

    * Create a JWT containing the logged-in user's info in the `User` format. See the [User data format](#user-data-format) section above for more information.
    * Sign the JWT with the secret key, using the ES256 algorithm.
    * Create a redirect URL back to your docs, including the JWT as the hash.
  </Step>
@@ -181,7 +181,7 @@

 ### Example

 Your documentation is hosted at `docs.foo.com`. You want your docs to be separate from your dashboard (or you don't have a dashboard) and enable personalization.

 Generate a JWT secret. Then create a login endpoint at `https://foo.com/docs-login` that initiates a login flow to your documentation.

@@ -227,7 +227,7 @@
 </Tab>
 <Tab title="OAuth 2.0">
 ### Prerequisites
 * An OAuth server that supports the Auth Code with PKCE Flow
 * Ability to create an API endpoint accessible by OAuth access tokens

 ### Implementation
@@ -242,11 +242,11 @@
    1. In your dashboard, go to [Authentication](https://dashboard.mintlify.com/settings/deployment/authentication).
    2. Select **Personalization**.
    3. Select **OAuth** and configure these fields:
      * **Authorization URL**: Your OAuth authorization endpoint.
      * **Client ID**: Your OAuth 2.0 client identifier.
      * **Scopes**: Permissions to request. Copy the **entire** scope string (for example, for a scope like `provider.users.docs`, copy the complete `provider.users.docs`). Must match the scopes of the endpoint that you configured in the first step.
      * **Token URL**: Your OAuth token exchange endpoint.
      * **Info API URL**: Endpoint to retrieve user data for personalization. Created in the first step.
    4. Select **Save changes**
  </Step>
  <Step title="Configure your OAuth server.">
@@ -257,7 +257,7 @@

 ### Example

 Your documentation is hosted at `foo.com/docs` and you have an existing OAuth server that supports the PKCE flow. You want to personalize your docs based on user data.

 **Create a user info endpoint** at `api.foo.com/docs/user-info`, which requires an OAuth access token with the `provider.users.docs` scope and responds with the user's custom data:


diff --git a/editor.mdx b/editor.mdx
@@ -88,7 +88,7 @@
 
 ### Markdown mode
 
-Markdown mode provides direct access to the underlying `MDX` code of your documentation. This mode is ideal for when you need precise control over component properties or when you prefer to write in Markdown syntax.
+Markdown mode provides direct access to the files that make up your documentation. This mode is ideal for when you need precise control over component properties or when you prefer to write in MDX syntax.
 
 <Frame>
   <img
@@ -224,9 +224,7 @@
 
 Make changes to your pages using visual mode or Markdown mode in the editor.
 
-In visual mode, press <kbd>/</kbd>
-
- to open the component menu. Add content blocks, callouts, code blocks, and other components to customize your documentation.
+In visual mode, press <kbd>/</kbd> to open the component menu. Add content blocks, callouts, code blocks, and other components to customize your documentation.
 
 <Frame>
   <img
@@ -242,13 +240,13 @@
   />
 </Frame>
 
-In Markdown mode, you directly edit the `MDX` of your pages. This can be helpful when you need to:
+In Markdown mode, you can directly edit the MDX of your pages. This can be helpful when you need to:
 
 - Set specific component properties
 - Work with complex nested components
-- Copy and paste `MDX` content from other sources
+- Copy and paste MDX content from other sources
 
-See [Format text](/create/text) and [Format code](/create/code) for more information on how to write using Markdown syntax.
+See [Format text](/create/text) and [Format code](/create/code) for more information on how to write using MDX syntax.
 
 ## Publish your changes
 
@@ -271,7 +269,7 @@
  />
 </Frame>

 If you authorize Mintlify to your GitHub user, your commits will be signed as if you had made them yourself. If not, they will be signed by the Mintlify GitHub app.

 ### Pull requests and reviewing changes

@@ -298,7 +296,7 @@
    - Any specific areas that need review
  </Step>
  <Step title="Create and share">
    Select **Publish Pull Request**. The editor will provide a link to view your pull request.

    <Frame>
      <img

diff --git a/guides/migrating-from-mdx.mdx b/guides/migrating-from-mdx.mdx
@@ -1,15 +1,15 @@
 ---
 title: "Migrating MDX API pages to OpenAPI navigation"
 sidebarTitle: "Migrate from MDX to OAS"
 description: "Migrate to automated OpenAPI generation with flexible navigation."
 keywords: ["API migration", "mint migrate-mdx", "OpenAPI migration", "x-mint extension"]
 ---
 
-If you are currently using individual `MDX` pages for your API endpoints, you can migrate to autogenerating pages from your OpenAPI specification while retaining the customizability of individual pages. This can help you reduce the number of files you need to maintain and improve the consistency of your API documentation.
+If you are currently using individual MDX pages for your API endpoints, you can migrate to autogenerating pages from your OpenAPI specification while retaining the customizability of individual pages. This can help you reduce the number of files you need to maintain and improve the consistency of your API documentation.
 
 You can define metadata and content for each endpoint in your OpenAPI specification and organize endpoints where you want them in your navigation.
 
 ## CLI migration

 The `mint migrate-mdx` command is the recommended way to migrate from MDX endpoint pages to autogenerated pages.

@@ -21,11 +21,11 @@
 - Deletes the original MDX endpoint files.

 <Info>
 If you already have `x-mint` defined for an endpoint and also have an MDX page with content for that endpoint, the MDX content will overwrite existing `x-mint` settings.

 If you have multiple MDX pages for the same endpoint with different content, the script will use the content from the page that appears last in your `docs.json`.

 The migration tool does not support previewing changes before applying them.
 </Info>

 <Steps>
@@ -39,7 +39,7 @@
    </Tip>
  </Step>
  <Step title="Install the Mint CLI">
    If needed, install or update the [Mint CLI](/installation).
  </Step>
  <Step title="Run the migration command.">
    ```bash
@@ -64,7 +64,7 @@
   </Step>
 
   <Step title="Update your navigation structure.">
-    Replace `MDX` page references with OpenAPI endpoints in your `docs.json`.
+    Replace MDX page references with OpenAPI endpoints in your `docs.json`.
 
     ```json
     "navigation": {
@@ -90,7 +90,7 @@
   </Step>
 
   <Step title="Remove old MDX files.">
-    After verifying your new navigation works correctly, remove the `MDX` endpoint files that you no longer need.
+    After verifying your new navigation works correctly, remove the MDX endpoint files that you no longer need.
   </Step>
 </Steps>
 
@@ -138,9 +138,9 @@
 }
 ```
 
-## When to use individual `MDX` pages
+## When to use individual MDX pages
 
-Consider keeping individual `MDX` pages when you need:
+Consider keeping individual MDX pages when you need:
 
 - Extensive custom content per endpoint like React components or lengthy examples.
 - Unique page layouts.

diff --git a/installation.mdx b/installation.mdx
@@ -1,7 +1,7 @@
 ---
 title: "CLI installation"
 description: "Use the CLI to preview docs locally, test changes in real-time, and catch issues before deploying your documentation site."
 keywords: ["CLI", "npm", "local development", "Node.js"]
 ---

 <img
@@ -15,14 +15,14 @@
  alt="Decorative graphic representing the CLI."
 />

 Use the CLI to preview your documentation locally as you write and edit. View changes in real-time before deploying, test your documentation site's appearance and functionality, and catch issues like broken links or accessibility problems.

 The CLI also has utilities for maintaining your documentation, including commands to rename files, validate OpenAPI specifications, and migrate content between formats.

 ## Install the CLI

 <Info>
  **Prerequisite**: The CLI requires [Node.js](https://nodejs.org/en) v20.17.0 or higher through v24. LTS versions are preferred.
 </Info>

 Run the following command to install the [CLI](https://www.npmjs.com/package/mint):
@@ -39,7 +39,7 @@

 ## Preview locally

 To generate a local preview, navigate to your documentation directory (where your `docs.json` file is located) and run the following command:

 ```bash
 mint dev
@@ -47,7 +47,7 @@

 A local preview of your documentation is available at `http://localhost:3000`.

 Alternatively, if you do not want to install the CLI globally, you can run a one-time script:

 ```bash
 npx mint dev
@@ -55,13 +55,13 @@

 ### Custom ports

 By default, the CLI uses port 3000. You can customize the port using the `--port` flag. To run the CLI on port 3333, for instance, use this command:

 ```bash
 mint dev --port 3333
 ```

 If you attempt to run on a port that is already in use, it will use the next available port:

 ```mdx
 Port 3000 is already in use. Trying 3001 instead.
@@ -85,13 +85,13 @@
 mint new [directory]
 ```

 This command clones the [starter kit](https://github.com/mintlify/starter) into a specified directory. If no directory is specified, the CLI tool prompts you to create a new subdirectory or overwrite the current directory.

 <Warning>
  If you overwrite the current directory, any existing files in the directory will be deleted.
 </Warning>

 The CLI tool prompts you for a project name and [theme](/customize/themes) to finish setting up your project.

 You can run `mint new` with the following flags:

@@ -104,15 +104,15 @@
 ```bash
 mint new docs --name my-project --theme linden
 ```
 ## Update the CLI

 If your local preview is out of sync with what you see on the web in the production version, update your local CLI:

 ```bash
 mint update
 ```

 If this `mint update` command is not available on your local version, re-install the CLI with the latest version:

 <CodeGroup>
    ```bash npm
@@ -150,7 +150,7 @@
 mint openapi-check <OpenAPI filename or URL>
 ```

 Pass a filename (for example, `./openapi.yaml`) or a URL (for example, `https://petstore3.swagger.io/api/v3/openapi.json`).

 ### Rename files

@@ -172,11 +172,11 @@
 
 ## Formatting
 
-While developing locally, we recommend using extensions in your IDE to recognize and format `MDX` files.
+While developing locally, we recommend using extensions in your IDE to recognize and format MDX files.
 
 If you use Cursor, Windsurf, or VS Code, we recommend the [MDX VS Code extension](https://marketplace.visualstudio.com/items?itemName=unifiedjs.vscode-mdx) for syntax highlighting, and [Prettier](https://marketplace.visualstudio.com/items?itemName=esbenp.prettier-vscode) for code formatting.
 
 If you use JetBrains, we recommend the [MDX IntelliJ IDEA plugin](https://plugins.jetbrains.com/plugin/14944-mdx) for syntax highlighting, and setting up [Prettier](https://prettier.io/docs/webstorm) for code formatting.

 ## Troubleshooting

@@ -189,7 +189,7 @@
    3. Reinstall the mint CLI: `npm install -g mint`
  </Accordion>
  <Accordion title="Issue: Encountering an unknown error">
    **Solution**: Go to the root of your device and delete the `~/.mintlify` folder. Afterwards, run `mint dev` again.
  </Accordion>
  <Accordion title="Error: permission denied">
    This is due to not having the required permissions to globally install node packages.
@@ -197,12 +197,12 @@
    **Solution**: Try running `sudo npm i -g mint`. You will be prompted for your password, which is the one you use to unlock your computer.
  </Accordion>
  <Accordion title="The local preview doesn't look the same as my docs do on the web">
    This is likely due to an outdated version of the CLI.

   **Solution:** Run `mint update` to get the latest changes.
  </Accordion>
  <Accordion title="mintlify vs. mint package">
    If you have any problems with the CLI package, you should first run `npm ls -g`. This command shows what packages are globally installed on your machine.

    If you don't use npm or don't see it in the -g list, try `which mint` to locate the installation.


diff --git a/migration.mdx b/migration.mdx
@@ -10,11 +10,11 @@

 <CardGroup cols="2">
  <Card title="Automated migration" icon="wand-sparkles">
    If you are migrating from Docusaurus or ReadMe, use our tools to automate your migration.
  </Card>

  <Card title="Manual migration" icon="pencil-ruler">
    If you are migrating from any other platform, follow our guide to migrate your content.
  </Card>
 </CardGroup>

@@ -101,7 +101,7 @@
 </svg>} horizontal />
 </Columns>

 If your documentation is hosted on another platform, see the manual migration steps.

 ### Installing the scraper

@@ -113,7 +113,7 @@

 ### Scraping pages and sections

 The migration tool automatically detects your documentation platform and converts your content. Prepared files are stored locally in `./docs` by default.

 For large documentation sites, migrate smaller sections at a time rather than the entire site at once.

@@ -136,7 +136,7 @@

 After scraping your existing documentation platform, you are ready to build your docs on Mintlify.

 Confirm that all of your pages have been migrated then add these files to the documentation repository that you created during the onboarding process. This is usually a GitHub repository.
 </Tab>
 <Tab title="Manual migration">

@@ -144,20 +144,24 @@

 ### Content migration

 To migrate your content to Mintlify, you will need:
 
 - A valid `docs.json` for your site settings and navigation. See [Global settings](/organize/settings) and [Navigation](/organize/navigation) for more information.
-- An `MDX` file for each page of your documentation. See [Pages](/organize/pages) for more information.
+- A Markdown file (`.md` or `.mdx`) for each page of your documentation. MDX is the recommended format. See [Pages](/organize/pages) for more information.
 - (Optional) An OpenAPI specification for your API endpoint pages. See [OpenAPI setup](/api-playground/openapi-setup) for more information.
 
-1. If your content is already in `MDX` format, copy the pages to your Mintlify project. Otherwise, convert your content to `MDX` format.
-2. Create your `docs.json` referencing the paths to your `MDX` pages.
+1. If your content is already in Markdown format, copy the content to your Mintlify project. Otherwise, convert your content to MDX format.
+2. Create your `docs.json` referencing the paths to your Markdown pages.
 3. If you have OpenAPI specifications, add them to your `docs.json` and configure the API playground.
 
+<Tip>
+  If you migrate your content as `.md` files, convert them to `.mdx` to support interactive features like React components.
+</Tip>
+
 ### Asset migration
 
 1. Copy assets to your repository's `images/` directory.
-2. Update references in your `MDX` files:
+2. Update references in your Markdown files:
    ```mdx
    ![Alt text](/images/screenshot.png)
    ```
@@ -167,13 +171,13 @@

 ## Post-migration checklist

 After completing your migration (automated or manual), we recommend checking:

 - All pages render
 - Navigation works as intended
 - Internal links resolve properly
 - Images and assets load correctly
 - Code blocks display with proper syntax highlighting
 - Search functionality works
 - Deployment is configured
 - Custom domain is set up
diff --git a/organize/navigation.mdx b/organize/navigation.mdx
@@ -10,7 +10,7 @@
 
 ## Pages
 
-Pages are the most fundamental navigation component. Pages map to the MDX files that make up your documentation.
+Pages are the most fundamental navigation component. Each page is an MDX file in your documentation repository.
 
 <img
   className="block dark:hidden pointer-events-none"
@@ -96,8 +96,8 @@

 Use the `expanded` property to control the default state of a group in the navigation sidebar.

 - `expanded: true`: Group is expanded by default.
 - `expanded: false` or omitted: Group is collapsed by default.

 This is useful for highlighting important sections or improving discoverability of key content.

@@ -254,9 +254,9 @@
 }
 ```

 For anchors that direct to external links only, use the `global` keyword. Anchors in a `global` object must have an `href` field and cannot point to a relative path. 

 Global anchors are particularly useful for linking to resources that are not part of your documentation, but should be readily accessible to your users like a blog or support portal.

 ```json
 {
@@ -282,7 +282,7 @@

 ## Dropdowns

 Dropdowns are contained in an expandable menu at the top of your sidebar navigation. Each item in a dropdown directs to a section of your documentation.

 <img
  className="block dark:hidden pointer-events-none"
@@ -397,7 +397,7 @@

 Integrate OpenAPI specifications directly into your navigation structure to automatically generate API documentation. Create dedicated API sections or place endpoint pages within other navigation components.

 Set a default OpenAPI specification at any level of your navigation hierarchy. Child elements will inherit this specification unless they define their own specification.

 ```json
 {
@@ -491,7 +491,7 @@

 In the `navigation` object, `languages` is an array where each entry is an object that requires a `language` field and can contain any other navigation fields.

 We currently support the following languages for localization:

 <CardGroup cols={2}>
  <Card title="Arabic (ar)" icon="/images/navigation/languages/ar.png" horizontal />
@@ -545,7 +545,7 @@

 ## Nesting

 You can use any combination of anchors, tabs, dropdowns, and products. The components can be nested within each other interchangeably to create your desired navigation structure.

 <CodeGroup>

@@ -667,7 +667,7 @@

 ## Breadcrumbs

 Breadcrumbs display the full navigation path at the top of pages. Some themes have breadcrumbs enabled by default and others do not. You can control whether breadcrumbs are enabled for your site using the `styling` property in your `docs.json`.

 <CodeGroup>

@@ -691,10 +691,10 @@

 ### Enable auto-navigation for groups

 When a user expands a navigation group, some themes will automatically navigate to the first page in the group. You can override a theme's default behavior using the `drilldown` option.

 - Set to `true` to force automatic navigation to the first page when a navigation group is selected.
 - Set to `false` to prevent navigation and only expand or collapse the group when it is selected.
 - Leave unset to use the theme's default behavior.

 <CodeGroup>

diff --git a/organize/pages.mdx b/organize/pages.mdx
@@ -4,7 +4,7 @@
 keywords: ["tags", "tag", "frontmatter", "metadata", "layout"]
 ---
 
-Each page is an MDX file, which combines Markdown content with React components to let you create rich, interactive documentation.
+Each page is a Markdown file. Both `.mdx` and `.md` file types are supported. We recommend using MDX, which combines Markdown with React components to create rich, interactive documentation. Plain Markdown (`.md`) is supported for easier migration from other platforms, but should be updated to MDX for full functionality.
 
 ## Page metadata
 
@@ -15,7 +15,7 @@
 - Page titles and descriptions
 - Sidebar titles, icons, and tags
 - Page layouts
 - SEO meta tags
 - Custom metadata

 <ResponseField name="title" type="string" required>
@@ -23,7 +23,7 @@
 </ResponseField>

 <ResponseField name="description" type="string">
  A brief description of what this page covers. Appears under the title and improves SEO.
 </ResponseField>

 <ResponseField name="sidebarTitle" type="string">
@@ -70,7 +70,7 @@

 ### Default

 If no mode is defined, defaults to a standard layout with a sidebar navigation and table of contents.

 ```yaml
 ---
@@ -80,7 +80,7 @@

 ### Wide

 Wide mode hides the table of contents. This is useful for pages that do not have any headings or if you prefer to use the extra horizontal space. Wide mode is available for all themes.

 ```yaml
 ---
@@ -147,10 +147,10 @@

 ## Search engine optimization

 Most SEO meta tags are automatically generated. You can set SEO meta tags manually to improve your site's SEO, social sharing, and browser compatibility.

 <Note>
  Meta tags with colons must be wrapped in quotes.
 </Note>

 ```yaml
@@ -159,11 +159,11 @@
 ---
 ```

 See [SEO](/optimize/seo) for complete SEO metadata options.

 ## Internal search keywords

 Enhance a specific page's discoverability in the built-in search by providing `keywords` in your metadata. These keywords won't appear as part of the page content or in search results, but users that search for them will be shown the page as a result.

 ```yaml
 ---

diff --git a/organize/settings.mdx b/organize/settings.mdx
@@ -50,7 +50,7 @@
 </ResponseField>

 <ResponseField name="colors" type="object" required>
  The colors used in your documentation. Colors are applied differently across themes. If you only provide a primary color, it will be used for all color elements.

  <Expandable title="Colors">
    <ResponseField name="primary" type="string matching ^#([a-fA-F0-9]{6}|[a-fA-F0-9]{3})$" required>
@@ -115,7 +115,7 @@
      Background image for your thumbnails. Can be a relative path or absolute URL.
    </ResponseField>
    <ResponseField name="fonts" type="object">
      Font configuration for thumbnails. Only Google Fonts family names are supported.

      <Expandable title="Fonts">
        <ResponseField name="family" type="string" required>
@@ -524,7 +524,7 @@

  <Expandable title="Interaction">
    <ResponseField name="drilldown" type="boolean">
      Control automatic navigation behavior when selecting navigation groups. Set to `true` to force navigation to the first page when a navigation group is expanded. Set to `false` to prevent navigation and only expand or collapse the group. Leave unset to use the theme's default behavior.
    </ResponseField>
  </Expandable>
 </ResponseField>
@@ -534,7 +534,7 @@

  <Expandable title="Metadata">
    <ResponseField name="timestamp" type="boolean">
      When enabled, all pages will display the date the content was last modified. Defaults to `false`.
    </ResponseField>
  </Expandable>
 </ResponseField>
@@ -612,7 +612,7 @@
      Destination path to redirect to. Example: `/new-page`
    </ResponseField>
    <ResponseField name="permanent" type="boolean">
      Whether to use a permanent redirect (301). Defaults to `true`.
    </ResponseField>
  </Expandable>
 </ResponseField>
@@ -646,7 +646,7 @@
  </Expandable>
 </ResponseField>

 ### API Configurations

 <ResponseField name="api" type="object">
  API documentation and interactive playground settings.
@@ -721,7 +721,7 @@
       </Expandable>
     </ResponseField>
     <ResponseField name="mdx" type="object">
-      Configurations for API pages generated from `MDX` files.
+      Configurations for API pages generated from MDX files.
 
       <Expandable title="Mdx">
         <ResponseField name="auth" type="object">
@@ -744,10 +744,10 @@
  </Expandable>
 </ResponseField>

 ### SEO and search

 <ResponseField name="seo" type="object">
  SEO indexing configurations.

  <Expandable title="Seo">
    <ResponseField name="metatags" type="object">