From 0d91ea5063983fa97968f41d9a574226b401e37f Mon Sep 17 00:00:00 2001
From: Ethan Palm <56270045+ethanpalm@users.noreply.github.com>
Date: Fri, 20 Jun 2025 11:46:29 -0700
Subject: [PATCH 1/2] remove outdated `mint.json` references

---
 changelog.mdx | 10 +++++-----
 1 file changed, 5 insertions(+), 5 deletions(-)

diff --git a/changelog.mdx b/changelog.mdx
index 22b648a92..0b6664b57 100644
--- a/changelog.mdx
+++ b/changelog.mdx
@@ -108,7 +108,7 @@ mode: "center"
   mint upgrade
   ```
 
-  1. Delete your old mint.json file and push your changes
+  1. Delete your old `mint.json` file and push your changes
 
   ## CI Checks
 
@@ -144,7 +144,7 @@ mode: "center"
   - New UI with dedicated chat page & pre-filled prompts
   - Stability improvements, e.g. bug fixes of editing the wrong file or no files at all
   - More robust knowledge for adding & editing components
-  - Improved mint.json file editing
+  - Improved `docs.json` file editing
 
   ## Partial Authentication
 
@@ -242,7 +242,7 @@ mode: "center"
 
   ## Light mode code blocks
 
-  Code blocks now have a light mode variant which can be enabled by adding the following to your `mint.json`:
+  Code blocks now have a light mode variant which can be enabled by adding the following to your `docs.json`:
 
   ```json
   "codeBlock": {
@@ -409,11 +409,11 @@ mode: "center"
 <Update label="June 2024">
   ## Launch Week Highlights
 
-  - Themes: Customize your styling with pre-configured themes. Just add the theme Quill, Prism, or Venus to your `mint.json` file and it'll update your docs styling.
+  - Themes: Customize your styling with pre-configured themes. Just add the theme Quill, Prism, or Venus to your `docs.json` file and it'll update your docs styling.
   - Search V2: directly query OpenAPI endpoint descriptions and titles to reach API Reference pages, remove hidden pages from search, and enjoy our updated search bar UI.
   - Web Editor branching: create branches in our web editor without an IDE.
   - User Personalization: authenticate users with Shared Session or JWT so that you can show them customized content, such as pre-filling API keys or showing specific content for customers.
-  - OepenAPI Automation Upgrades: to auto-populate API Playground pages, you can add an `openapi` field to an object in tabs or anchors arrays in the mint.json.
+  - OpenAPI Automation Upgrades: to auto-populate API Playground pages, you can add an `openapi` field to an object in tabs or anchors arrays in the `docs.json`.
 </Update>
 
 <Update label="May 2024">

From c6ff0c827cdb421973162cc048a05a10c9b7f0f4 Mon Sep 17 00:00:00 2001
From: Ethan Palm <56270045+ethanpalm@users.noreply.github.com>
Date: Fri, 20 Jun 2025 12:02:39 -0700
Subject: [PATCH 2/2] add upgrading steps

---
 settings.mdx | 47 +++++++++++++++++++++++++++++++++++++++++++++++
 1 file changed, 47 insertions(+)

diff --git a/settings.mdx b/settings.mdx
index 2836f68a2..087353f4a 100644
--- a/settings.mdx
+++ b/settings.mdx
@@ -1396,3 +1396,50 @@ See [Themes](themes) for more information.
     ```
   </Tab>
 </Tabs>
+
+## Upgrading from `mint.json`
+
+If your docs project uses the deprecated `mint.json` file, follow these steps to upgrade to `docs.json`.
+
+<Steps>
+<Step title="Install or update the CLI">
+If you haven't installed the [CLI](/installation), install it now:
+
+<CodeGroup>
+
+```bash npm
+npm i -g mint
+```
+
+
+```bash yarn
+yarn global add mint
+```
+
+
+```bash pnpm
+pnpm add -g mint
+```
+
+</CodeGroup>
+
+If you already have the CLI installed, make sure it is up to date:
+
+```bash
+mint update
+```
+
+</Step>
+<Step title="Create your docs.json file">
+In your docs repository, run:
+
+```bash
+mint upgrade
+```
+
+This command will create a `docs.json` file from your existing `mint.json`. Review the generated file to ensure all settings are correct.
+</Step>
+<Step title="Delete your mint.json file">
+After verifying your `docs.json` is configured properly, you can safely delete your old `mint.json` file.
+</Step>
+</Steps>