diff --git a/api-playground/mdx/authentication.mdx b/api-playground/mdx/authentication.mdx index b6469ecb7..feb71f131 100644 --- a/api-playground/mdx/authentication.mdx +++ b/api-playground/mdx/authentication.mdx @@ -5,18 +5,20 @@ description: "You can set authentication parameters to let users use their real ## Enabling Authentication -You can add an authentication method to your mint.json to enable it on every page or you can set it on a per-page basis. +You can add an authentication method to your docs.json to enable it on every page or you can set it on a per-page basis. -The page's authentication method will override mint.json if both are set. +The page's authentication method will override docs.json if both are set. ### Bearer Token -```json mint.json +```json docs.json "api": { - "auth": { + "mdx": { + "auth": { "method": "bearer" + } } } ``` @@ -34,10 +36,12 @@ authMethod: "bearer" -```json mint.json +```json docs.json "api": { - "auth": { + "mdx": { + "auth": { "method": "basic" + } } } ``` @@ -55,11 +59,13 @@ authMethod: "basic" -```json mint.json +```json docs.json "api": { - "auth": { + "mdx": { + "auth": { "method": "key", "name": "x-api-key" + } } } ``` @@ -75,7 +81,7 @@ authMethod: "key" ### None -The "none" authentication method is useful to disable authentication on a specific endpoint after setting a default in mint.json. +The "none" authentication method is useful to disable authentication on a specific endpoint after setting a default in docs.json. ```md Page Metadata diff --git a/api-playground/mdx/configuration.mdx b/api-playground/mdx/configuration.mdx index 55682df30..48a1d39ae 100644 --- a/api-playground/mdx/configuration.mdx +++ b/api-playground/mdx/configuration.mdx @@ -3,18 +3,19 @@ title: 'MDX Setup' description: 'Generate docs pages for your API endpoints using MDX' --- -Mintlify allows you to define your API endpoints using a combination of `mint.json` configuration, MDX metadata fields, and the `` component. From the defined endpoints, we generate an API playground, request examples, and response examples. +Mintlify allows you to define your API endpoints using a combination of `docs.json` configuration, MDX metadata fields, and the `` component. From the defined endpoints, we generate an API playground, request examples, and response examples. - In your `mint.json` file, define your base URL and auth method: + In your `docs.json` file, define your base URL and auth method: ```json - { - "api": { - "baseUrl": "https://mintlify.com/api", // string array for multiple base URLs + "api": { + "mdx": { + "server": "https://mintlify.com/api", // string array for multiple base URLs "auth": { - "method": "bearer" // options: bearer, basic, key. + "method": "key", + "name": "x-api-key" // options: bearer, basic, key. } } } @@ -23,16 +24,14 @@ Mintlify allows you to define your API endpoints using a combination of `mint.js If you would not like to show an API playground, you don't need to include auth types. Hide the playground with the following field: ```json - { - "api": { - "playground": { - "mode": "hide" - } + "api": { + "playground": { + "display": "none" } } ``` - Find a full list of API configurations [here](/settings/global#api-configurations). + Find a full list of API configurations [here](/settings/global#param-api). @@ -54,12 +53,12 @@ Mintlify allows you to define your API endpoints using a combination of `mint.js - If you have `baseUrl` configured in [mint.json](/settings/global), you can use relative paths like `/v1/endpoint`. + If you have `server` configured in [docs.json](/settings/global), you can use relative paths like `/v1/endpoint`. - Add your endpoint pages to the sidebar by adding the paths to the `navigation` field in your `mint.json`. Learn more about structuring your docs [here](/settings/navigation). + Add your endpoint pages to the sidebar by adding the paths to the `navigation` field in your `docs.json`. Learn more about structuring your docs [here](/settings/navigation). diff --git a/api-playground/openapi/setup.mdx b/api-playground/openapi/setup.mdx index bc24fbbf6..41bdf0fd6 100644 --- a/api-playground/openapi/setup.mdx +++ b/api-playground/openapi/setup.mdx @@ -12,7 +12,7 @@ follow OpenAPI specification 3.0+. ## Auto-populate API pages -The fastest way to get started with OpenAPI is to add an `openapi` field to a tab or anchor in the `mint.json`. This field can contain either the path to an OpenAPI document in your docs repo, or the URL of a hosted OpenAPI document. Mintlify will automatically generate a page for each OpenAPI operation and place them in the tab/anchor. +The fastest way to get started with OpenAPI is to add an `openapi` field to a tab or anchor in the `docs.json`. This field can contain either the path to an OpenAPI document in your docs repo, or the URL of a hosted OpenAPI document. Mintlify will automatically generate a page for each OpenAPI operation and place them in the tab/anchor. **Example with Anchors:** diff --git a/api-playground/troubleshooting.mdx b/api-playground/troubleshooting.mdx index 85504e746..4b411e6a1 100644 --- a/api-playground/troubleshooting.mdx +++ b/api-playground/troubleshooting.mdx @@ -76,7 +76,7 @@ openapi: "v1 GET /users/{id}" Alternatively, if your reverse proxy prevents you from accepting `POST` requests, you can configure Mintlify to send requests directly to your backend with the `api.playground.disableProxy` - setting in the `mint.json`, as described [here](/settings/global#api-configurations). This will + setting in the `docs.json`, as described [here](/settings/global#api-configurations). This will likely require you to configure CORS on your server, as these requests will now come directly from your users' browsers. diff --git a/development.mdx b/development.mdx index 856629aaf..a36c3c707 100644 --- a/development.mdx +++ b/development.mdx @@ -27,7 +27,7 @@ description: 'Preview changes locally to update your docs' -**Step 2**: Navigate to the docs directory (where the `mint.json` file is located) and execute the following command: +**Step 2**: Navigate to the docs directory (where the `docs.json` file is located) and execute the following command: ```bash mintlify dev diff --git a/integrations/analytics/amplitude.mdx b/integrations/analytics/amplitude.mdx index 13b92ef57..630323ef8 100644 --- a/integrations/analytics/amplitude.mdx +++ b/integrations/analytics/amplitude.mdx @@ -2,12 +2,12 @@ title: "Amplitude" --- -Add the following to your `mint.json` file to send analytics to Amplitude. +Add the following to your `docs.json` file to send analytics to Amplitude. -```json Analytics options in mint.json -"analytics": { +```json Analytics options in docs.json +"integrations": { "amplitude": { "apiKey": "required" } @@ -15,7 +15,7 @@ Add the following to your `mint.json` file to send analytics to Amplitude. ``` ```json Example -"analytics": { +"integrations": { "amplitude": { "apiKey": "76bb138bf3fbf58186XXX00000" } diff --git a/integrations/analytics/clearbit.mdx b/integrations/analytics/clearbit.mdx index 629525434..5290bf5be 100644 --- a/integrations/analytics/clearbit.mdx +++ b/integrations/analytics/clearbit.mdx @@ -2,12 +2,12 @@ title: "Clearbit" --- -Add the following to your `mint.json` file to send analytics to Clearbit. +Add the following to your `docs.json` file to send analytics to Clearbit. -```json Analytics options in mint.json -"analytics": { +```json Analytics options in docs.json +integrations: { "clearbit": { "publicApiKey": "required" } @@ -15,7 +15,7 @@ Add the following to your `mint.json` file to send analytics to Clearbit. ``` ```json Example -"analytics": { +integrations: { "clearbit": { "publicApiKey": "pk_1a1882" } diff --git a/integrations/analytics/fathom.mdx b/integrations/analytics/fathom.mdx index b522c8726..fd950c85f 100644 --- a/integrations/analytics/fathom.mdx +++ b/integrations/analytics/fathom.mdx @@ -2,14 +2,14 @@ title: "Fathom" --- -Add the following to your `mint.json` file to send analytics to Fathom. +Add the following to your `docs.json` file to send analytics to Fathom. You can get the `siteId` from your script settings. -```json Analytics options in mint.json -"analytics": { +```json Analytics options in docs.json +integrations: { "fathom": { "siteId": "required" } @@ -17,7 +17,7 @@ You can get the `siteId` from your script settings. ``` ```json Example -"analytics": { +integrations: { "fathom": { "siteId": "YSVMSDAY" } diff --git a/integrations/analytics/google-analytics.mdx b/integrations/analytics/google-analytics.mdx index 7ebfe1610..d6ae5c97f 100644 --- a/integrations/analytics/google-analytics.mdx +++ b/integrations/analytics/google-analytics.mdx @@ -20,12 +20,12 @@ Create a Web Stream and put the URL of your Mintlify docs site as the stream URL Your Measurement ID looks like `G-XXXXXXX` and will show up under Stream Details immediately after you create the Web Stream. -### Put Measurement ID in mint.json +### Put Measurement ID in docs.json -Add your Measurement ID to your `mint.json` file like so: +Add your Measurement ID to your `docs.json` file like so: -```json mint.json -"analytics": { +```json docs.json +integrations: { "ga4": { "measurementId": "G-XXXXXXX" } diff --git a/integrations/analytics/google-tag-manager.mdx b/integrations/analytics/google-tag-manager.mdx index 0e715d0c3..3bdb8fe37 100644 --- a/integrations/analytics/google-tag-manager.mdx +++ b/integrations/analytics/google-tag-manager.mdx @@ -2,14 +2,14 @@ title: "Google Tag Manager" --- -Add your tag ID to `mint.json` file and we'll inject the Google Tag Manager script to all your pages. +Add your tag ID to `docs.json` file and we'll inject the Google Tag Manager script to all your pages. You are responsible for setting up cookie consent banners with Google Tag Manager if you need them. -```json Analytics options in mint.json -"analytics": { +```json Analytics options in docs.json +integrations: { "gtm": { "tagId": "required" } @@ -17,7 +17,7 @@ You are responsible for setting up cookie consent banners with Google Tag Manage ``` ```json Example -"analytics": { +integrations: { "gtm": { "tagId": "GTM-MGBL4PW" } diff --git a/integrations/analytics/heap.mdx b/integrations/analytics/heap.mdx index e863628e2..d0d00534b 100644 --- a/integrations/analytics/heap.mdx +++ b/integrations/analytics/heap.mdx @@ -2,12 +2,12 @@ title: "Heap" --- -Add the following to your `mint.json` file to send analytics to Heap. +Add the following to your `docs.json` file to send analytics to Heap. -```json Analytics options in mint.json -"analytics": { +```json Analytics options in docs.json +integrations: { "heap": { "appId": "required" } @@ -15,7 +15,7 @@ Add the following to your `mint.json` file to send analytics to Heap. ``` ```json Example -"analytics": { +integrations: { "heap": { "appId": "1234567890" } diff --git a/integrations/analytics/hotjar.mdx b/integrations/analytics/hotjar.mdx index a872a8f72..ea6945bb0 100644 --- a/integrations/analytics/hotjar.mdx +++ b/integrations/analytics/hotjar.mdx @@ -2,10 +2,10 @@ title: "HotJar" --- -Add the following to your `mint.json` file to send analytics to HotJar. +Add the following to your `docs.json` file to send analytics to HotJar. -```json Analytics options in mint.json -"analytics": { +```json Analytics options in docs.json +integrations: { "hotjar": { "hjid": "required", "hjsv": "required" diff --git a/integrations/analytics/koala.mdx b/integrations/analytics/koala.mdx index 03a7eab71..9984de897 100644 --- a/integrations/analytics/koala.mdx +++ b/integrations/analytics/koala.mdx @@ -2,12 +2,12 @@ title: "Koala" --- -Add the following to your `mint.json` file to send analytics to Koala. +Add the following to your `docs.json` file to send analytics to Koala. -```json Analytics options in mint.json -"analytics": { +```json Analytics options in docs.json +integrations: { "koala": { "publicApiKey": "required" } @@ -15,7 +15,7 @@ Add the following to your `mint.json` file to send analytics to Koala. ``` ```json Example -"analytics": { +integrations: { "koala": { "publicApiKey": "pk_1a1882" } diff --git a/integrations/analytics/logrocket.mdx b/integrations/analytics/logrocket.mdx index 702de184b..484fb1ac0 100644 --- a/integrations/analytics/logrocket.mdx +++ b/integrations/analytics/logrocket.mdx @@ -2,10 +2,10 @@ title: "LogRocket" --- -Add the following to your `mint.json` file to send analytics to LogRocket. +Add the following to your `docs.json` file to send analytics to LogRocket. -```json Analytics options in mint.json -"analytics": { +```json Analytics options in docs.json +integrations: { "logrocket": { "apiKey": "required" } diff --git a/integrations/analytics/mixpanel.mdx b/integrations/analytics/mixpanel.mdx index f1851d5c5..3aada5a90 100644 --- a/integrations/analytics/mixpanel.mdx +++ b/integrations/analytics/mixpanel.mdx @@ -2,10 +2,10 @@ title: "Mixpanel" --- -Add the following to your `mint.json` file to send analytics to Mixpanel. +Add the following to your `docs.json` file to send analytics to Mixpanel. -```json Analytics options in mint.json -"analytics": { +```json Analytics options in docs.json +integrations: { "mixpanel": { "projectToken": "required" } diff --git a/integrations/analytics/overview.mdx b/integrations/analytics/overview.mdx index fe9574b9b..98cb627c7 100644 --- a/integrations/analytics/overview.mdx +++ b/integrations/analytics/overview.mdx @@ -506,14 +506,14 @@ className="h-6 w-6" ## Enabling Analytics -Set your analytics keys in `mint.json`. You can add an unlimited number of analytics integrations for free. +Set your analytics keys in `docs.json`. You can add an unlimited number of analytics integrations for free. -The syntax for `mint.json` is below. You only need to include entries for the platforms you want to connect. +The syntax for `docs.json` is below. You only need to include entries for the platforms you want to connect. -```json Analytics options in mint.json -"analytics": { +```json Analytics options in docs.json +integrations: { "amplitude": { "apiKey": "required" }, @@ -556,7 +556,7 @@ The syntax for `mint.json` is below. You only need to include entries for the pl ``` ```json Google Analytics 4 Example -"analytics": { +integrations: { "ga4": { "measurementId": "G-XXXXXXX" } diff --git a/integrations/analytics/pirsch.mdx b/integrations/analytics/pirsch.mdx index e4b3e3085..8b03002bf 100644 --- a/integrations/analytics/pirsch.mdx +++ b/integrations/analytics/pirsch.mdx @@ -2,14 +2,14 @@ title: "Pirsch" --- -Add the following to your `mint.json` file to send analytics to Pirsch. +Add the following to your `docs.json` file to send analytics to Pirsch. You can get your site ID from Settings \> Developer \> Identification Code. -```json Analytics options in mint.json -"analytics": { +```json Analytics options in docs.json +integrations: { "pirsch": { "id": "required" } @@ -17,7 +17,7 @@ You can get your site ID from Settings \> Developer \> Identification Code. ``` ```json Example -"analytics": { +integrations: { "pirsch": { "id": "8Kw7OKxBfswOjnKGZa7P9Day8JmVYwTp" } diff --git a/integrations/analytics/plausible.mdx b/integrations/analytics/plausible.mdx index 8d65d86a4..d013c1e6a 100644 --- a/integrations/analytics/plausible.mdx +++ b/integrations/analytics/plausible.mdx @@ -2,7 +2,7 @@ title: "Plausible" --- -Add your site's domain to `mint.json` to send analytics to Plausible. +Add your site's domain to `docs.json` to send analytics to Plausible. @@ -12,8 +12,8 @@ Add your site's domain to `mint.json` to send analytics to Plausible. -```json Analytics options in mint.json -"analytics": { +```json Analytics options in docs.json +integrations: { "plausible": { "domain": "required", "server": "optional" @@ -22,7 +22,7 @@ Add your site's domain to `mint.json` to send analytics to Plausible. ``` ```json Example -"analytics": { +integrations: { "plausible": { "domain": "docs.domain.com" } diff --git a/integrations/analytics/posthog.mdx b/integrations/analytics/posthog.mdx index b78cabb18..88db05972 100644 --- a/integrations/analytics/posthog.mdx +++ b/integrations/analytics/posthog.mdx @@ -2,14 +2,14 @@ title: "PostHog" --- -Add the following to your `mint.json` file to send analytics to PostHog. +Add the following to your `docs.json` file to send analytics to PostHog. You only need to include `apiHost` if you are self-hosting PostHog. We send events to `https://app.posthog.com` by default. -```json Analytics options in mint.json -"analytics": { +```json Analytics options in docs.json +integrations: { "posthog": { "apiKey": "required", "apiHost": "optional" @@ -18,7 +18,7 @@ You only need to include `apiHost` if you are self-hosting PostHog. We send even ``` ```json Example -"analytics": { +integrations: { "posthog": { "apiKey": "phc_TXdpocbYTeZVm5VJmMzHTMrCofBQu3e0kN7HGMNGTVW" } diff --git a/integrations/analytics/segment.mdx b/integrations/analytics/segment.mdx index 1f1b8076b..3ee4ad631 100644 --- a/integrations/analytics/segment.mdx +++ b/integrations/analytics/segment.mdx @@ -2,12 +2,12 @@ title: "Segment" --- -Add your Segment write key to your `mint.json` file to send analytics to Segment. +Add your Segment write key to your `docs.json` file to send analytics to Segment. -```json Analytics options in mint.json -"analytics": { +```json Analytics options in docs.json +integrations: { "segment": { "key": "required", } @@ -15,7 +15,7 @@ Add your Segment write key to your `mint.json` file to send analytics to Segment ``` ```json Example -"analytics": { +integrations: { "segment": { "key": "nqJxiRG15Y6M594P8Sb8ESEciU3VC2" } diff --git a/integrations/privacy/osano.mdx b/integrations/privacy/osano.mdx index ded3d2d59..71aca7ccd 100644 --- a/integrations/privacy/osano.mdx +++ b/integrations/privacy/osano.mdx @@ -2,11 +2,11 @@ title: "Osano" --- -Add the following to your `mint.json` file to add the [Osano](https://www.osano.com/) cookie consent manager. +Add the following to your `docs.json` file to add the [Osano](https://www.osano.com/) cookie consent manager. -```json Integration options in mint.json +```json Integration options in docs.json "integrations": { "osano": "SOURCE" } diff --git a/integrations/privacy/overview.mdx b/integrations/privacy/overview.mdx index 737baebe5..f70e8d841 100644 --- a/integrations/privacy/overview.mdx +++ b/integrations/privacy/overview.mdx @@ -15,7 +15,7 @@ description: "Integrate with a data privacy platform" ## Enabling Data Privacy Integrations -You can add data privacy platforms onto your docs. Add the `integrations` field into your `mint.json` file with your respective scripts. +You can add data privacy platforms onto your docs. Add the `integrations` field into your `docs.json` file with your respective scripts. ```json "integrations": { diff --git a/integrations/support/front.mdx b/integrations/support/front.mdx index 8e1af6aff..2ed954af7 100644 --- a/integrations/support/front.mdx +++ b/integrations/support/front.mdx @@ -2,11 +2,11 @@ title: "Front" --- -Add the following to your `mint.json` file to add a [Front Chat](https://front.com) widget. +Add the following to your `docs.json` file to add a [Front Chat](https://front.com) widget. -```json Integration options in mint.json +```json Integration options in docs.json "integrations": { "frontchat": "CHAT_ID" } diff --git a/integrations/support/intercom.mdx b/integrations/support/intercom.mdx index 412c371c2..d47aa464c 100644 --- a/integrations/support/intercom.mdx +++ b/integrations/support/intercom.mdx @@ -2,11 +2,11 @@ title: "Intercom" --- -Add the following to your `mint.json` file to add an [Intercom](https://www.intercom.com) widget. +Add the following to your `docs.json` file to add an [Intercom](https://www.intercom.com) widget. -```json Integration options in mint.json +```json Integration options in docs.json "integrations": { "intercom": "APP_ID" } diff --git a/integrations/support/overview.mdx b/integrations/support/overview.mdx index 71be4aa65..e78f0c2d7 100644 --- a/integrations/support/overview.mdx +++ b/integrations/support/overview.mdx @@ -37,7 +37,7 @@ horizontal ## Enabling Support Integrations -You can integrate widgets onto your docs for customer support. Add the `integrations` field into your `mint.json` file with your respective app ID. +You can integrate widgets onto your docs for customer support. Add the `integrations` field into your `docs.json` file with your respective app ID. ```json "integrations": { diff --git a/quickstart.mdx b/quickstart.mdx index fd4ba0858..76ec6868b 100644 --- a/quickstart.mdx +++ b/quickstart.mdx @@ -41,7 +41,7 @@ your docs with your code, and make source control effortless. Onboard through th If you want your docs to live alongside your code as a monorepo setup, you can: 1. Move your docs content to your monorepo. 2. Specify the path to your - `mint.json` in the + `docs.json` in the [dashboard](https://dashboard.mintlify.com/settings/deployment/git-settings) - Easily customize colors, logos and buttons among other configurations in our `mint.json` file. Start with these basic configurations: + Easily customize colors, logos and buttons among other configurations in our `docs.json` file. Start with these basic configurations: ```json "name": "Your Company" @@ -136,7 +136,7 @@ your docs. You can easily set up your API references using an OpenAPI document. - 1. Add your `openapi.yaml` or `openapi.json` file into your docs repository or define the `openapi` field in `mint.json` with a URL. + 1. Add your `openapi.yaml` or `openapi.json` file into your docs repository or define the `openapi` field in `docs.json` with a URL. ```json "openapi": "link-to-your-openapi-file" @@ -148,7 +148,7 @@ your docs. npx @mintlify/scraping@latest openapi-file ``` - 3. Finally, include the generated endpoint MDX files to your `mint.json` under `navigation`. + 3. Finally, include the generated endpoint MDX files to your `docs.json` under `navigation`. For a complete guide on using Mintlify with OpenAPI, check out [this guide](/api-playground/openapi/setup). [This guide](/api-playground/openapi/writing-openapi) explains how to configure your API authentication methods. For manual API references definition, explore [our syntax](/api-playground/overview). diff --git a/settings/broken-links.mdx b/settings/broken-links.mdx index 7bd9f7e69..0573a4742 100644 --- a/settings/broken-links.mdx +++ b/settings/broken-links.mdx @@ -18,7 +18,7 @@ The CLI will identify any relative links in your docs that don't exist. ## Redirects -Set up 301 redirects by adding the `redirects` field into your `mint.json` file. +Set up 301 redirects by adding the `redirects` field into your `docs.json` file. ```json "redirects": [ diff --git a/settings/global.mdx b/settings/global.mdx index 12b41588d..0c5f94f9f 100644 --- a/settings/global.mdx +++ b/settings/global.mdx @@ -231,7 +231,7 @@ The path to the favicon. Can be a single file or a pair for light and dark mode. - + diff --git a/settings/navigation.mdx b/settings/navigation.mdx index ec1ab6e76..6ccb1d3dd 100644 --- a/settings/navigation.mdx +++ b/settings/navigation.mdx @@ -15,34 +15,28 @@ documentation. They show up above the main sidebar. -Configure tabs with the `tabs` field of the `mint.json` file. The `url` field of +Configure tabs with the `tabs` field of the `docs.json` file. The `href` field of the tab object should map to a folder of content added to your sidebar, or an external link. ```json -"tabs": [ - { - "name": "API References", - "url": "api-references" - }, - { - "name": "Content", - "url": "content" - }, - { - "name": "Blog", - "url": "https://your-website.com/blog" - } -] -``` - -To configure the default `Documentation` primary tab, add the `primaryTab` field -to your `mint.json` file with your desired name. Any files in your navigation -not in a folder reserved by another tab will show up in the primary tab. - -```json -"primaryTab": { - "name": "Home" +"navigation": { + "global": { + "tabs": [ + { + "tab": "API References", + "href": "api-references" + }, + { + "tab": "Content", + "href": "content" + }, + { + "tab": "Blog", + "href": "https://your-website.com/blog" + } + ] + } } ``` @@ -57,82 +51,89 @@ or link out to external URLs. -Configure anchors with the `anchors` field of the `mint.json` file. The `url` +Configure anchors with the `anchors` field of the `docs.json` file. The `href` field of the tab object should map an external link, or a folder of content added to your sidebar. More fields for anchors can be found [here](/settings/global). ```json -"anchors": [ - { - "name": "API References", - "icon": "code", - "url": "api-references" - }, - { - "name": "Content", - "icon": "pencil", - "url": "content" - }, - { - "name": "Contact us", - "icon": "envelope", - "url": "https://mintlify.com/contact-us" - } -] -``` - -To configure the default `Documentation` top anchor, add the `topAnchor` field -to your `mint.json`. - -```json -"topAnchor": { - "name": "Home", - "icon": "building" +"navigation": { + "global": { + "anchors": [ + { + "anchor": "API References", + "icon": "code", + "href": "api-references" + }, + { + "anchor": "Content", + "icon": "pencil", + "href": "content" + }, + { + "anchor": "Contact us", + "icon": "envelope", + "href": "https://mintlify.com/contact-us" + } + ] + } } ``` ## Sidebar Organize your navigation by defining the `navigation` property in your -mint.json, You don't need to include `.mdx` in page names. For sidebar styling options, see the [global settings page](/settings/global#param-sidebar) +docs.json, You don't need to include `.mdx` in page names. Once you add a page to your docs directory, you'll need to add the path to - `mint.json` to add it to the sidebar. Pages do not show up automatically. + `docs.json` to add it to the sidebar. Pages do not show up automatically. ```json Regular Navigation -"navigation": [ +"navigation": { + "tabs": [ { - "group": "Getting Started", - "pages": ["quickstart"] + "tab": "Docs", + "groups": [ + { + "group": "Getting Started", + "pages": ["quickstart"] + } + ] } -] + ] +} ``` ### Groups Create groups by recursively nesting a group within a group. - ```json Nested Navigation -"navigation": [ +"navigation": { + "tabs": [ { - "group": "Getting Started", - "pages": [ + "tab": "Docs", + "groups": [ + { + "group": "Getting Started", + "pages": [ "quickstart", { - "group": "Nested Reference Pages", - "pages": ["nested-reference-page"] + "group": "Nested Reference Pages", + "pages": ["nested-reference-page"] } - ] + ] + } + ] } -] + ] +} ``` ### Folders -Simply put your MDX files in folders and update the paths in `mint.json`. +Simply put your MDX files in folders and update the paths in `docs.json`. For example, to have a page at `https://yoursite.com/your-folder/your-page` you would make a folder called `your-folder` containing an MDX file called @@ -146,93 +147,113 @@ would make a folder called `your-folder` containing an MDX file called - ```json Navigation With Folder - "navigation": [ - { +```json Navigation with Folder +"navigation": { + "tabs": [ + { + "tab": "Docs", + "groups": [ + { "group": "Group Name", "pages": ["your-folder/your-page"] - } + } + ] + } ] - ``` +} +``` ```json Nested Navigation -"navigation": [ +"navigation": { + "tabs": [ { - "group": "Getting Started", - "pages": [ + "tab": "Docs", + "groups": [ + { + "group": "Getting Started", + "pages": [ "quickstart", { - "group": "Nested Reference Pages", - "pages": ["nested-reference-page"] + "group": "Nested Reference Pages", + "pages": ["nested-reference-page"] } - ] + ] + } + ] } -] + ] +} ``` ### Hidden Pages -MDX files not included in `mint.json` will not show up in the sidebar but are +MDX files not included in `docs.json` will not show up in the sidebar but are accessible by linking directly to them. Hidden pages are not indexed for search within your docs by default. If you would like to override this behavior, you can set the -[`seo.indexHiddenPages`](/settings/global#search-engine-optimization) attribute -in your `mint.json` to `true`. +[`seo.indexing`](/settings/global#param-indexing) attribute +in your `docs.json` to `navigable`. ## Topbar ### Links -Add links to the topbar with the `topbarLinks` field in the `mint.json` file. +Add links to the topbar with the `topbarLinks` field in the `docs.json` file. -The `topbarLinks` field supports the following fields: `name`, `url`. - +The `links` field supports the following fields: `label`, `href`. ```json - "topbarLinks": [ +"navbar": { + "links": [ { - "name": "Community", - "url": "https://mintlify.com/community" + "label": "Community", + "href": "https://mintlify.com/community" } ] +} ``` ### CTA Button -Customize the call-to-action (CTA) button in the topbar using the `topbarCtaButton` +Customize the call-to-action (CTA) button in the topbar using the `primary` field. -The `topbarCtaButton` field supports the following fields: `name`, `url`, `type`, `style`, and `arrow`. For more information on the options for these fields, see the [mint.json schema](/settings/global#structure). - +The `primary` field supports the following fields: `label`, `href`, `type`. For more information on the options for these fields, see the [docs.json schema](/settings/global#param-navbar). ```json - "topbarCtaButton": { - "name": "Get Started", - "url": "https://mintlify.com/get-started" +"navbar": { + "primary": { + "type": "button", + "label": "Get Started", + "href": "https://mintlify.com/get-started" } +} ``` #### GitHub You can also configure the CTA button to link directly to your GitHub -repository. Use the `topbarCtaButton` field with the `type` set to `github`. +repository. Use the `primary` field with the `type` set to `github`. - ```json - "topbarCtaButton": { +"navbar": { + "primary": { "type": "github", - "url": "https://github.com/mintlify/docs" + "label": "GitHub", + "href": "https://github.com/mintlify/docs" } +} ``` + diff --git a/settings/seo.mdx b/settings/seo.mdx index b81352b91..bd115d08d 100644 --- a/settings/seo.mdx +++ b/settings/seo.mdx @@ -1,6 +1,6 @@ --- title: 'SEO' -description: 'Mintlify automatically generates most meta tags. If you want to customize them, you can set default values in mint.json or change them per page.' +description: 'Mintlify automatically generates most meta tags. If you want to customize them, you can set default values in docs.json or change them per page.' icon: 'magnifying-glass' --- @@ -27,11 +27,13 @@ icon: 'magnifying-glass' ## Default meta tags -You can set default meta tags by adding the `metadata` field to your `mint.json`. +You can set default meta tags by adding the `metadata` field to your `docs.json`. ```json -"metadata": { - "og:image": "link to your default meta tag image" +"seo": { + "metatags": { + "og:image": "link to your default meta tag image" + } } ``` @@ -56,11 +58,11 @@ Meta tags with colons need to be typed with quotes around them when you put them Mintlify automatically generates a `sitemap.xml` file and a `robots.txt` file. Simply add `/sitemap.xml` to the end of your website URL to see your sitemap. We recommend submitting the sitemap to search engines for improved SEO. -Only pages included in your `mint.json` are included by default. To include hidden links, add `seo.indexHiddenPages` to your `mint.json`: +Only pages included in your `docs.json` are included by default. To include hidden links, add `seo.indexing` to your `docs.json`: ```json "seo": { - "indexHiddenPages": true + "indexing": all } ``` @@ -72,7 +74,7 @@ noindex: true --- ``` -You can also specify `noindex` for all pages in your docs by setting the `metadata.robots` field to `"noindex"` in your `mint.json`: +You can also specify `noindex` for all pages in your docs by setting the `metadata.robots` field to `"noindex"` in your `docs.json`: ```json "metadata": { diff --git a/settings/versioning.mdx b/settings/versioning.mdx index bc60a79b1..0737fdbb4 100644 --- a/settings/versioning.mdx +++ b/settings/versioning.mdx @@ -1,4 +1,4 @@ ---- + --- title: "Versioning & Localization" description: "Build separate versions or localizations" icon: "square-chevron-down" @@ -15,19 +15,21 @@ These guides will assume `v1` pages are in a folder named `v1`, `v2` pages are i Add `"versions": ["v2", "v1"]` to your `mint.json` file where `v1` and `v2` are the names of your versions. You can put any number of versions in this array. The first version from the array serves as the default version. If you would like to specify a default version, you can do so like this: - ```json -"versions": [ - { - "name": "version-name", - "default": true - } -] +"global": { + "versions": [ + { + "version": "version-name", + "default": true, + "href": "link-to-version" + } + ] +} ``` The versions dropdown will show your versions in the order you include them in - `mint.json`. + `docs.json`. ### Versioning Groups and Pages @@ -37,13 +39,20 @@ The best way to specify page versions is by adding a version value to a group in You can also specify the version of a single page in the page metadata. Versions on individual pages always take precedence. -```json Groups (mint.json) +```json Groups (docs.json) "navigation": [ - { - "group": "Getting Started", - "version": "v1", - "pages": [...] - } + "tabs": [ + { + "tab": "Docs", + "groups": [ + { + "group": "Getting Started", + "version": "v1", + "pages": [...] + } + ] + } + ] ], ``` @@ -66,46 +75,65 @@ version: "v2" You can hide a tab or anchor based on a version. This is useful if you have links that are only relevant in one version. Importantly, this does **not** apply the version to the pages within that anchor. -In `mint.json`, simply add `version` to your tab or anchor. Tabs and anchors without a specified version are shown in every version. +In `docs.json`, simply add `version` to your tab or anchor. Tabs and anchors without a specified version are shown in every version. ```json Tabs -"tabs": [ - { - "name": "API Reference V1", - "url": "v1/api-reference", - "version": "v1" - }, - { - "name": "API Reference V2", - "url": "v2/api-reference", - "version": "v2" - }, - { - "name": "Migrating from V1 to V2", - "url": "https://mintlify.com/changelog/v2" - }, -], +"navigation": { + "tabs": [ + { + "tab": "API Reference V1", + "versions": [ + { + "version": "v1", + "pages": ["v1/api-reference"] + } + ] + }, + { + "tab": "API Reference V2", + "versions": [ + { + "version": "v2", + "pages": ["v2/api-reference"] + } + ] + }, + { + "tab": "Migrating from V1 to V2", + "versions": [ + { + "version": "v2", + "href": "https://mintlify.com/changelog/v2" + } + ] + } + ] +} ``` ```json Anchors -"anchors": [ - { - "name": "API Reference V1", - "url": "v1/api-reference", - "version": "v1" - }, - { - "name": "API Reference V2", - "url": "v2/api-reference", - "version": "v2" - }, - { - "name": "Migrating from V1 to V2", - "url": "https://mintlify.com/changelog/v2", - "version": "v2" - }, -], +"navigation": { + "global": { + "anchors": [ + { + "anchor": "API Reference V1", + "href": "v1/api-reference", + "version": "v1" + }, + { + "anchor": "API Reference V2", + "href": "v2/api-reference", + "version": "v2" + }, + { + "anchor": "Migrating from V1 to V2", + "href": "https://mintlify.com/changelog/v2", + "version": "v2" + } + ] + } +} ``` @@ -136,7 +164,7 @@ Common errors and how to fix them If you add versions to your docs and the pages disappeared from your navigation, make sure you spelled the version the same as in your `versions` - array in `mint.json`. + array in `docs.json`. @@ -146,28 +174,30 @@ Common errors and how to fix them `"versions"` in your `mint.json` can be leveraged to create different language versions by adding a `locale` value to the version. The first localization from the array serves as the default localization. -We currently support localization in English (`en`), Chinese (`cn`), Spanish (`es`), French (`fr`), Japanese (`jp`), Portuguese (`pt`), and German (`de`). - -```json mint.json example -"versions": [ - { - "name": "English", - "locale": "en", - }, - { - "name": "French", - "locale": "fr", - }, - { - "name": "Spanish", - "locale": "es" - } -] +We currently support localization in English (`en`), Chinese (`cn`), Spanish (`es`), French (`fr`), Japanese (`jp`), Portuguese (`pt`), Portuguese (Brazil) (`pt-BR`), and German (`de`). + +```json docs.json example +"global": { + "languages": [ + { + "language": "en", + "href": "docs/en", + }, + { + "language": "fr", + "href": "docs/fr", + }, + { + "language": "es", + "href": "docs/es", + } + ] +} ``` - The versions dropdown will show your localizations in the order you include - them in the `mint.json`. + The languages dropdown will show your localizations in the order you include + them in the `docs.json`. Once setup, the rest of localization is handled by the versioning setup described above. diff --git a/web-editor.mdx b/web-editor.mdx index 0c945d94b..f25c54d4b 100644 --- a/web-editor.mdx +++ b/web-editor.mdx @@ -259,7 +259,7 @@ We do have a few current limitations in the editor that we're working to resolve You currently cannot live-update your navigation based on added/edited files. You - still have to manually edit renamed, added, and deleted files in your `mint.json` + still have to manually edit renamed, added, and deleted files in your `docs.json`