Add info on migrating to docs.json from mint.json

changelog.mdx

@@ -83,7 +83,7 @@
   - Improved styling nits for dashboard border for mobile-tablet-desktop responsiveness
   - Show code examples even when in simple mode for API playground
   - Support "command \+ k" shortcut for search in web editor
   - Codeblocks within callouts expand to fill the width of the callout area
 </Update>
 
 <Update label="February 2025">
@@ -108,15 +108,15 @@
   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
 
   Automatically lint your docs to find broken links, discover spelling and grammar issues, or enforce writing styles with your own Vale config. Learn more in our [docs](settings/ci).
 
   ## .md support for LLMs
 
   All documentation pages are now automatically available as plain Markdown files—just append `.md` to the URL. This makes it easier for LLMs to ingest individual pages from your documentation.
 
   ## More Themes
 
@@ -144,7 +144,7 @@
   - 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
 
@@ -198,7 +198,7 @@
   <Frame>
     ![llms.txt support](/images/changelog/llms.jpg)
   </Frame>
   All docs instances are now automatically hosted at /llms.txt and /llms-full.txt so that LLMs can easily ingest your documentation. For more information, read the [docs on the new llms.txt standard.](https://llmstxt.org)
 
   ## Localization
 
@@ -242,7 +242,7 @@
 
   ## 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": {
@@ -270,7 +270,7 @@
   ## Dashboard Improvements
 
   - Added ability to change custom domain to be /docs directly through dashboard settings.
   - Consolidated the login and signup pages to decrease friction and confusion.
   - Implemented the discovery login flow so that users that are members of multiple organizations can now switch between them.
   - Added login with Google OAuth
   - Added ability to add new deployment through dashboard settings.
@@ -284,7 +284,7 @@
   - Don't allow search engines to crawl user-auth protected pages.
   - Revalidate the cache when an org is deleted.
   - We now use the Scalar OpenAPI parser to parse OpenAPI definitions which improves the performance, fixes parsing issues, and surfaces better error messages.
   - Top-level descriptions are now supported in API reference pages autogenerated from OpenAPI definitions.
   - Add in-line-style support for icons
   - Fixed the pop-in of custom CSS in docs.
   - Properly show in-line code styling in conjunction with links.
@@ -317,7 +317,7 @@
   <Frame>
     ![SEO Improvements](/images/changelog/seo-improvements.jpeg)
   </Frame>
   We've fixed  both the mobile and desktop layout of our docs so that they are more SEO-friendly - including adding proper aria tags to navbar and toggle elements.
 
   ## Dashboard Improvements
 
@@ -351,7 +351,7 @@
 
   ## File Uploads in API Playground
 
   By default, API playground requests are proxied by Mintlify. Now you can use
   `disableProxy` to disable this behavior and support request types like file
   uploads.
 
@@ -384,7 +384,7 @@
   </Frame>
   For `Pro` users, we introduced Mintlify Widget, an extension of your docs to
   answer your users' questions when and where they asked. You can add this
   AI-powered chatbot to any web page: your landing page, inside your product, or
   on your existing documentation pages.
 
   - [Read the blog announcement](https://mintlify.com/blog/widget)
@@ -409,17 +409,17 @@
 <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">
   ## Okta SSO
 
   We now support sign-on via Okta SAML and OIDC.
 
   ## Mintlify REST API
 
@@ -442,7 +442,7 @@
 <Update label="March 2024">
   ## Mintlify MDX for VSCode
 
   Call snippets of our pre-built components and callouts without leaving VSCode. [Install the extension here](https://marketplace.visualstudio.com/items?itemName=mintlify.mintlify-snippets).
 </Update>
 
 <Update label="February 2024">
@@ -451,7 +451,7 @@
   - Dashboard upgrades: view update logs to see what's changed and status of an update, toggle between Mintlify projects to manage deployments
   - Versioning with tabs fully supported
   - Wildcard redirects now supported
   - CLI Error Detection: we now show the position of invalid frontmatter when there are parsing issues during local development
 </Update>
 
 <Update label="January 2024">

settings.mdx

@@ -13,7 +13,7 @@
 
 To get started, you only need to specify `theme`, `name`, `colors.primary`, and `navigation`. Other fields are optional and you can add them as your documentation needs grow.
 
 For the best editing experience, include the schema reference at the top of your `docs.json` file. This enables autocomplete, validation, and helpful tooltips in most code editors:
 
 ```json
 {
@@ -145,7 +145,7 @@
 
   <Expandable title="Fonts">
     <ResponseField name="family" type="string" required>
       Font family, such as "Open Sans", "Playfair Display".
     </ResponseField>
     <ResponseField name="weight" type="number">
       Font weight, such as 400 or 700. Variable fonts support precise weights  such as 550.
@@ -250,12 +250,12 @@
 
 ### Structure
 
 <ResponseField name="navbar" type="object">
   Navigation bar items.
 
   <Expandable title="Navbar">
     <ResponseField name="links" type="array of object">
       Links to display in the navbar
 
       <Expandable title="Links">
         <ResponseField name="label" type="string" required>
@@ -293,7 +293,7 @@
 
   <Expandable title="Navigation">
     <ResponseField name="global" type="object">
       Global navigation elements that appear accross all pages and sections.
 
       <Expandable title="Global">
         <ResponseField name="languages" type="array of object">
@@ -527,7 +527,7 @@
   Contextual menu for AI-optimized content and integrations.
 
   <Expandable title="Contextual">
     <ResponseField name="options" type="array of &quot;copy&quot; | &quot;view&quot; | &quot;chatgpt&quot; | &quot;claude&quot;" required>
       Actions available in the contextual menu. The first option appears as the default.
       - `copy`: Copy the current page as Markdown to the clipboard.
       - `view`: View the current page as Markdown in a new tab.
@@ -546,7 +546,7 @@
 
 ### API Configurations
 
 <ResponseField name="api" type="object">
   API documentation and interactive playground settings.
 
   <Expandable title="Api">
@@ -965,7 +965,7 @@
       "footer": {
         "socials": {
           "x": "https://x.com/example",
           "linkedin": "https://www.linkedin.com/company/example",
           "github": "https://github.com/example",
           "slack": "https://example.com/community"
         },
@@ -1008,7 +1008,7 @@
       },
       "integrations": {
         "ga4": {
           "measurementId": "G-XXXXXXXXXX"
         },
         "koala": {
           "publicApiKey": "pk_example_key_123"
@@ -1017,8 +1017,8 @@
           "enabled": true
         },
         "cookies": {
           "key": "example_cookie_key",
           "value": "example_cookie_value"
         }
       },
       "contextual": {
@@ -1139,7 +1139,7 @@
       "footer": {
         "socials": {
           "x": "https://x.com/example",
           "linkedin": "https://www.linkedin.com/company/example",
           "github": "https://github.com/example",
           "slack": "https://example.com/community"
         },
@@ -1182,7 +1182,7 @@
       },
       "integrations": {
         "ga4": {
           "measurementId": "G-XXXXXXXXXX"
         },
         "koala": {
           "publicApiKey": "pk_example_key_123"
@@ -1191,8 +1191,8 @@
           "enabled": true
         },
         "cookies": {
           "key": "example_cookie_key",
           "value": "example_cookie_value"
         }
       },
       "contextual": {
@@ -1277,10 +1277,10 @@
               {
                 "dropdown": "Documentación",
                 "icon": "book",
                 "description": "Cómo usar el producto de Example Co.",
                 "pages": [
                   {
                     "group": "Comenzando",
                     "pages": ["es/index", "es/quickstart"]
                   },
                   {
@@ -1300,7 +1300,7 @@
               {
                 "dropdown": "Changelog",
                 "icon": "history",
                 "description": "Actualizaciones y cambios",
                 "pages": ["es/changelog"]
               }
             ]
@@ -1328,7 +1328,7 @@
       "footer": {
         "socials": {
           "x": "https://x.com/example",
           "linkedin": "https://www.linkedin.com/company/example",
           "github": "https://github.com/example",
           "slack": "https://example.com/community"
         },
@@ -1371,7 +1371,7 @@
       },
       "integrations": {
         "ga4": {
           "measurementId": "G-XXXXXXXXXX"
         },
         "koala": {
           "publicApiKey": "pk_example_key_123"
@@ -1380,8 +1380,8 @@
           "enabled": true
         },
         "cookies": {
           "key": "example_cookie_key",
           "value": "example_cookie_value"
         }
       },
       "contextual": {
@@ -1396,3 +1396,50 @@
     ```
   </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>