From 2717c0a2c0138559f9f62f62b655bdf2e176bac7 Mon Sep 17 00:00:00 2001 From: Ethan Palm <56270045+ethanpalm@users.noreply.github.com> Date: Tue, 25 Nov 2025 16:40:58 -0800 Subject: [PATCH 1/5] replace `MDX` with `Markdown` where appropriate --- api-playground/mdx-setup.mdx | 2 +- api-playground/overview.mdx | 4 ++-- customize/custom-scripts.mdx | 2 +- customize/react-components.mdx | 8 ++++---- deploy/personalization-setup.mdx | 6 +++--- editor.mdx | 14 ++++++-------- guides/migrating-from-mdx.mdx | 10 +++++----- installation.mdx | 2 +- migration.mdx | 8 ++++---- organize/navigation.mdx | 2 +- organize/pages.mdx | 2 +- organize/settings.mdx | 2 +- 12 files changed, 30 insertions(+), 32 deletions(-) diff --git a/api-playground/mdx-setup.mdx b/api-playground/mdx-setup.mdx index 74e363191..aaa2352e5 100644 --- a/api-playground/mdx-setup.mdx +++ b/api-playground/mdx-setup.mdx @@ -38,7 +38,7 @@ You can manually define API endpoints in individual pages. This approach is usef - 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 --- diff --git a/api-playground/overview.mdx b/api-playground/overview.mdx index f1dda5e7b..7281edaa4 100644 --- a/api-playground/overview.mdx +++ b/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 diff --git a/customize/custom-scripts.mdx b/customize/custom-scripts.mdx index eae520332..95de27734 100644 --- a/customize/custom-scripts.mdx +++ b/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 Markdown files. ### Adding `style.css` diff --git a/customize/react-components.mdx b/customize/react-components.mdx index 5e3c70c69..318e9a49a 100644 --- a/customize/react-components.mdx +++ b/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" diff --git a/deploy/personalization-setup.mdx b/deploy/personalization-setup.mdx index 4288e1009..6a2405964 100644 --- a/deploy/personalization-setup.mdx +++ b/deploy/personalization-setup.mdx @@ -14,7 +14,7 @@ Customize content with these personalization capabilities. 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. -### Dynamic MDX content +### Dynamic Markdown content Display dynamic content based on user information like name, plan, or organization using the `user` variable. @@ -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 Markdown 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 Markdown**: ```mdx Welcome back, {user.firstName}! Your {user.plan} plan includes... ``` diff --git a/editor.mdx b/editor.mdx index b049acaa1..0e614ad68 100644 --- a/editor.mdx +++ b/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 Markdown 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 Markdown syntax. / - - to open the component menu. Add content blocks, callouts, code blocks, and other components to customize your documentation. +In visual mode, press / to open the component menu. Add content blocks, callouts, code blocks, and other components to customize your documentation. / /> -In Markdown mode, you directly edit the `MDX` of your pages. This can be helpful when you need to: +In Markdown mode, directly edit the Markdown 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 Markdown content from other sources See [Format text](/create/text) and [Format code](/create/code) for more information on how to write using Markdown syntax. @@ -406,13 +404,13 @@ Find solutions to common issues you might encounter while using the visual edito **Possible causes:** - - Invalid MDX syntax in files + - Invalid Markdown syntax in files - Missing or corrupted files - Large file sizes causing timeouts **Solutions:** - 1. Check the file syntax for MDX formatting errors + 1. Check the file syntax for Markdown formatting errors 2. Verify the file exists in your repository. diff --git a/guides/migrating-from-mdx.mdx b/guides/migrating-from-mdx.mdx index beb02f4b9..3cac09c21 100644 --- a/guides/migrating-from-mdx.mdx +++ b/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. - 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. - 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. @@ -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. diff --git a/installation.mdx b/installation.mdx index e17fb6a11..4af6cdccd 100644 --- a/installation.mdx +++ b/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 Markdown 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. diff --git a/migration.mdx b/migration.mdx index 6086742b8..28415c713 100644 --- a/migration.mdx +++ b/migration.mdx @@ -147,17 +147,17 @@ 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. 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 Markdown 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. ### 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) ``` diff --git a/organize/navigation.mdx b/organize/navigation.mdx index c03ec0176..31ddf4eb8 100644 --- a/organize/navigation.mdx +++ b/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 a Markdown file in your documentation repository. - Configurations for API pages generated from `MDX` files. + Configurations for API pages generated from MDX files. From 6189a0c5f033953cbf39d9895b9b0b58a4c34e92 Mon Sep 17 00:00:00 2001 From: Ethan Palm <56270045+ethanpalm@users.noreply.github.com> Date: Tue, 25 Nov 2025 17:15:54 -0800 Subject: [PATCH 2/5] favor MDX --- api-playground/mdx-setup.mdx | 2 +- customize/custom-scripts.mdx | 2 +- deploy/personalization-setup.mdx | 4 ++-- editor.mdx | 2 +- installation.mdx | 2 +- 5 files changed, 6 insertions(+), 6 deletions(-) diff --git a/api-playground/mdx-setup.mdx b/api-playground/mdx-setup.mdx index aaa2352e5..f41a651ae 100644 --- a/api-playground/mdx-setup.mdx +++ b/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 diff --git a/customize/custom-scripts.mdx b/customize/custom-scripts.mdx index 95de27734..c0c10e790 100644 --- a/customize/custom-scripts.mdx +++ b/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 Markdown 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` diff --git a/deploy/personalization-setup.mdx b/deploy/personalization-setup.mdx index 6a2405964..db3427729 100644 --- a/deploy/personalization-setup.mdx +++ b/deploy/personalization-setup.mdx @@ -14,7 +14,7 @@ Customize content with these personalization capabilities. 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. -### Dynamic Markdown content +### Dynamic MDX content Display dynamic content based on user information like name, plan, or organization using the `user` variable. @@ -75,7 +75,7 @@ type User = { path="content" type="object" > - Custom data accessible in your Markdown 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 diff --git a/editor.mdx b/editor.mdx index 0e614ad68..4a3163137 100644 --- a/editor.mdx +++ b/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 Markdown 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 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 Markdown syntax. Date: Tue, 25 Nov 2025 17:20:48 -0800 Subject: [PATCH 3/5] Emphasize .md is for migration, .mdx is recommended --- migration.mdx | 8 ++++++-- organize/pages.mdx | 2 +- 2 files changed, 7 insertions(+), 3 deletions(-) diff --git a/migration.mdx b/migration.mdx index 28415c713..604d61bb6 100644 --- a/migration.mdx +++ b/migration.mdx @@ -147,13 +147,17 @@ 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. -- A Markdown file (`.md` or `.mdx`) 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 Markdown format, copy the content to your Mintlify project. Otherwise, convert your content to Markdown format. +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. + + If you migrate your content as `.md` files, convert them to `.mdx` to support interactive features like React components. + + ### Asset migration 1. Copy assets to your repository's `images/` directory. diff --git a/organize/pages.mdx b/organize/pages.mdx index b2081da20..a212b8aa5 100644 --- a/organize/pages.mdx +++ b/organize/pages.mdx @@ -4,7 +4,7 @@ description: "Configure page metadata, titles, and frontmatter properties." keywords: ["tags", "tag", "frontmatter", "metadata", "layout"] --- -Each page is a Markdown file (`.md` or `.mdx`). MDX files combine Markdown with React components to 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 From 5f4a78a768b886bcad0b2a4d28a804529a435010 Mon Sep 17 00:00:00 2001 From: Ethan Palm <56270045+ethanpalm@users.noreply.github.com> Date: Tue, 25 Nov 2025 18:57:38 -0800 Subject: [PATCH 4/5] favor MDX --- deploy/personalization-setup.mdx | 2 +- editor.mdx | 12 ++++++------ organize/navigation.mdx | 2 +- 3 files changed, 8 insertions(+), 8 deletions(-) diff --git a/deploy/personalization-setup.mdx b/deploy/personalization-setup.mdx index db3427729..927bcd1c8 100644 --- a/deploy/personalization-setup.mdx +++ b/deploy/personalization-setup.mdx @@ -82,7 +82,7 @@ type User = { { "firstName": "Ronan", "company": "Acme Corp", "plan": "Enterprise" } ``` - **Usage in Markdown**: + **Usage in MDX**: ```mdx Welcome back, {user.firstName}! Your {user.plan} plan includes... ``` diff --git a/editor.mdx b/editor.mdx index 4a3163137..2b1e8ab49 100644 --- a/editor.mdx +++ b/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 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 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. / to open the component menu. Add content block /> -In Markdown mode, directly edit the Markdown of your pages. This can be helpful when you need to: +In Markdown mode, 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 Markdown 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 @@ -404,13 +404,13 @@ Find solutions to common issues you might encounter while using the visual edito **Possible causes:** - - Invalid Markdown syntax in files + - Invalid MDX syntax in files - Missing or corrupted files - Large file sizes causing timeouts **Solutions:** - 1. Check the file syntax for Markdown formatting errors + 1. Check the file syntax for MDX formatting errors 2. Verify the file exists in your repository. diff --git a/organize/navigation.mdx b/organize/navigation.mdx index 31ddf4eb8..5574bec3a 100644 --- a/organize/navigation.mdx +++ b/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. Each page is a Markdown file in your documentation repository. +Pages are the most fundamental navigation component. Each page is an MDX file in your documentation repository. Date: Tue, 25 Nov 2025 19:13:46 -0800 Subject: [PATCH 5/5] missing words --- editor.mdx | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/editor.mdx b/editor.mdx index 2b1e8ab49..bae5ff72d 100644 --- a/editor.mdx +++ b/editor.mdx @@ -240,7 +240,7 @@ In visual mode, press / to open the component menu. Add content block /> -In Markdown mode, 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