Document support for .md (#1900)

* replace `MDX` with `Markdown` where appropriate

* favor MDX

* Emphasize .md is for migration, .mdx is recommended

* favor MDX

* missing words

Author: ethanpalm

api-playground/mdx-setup.mdx

@@ -4,7 +4,7 @@ description: "Document API endpoints manually with MDX files."
 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 @@ You can manually define API endpoints in individual pages. This approach is usef
   </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
     ---

api-playground/overview.mdx

@@ -133,7 +133,7 @@ This example configures the API playground to be interactive with example code s
 
 ### 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 @@ Both options allow you to:
 
 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
 

customize/custom-scripts.mdx

@@ -24,7 +24,7 @@ Tailwind CSS arbitrary values are not supported. For custom values, use the `sty
 
 ## 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`
 

customize/react-components.mdx

@@ -10,7 +10,7 @@ import { ColorGenerator } from "/snippets/color-generator.jsx";
 
 ## 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 @@ The counter renders as an interactive React component.
 
 ## 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 @@ export const ColorGenerator = () => {
 }
 ```
 
-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"

deploy/personalization-setup.mdx

@@ -75,14 +75,14 @@ type User = {
   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...
   ```

editor.mdx

@@ -88,7 +88,7 @@ Visual mode provides a WYSIWYG experience where changes that you make in the edi
 
 ### 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 @@ In this example, you created a new page titled Themes and you want to add it to
 
 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 @@ In visual mode, press <kbd>/</kbd>
   />
 </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
 

guides/migrating-from-mdx.mdx

@@ -5,7 +5,7 @@ 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.
 
@@ -64,7 +64,7 @@ The migration tool does not support previewing changes before applying them.
   </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 @@ The migration tool does not support previewing changes before applying them.
   </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 @@ Organize different API versions using tabs or groups:
 }
 ```
 
-## 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.

installation.mdx

@@ -172,7 +172,7 @@ This command converts individual MDX endpoint pages to autogenerated pages defin
 
 ## 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.
 

migration.mdx

@@ -147,17 +147,21 @@ Migrate your documentation from any platform with full control over the process.
 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)
    ```

organize/navigation.mdx

@@ -10,7 +10,7 @@ With proper navigation configuration, you can organize your content so that user
 
 ## 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"