x-mint migrate script

api-playground/migrating-from-mdx.mdx

@@ -5,11 +5,51 @@
 icon: "arrow-big-right-dash"
 ---
 
 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.
 
-## Migration steps
+## CLI migration
+
+The `mint migrate-mdx` command is the recommended way to migrate from MDX endpoint pages to autogenerated pages.
+
+This command:
+- Parses your `docs.json` navigation structure.
+- Identifies MDX pages that reference OpenAPI endpoints.
+- Extracts content from MDX files and moves it to the `x-mint` extension in your OpenAPI specification.
+- Migrates any existing `x-mcp` data into `x-mint`.
+- Updates your `docs.json` to reference the OpenAPI endpoints directly instead of MDX files.
+- 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>
+<Step title="Prepare your OpenAPI specification.">
+    Ensure your OpenAPI specification is valid and includes all endpoints you want to document.
+
+    Any MDX pages you want to migrate must have the `openapi:` frontmatter referencing an endpoint.
+
+    <Tip>
+      Validate your OpenAPI file using the [Swagger Editor](https://editor.swagger.io/) or [Mint CLI](https://www.npmjs.com/package/mint).
+    </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
+    mint migrate-mdx
+    ```
+  </Step>
+</Steps>
+
+## Manual migration steps
 
 <Steps>
   <Step title="Prepare your OpenAPI specification.">

installation.mdx

@@ -126,6 +126,16 @@
 mint rename <oldFilename> <newFilename>
 ```
 
+### Migrating MDX endpoint pages
+
+You can migrate MDX endpoint pages to autogenerated pages from your OpenAPI specification using the following command:
+
+```bash
+mint migrate-mdx
+```
+
+This command converts individual MDX endpoint pages to autogenerated pages defined in your `docs.json`, moves MDX content to the `x-mint` extension in your OpenAPI specification, and updates your navigation. See [Migrating from MDX](/api-playground/migrating-from-mdx) for detailed information.
+
 ## Formatting
 
 While developing locally, we recommend using extensions in your IDE to recognize and format `MDX` files.