diff --git a/content/components/code.mdx b/content/components/code.mdx
index d59351bb4..8b3334e2c 100644
--- a/content/components/code.mdx
+++ b/content/components/code.mdx
@@ -54,7 +54,7 @@ class HelloWorld {
## Names
-You can add more text after the programming language to set the name of your code example. The text can be anything as long as its all in one line.
+Add a title after the programming language to set the name of your code example. The text can be anything as long as its all in one line.
```javascript Code Block Example
const hello = "world";
@@ -68,7 +68,7 @@ const hello = "world";
## Line Highlighting
-You can highlight specific lines in your code blocks by adding a special comment after the language identifier. Use curly braces `{}` and specify line numbers or ranges separated by commas.
+Highlight specific lines in your code blocks by adding a special comment after the language identifier. Use curly braces `{}` and specify line numbers or ranges separated by commas.
```javascript Line Highlighting Example {1,3-5}
const greeting = "Hello, World!";
@@ -88,6 +88,110 @@ sayHello();
```
````
+## Expandable
+
+If you have a long code block and `[expandable]` after your title to make it close and expand.
+
+```python library.py [expandable]
+from datetime import datetime, timedelta
+from typing import Dict, List, Optional
+from dataclasses import dataclass
+
+@dataclass
+class Book:
+ title: str
+ author: str
+ isbn: str
+ checked_out: bool = False
+ due_date: Optional[datetime] = None
+
+class Library:
+ def __init__(self):
+ self.books: Dict[str, Book] = {}
+ self.checkouts: Dict[str, List[str]] = {} # patron -> list of ISBNs
+
+ def add_book(self, book: Book) -> None:
+ if book.isbn in self.books:
+ raise ValueError(f"Book with ISBN {book.isbn} already exists")
+ self.books[book.isbn] = book
+
+ def checkout_book(self, isbn: str, patron: str, days: int = 14) -> None:
+ if patron not in self.checkouts:
+ self.checkouts[patron] = []
+
+ book = self.books.get(isbn)
+ if not book:
+ raise ValueError("Book not found")
+
+ if book.checked_out:
+ raise ValueError("Book is already checked out")
+
+ if len(self.checkouts[patron]) >= 3:
+ raise ValueError("Patron has reached checkout limit")
+
+ book.checked_out = True
+ book.due_date = datetime.now() + timedelta(days=days)
+ self.checkouts[patron].append(isbn)
+
+ def return_book(self, isbn: str) -> float:
+ book = self.books.get(isbn)
+ if not book or not book.checked_out:
+ raise ValueError("Book not found or not checked out")
+
+ late_fee = 0.0
+ if datetime.now() > book.due_date:
+ days_late = (datetime.now() - book.due_date).days
+ late_fee = days_late * 0.50
+
+ book.checked_out = False
+ book.due_date = None
+
+ # Remove from patron's checkouts
+ for patron, books in self.checkouts.items():
+ if isbn in books:
+ books.remove(isbn)
+ break
+
+ return late_fee
+
+ def search(self, query: str) -> List[Book]:
+ query = query.lower()
+ return [
+ book for book in self.books.values()
+ if query in book.title.lower() or query in book.author.lower()
+ ]
+
+def main():
+ library = Library()
+
+ # Add some books
+ books = [
+ Book("The Hobbit", "J.R.R. Tolkien", "978-0-261-10295-4"),
+ Book("1984", "George Orwell", "978-0-452-28423-4"),
+ ]
+
+ for book in books:
+ library.add_book(book)
+
+ # Checkout and return example
+ library.checkout_book("978-0-261-10295-4", "patron123")
+ late_fee = library.return_book("978-0-261-10295-4")
+ print(f"Late fee: ${late_fee:.2f}")
+
+if __name__ == "__main__":
+ main()
+```
+
+````md
+```javascript Expandable Example [expandable]
+const greeting = "Hello, World!";
+function sayHello() {
+ console.log(greeting);
+}
+sayHello();
+```
+````
+
## Code Groups
Want to display multiple code examples in one code box? Check out the Code Group docs:
diff --git a/docs.json b/docs.json
index b421920f6..7c608b71c 100644
--- a/docs.json
+++ b/docs.json
@@ -20,13 +20,21 @@
{
"group": "Editing",
"icon": "pen-paintbrush",
+ "pages": ["development", "web-editor"]
+ },
+ "settings/global",
+ {
+ "group": "Navigation",
+ "icon": "map",
"pages": [
- "development",
- "web-editor"
+ "navigation/overview",
+ "navigation/pages",
+ "navigation/divisions",
+ "navigation/versions",
+ "navigation/localization",
+ "navigation/config-upgrade"
]
},
- "settings/global",
- "settings/navigation",
"migration"
]
},
@@ -71,12 +79,11 @@
"settings/custom-domain",
"settings/seo",
"settings/broken-links",
- "settings/versioning",
"settings/add-members",
"settings/authentication",
"settings/github",
"settings/gitlab",
- "settings/ci",
+ "settings/ci",
"settings/preview-deployments"
]
},
@@ -86,10 +93,7 @@
{
"group": "Custom Scripts",
"icon": "code",
- "pages": [
- "advanced/custom/css",
- "advanced/custom/js"
- ]
+ "pages": ["advanced/custom/css", "advanced/custom/js"]
},
{
"group": "Custom Subdirectory",
@@ -133,9 +137,7 @@
{
"group": "Extensions",
"icon": "plug",
- "pages": [
- "advanced/widget/chat"
- ]
+ "pages": ["advanced/widget/chat"]
},
{
"group": "REST API",
@@ -246,9 +248,7 @@
"groups": [
{
"group": "Changelog",
- "pages": [
- "changelog/overview"
- ]
+ "pages": ["changelog/overview"]
}
]
}
@@ -363,4 +363,4 @@
"publicApiKey": "pk_76a6caa274e800f3ceff0b2bc6b9b9d82ab8"
}
}
-}
\ No newline at end of file
+}
diff --git a/navigation/config-upgrade.mdx b/navigation/config-upgrade.mdx
new file mode 100644
index 000000000..47a5865ca
--- /dev/null
+++ b/navigation/config-upgrade.mdx
@@ -0,0 +1,294 @@
+---
+title: "mint.json vs docs.json"
+description: Understanding the differences between mint.json and docs.json
+sidebarTitle: Config Upgrade
+---
+
+## What is the difference between mint.json and docs.json?
+
+In the `mint.json`, the navigation was defined by both the `navigation` field AND the `tabs`, `anchors`, and `versions` fields.
+All these fields were related to each other and had to be mapped together.
+
+In the `docs.json`, the navigation is solely defined by the `navigation` field.
+
+For example, here is a `mint.json` and its equivalent `docs.json`
+
+
+
+```json mint.json
+{
+ "tabs": [{
+ "name": "Components",
+ "url": "content"
+ },
+ {
+ "name": "Integrations",
+ "url": "integrations"
+ }],
+ "navigation": [
+ {
+ "group": "Components",
+ "pages": [
+ "content/components/accordions",
+ "content/components/accordion-groups",
+ "content/components/callouts",
+ ...
+ ]
+ },
+ {
+ "group": "API Components",
+ "pages": [
+ "content/components/params",
+ "content/components/responses",
+ ...
+ ]
+ },
+ {
+ "group": "Analytics",
+ "pages": [
+ "integrations/analytics/overview",
+ "integrations/analytics/amplitude",
+ "integrations/analytics/clearbit",
+ ...
+ ]
+ },
+ {
+ "group": "SDKs",
+ "pages": ["integrations/sdks/providers", "integrations/sdks/clients"]
+ }
+ ]
+}
+```
+
+```json docs.json
+{
+ "navigation": {
+ "tabs": [{
+ "tab": "Components",
+ "groups": [
+ {
+ "group": "Components",
+ "pages": [
+ "content/components/accordions",
+ "content/components/accordion-groups",
+ "content/components/callouts",
+ ...
+ ]
+ },
+ {
+ "group": "API Components",
+ "pages": [
+ "content/components/params",
+ "content/components/responses",
+ ...
+ ]
+ }
+ ]
+ },
+ {
+ "tab": "Integrations",
+ "groups": [
+ {
+ "group": "Analytics",
+ "pages": [
+ "integrations/analytics/overview",
+ "integrations/analytics/amplitude",
+ "integrations/analytics/clearbit",
+ ...
+ ]
+ },
+ {
+ "group": "SDKs",
+ "pages": ["integrations/sdks/providers", "integrations/sdks/clients"]
+ }
+ ]
+ }]
+ }
+}
+```
+
+
+
+In the above `mint.json` example, the navigation is one combined array of groups and the tabs are a separate array.
+The tabs serve to group the groups in the navigation. This isn't very intuitive and it's hard to manage.
+
+In the `docs.json` there is no separation between tabs, groups, and pages - they are integrated into one large recursive structure.
+So it is very obvious how the groups are grouped into tabs.
+
+## What functionality does docs.json unlock?
+
+Tabs and anchors are no longer restricted to a single folder of the same name. Previously with mint.json a tab had to correlate with a folder in the file tree.
+Now you can have a tab with an assortment of files in different folders.
+
+
+
+```json mint.json
+{
+ "tabs": [
+ {
+ "name": "Tab 1",
+ "url": "some-folder"
+ },
+ {
+ "name": "Tab 2",
+ "url": "some-other-folder"
+ }
+ ],
+ "navigation": [
+ {
+ "group": "Group in Tab 1",
+ "pages": [
+ "some-folder/file-1", // Notice how we're restricted to the folder name
+ "some-folder/file-2"
+ ]
+ },
+ {
+ "group": "Group in Tab 2",
+ "pages": ["some-other-folder/file-1", "some-other-folder/file-2"]
+ }
+ ]
+}
+```
+
+```json docs.json
+{
+ "navigation": {
+ "tabs": [
+ {
+ "tab": "Tab 1",
+ "groups": [
+ {
+ "group": "Group 1",
+ "pages": [
+ "some-folder/file-1",
+ "another-folder/file-2"
+ "just-a-file"
+ ]
+ }
+ ]
+ }
+ {
+ "tab": "Tab 2",
+ "groups": [
+ {
+ "group": "Group 2",
+ "pages": [
+ "some-other-folder/file-1",
+ "various-different-folders/file-2",
+ "another-file"
+ ]
+ }
+ ]
+ }
+ ]
+ }
+}
+```
+
+
+
+All the benefits we've been discussing with tabs is applicable for versions, anchors, languages, and dropdowns.
+And you can now arbitrarily mix and nest any combination of these divisions.
+
+This gives a lot of freedom for you to pick and choose the hierarchy you want - either tabs or anchors can be on the highest level.
+
+Here is a complex example that includes all the different types of divisions - versions, anchors, languages, and dropdowns.
+
+Now you can have versions applied to only a specific tab and reference tabs at one layer and then reference them again
+further down the hierarchy.
+
+```json docs.json [expandable]
+{
+ "languages": [
+ {
+ "language": "en",
+ "tabs": [
+ {
+ "tab": "Guides",
+ "pages": ["en/overview", "en/quickstart"]
+ },
+ {
+ "tab": "SDKs",
+ "versions": [
+ {
+ "version": "latest",
+ "anchors": [
+ {
+ "anchor": "Javascript",
+ "pages": [
+ "en/sdk/js/create",
+ "en/sdk/js/edit",
+ "en/sdk/js/delete"
+ ]
+ },
+ {
+ "anchor": "Python",
+ "pages": [
+ "en/sdk/py/create",
+ "en/sdk/py/edit",
+ "en/sdk/py/delete"
+ ]
+ }
+ ]
+ }
+ ]
+ }
+ ]
+ },
+ {
+ "language": "es",
+ "tabs": [
+ {
+ "tab": "Guías",
+ "pages": ["es/overview", "es/quickstart"]
+ },
+ {
+ "tab": "SDKs",
+ "versions": [
+ {
+ "version": "último",
+ "anchors": [
+ {
+ "anchor": "Javascript",
+ "pages": [
+ "es/sdk/js/create",
+ "es/sdk/js/edit",
+ "es/sdk/js/delete"
+ ]
+ },
+ {
+ "anchor": "Python",
+ "pages": [
+ "es/sdk/py/create",
+ "es/sdk/py/edit",
+ "es/sdk/py/delete"
+ ]
+ }
+ ]
+ }
+ ]
+ }
+ ]
+ }
+ ]
+}
+```
+
+## Upgrading from `mint.json` to `docs.json`
+
+
+
+
+ ```bash
+ npm i mintlify@latest -g
+ ```
+
+
+
+
+ ```bash
+ mintlify upgrade
+ ```
+
+
+
diff --git a/navigation/divisions.mdx b/navigation/divisions.mdx
new file mode 100644
index 000000000..41555ba05
--- /dev/null
+++ b/navigation/divisions.mdx
@@ -0,0 +1,158 @@
+---
+title: Tabs and Anchors
+---
+
+## Tabs
+
+Tabs help distinguish between different topics or sections of your
+documentation.
+
+
+ 
+
+ 
+
+
+```json docs.json
+"navigation": {
+ "tabs": [
+ {
+ "tab": "API References",
+ "pages": [
+ "api-reference/get",
+ "api-reference/post",
+ "api-reference/delete"
+ ]
+ },
+ {
+ "tab": "SDKs",
+ "pages": [
+ "sdk/fetch",
+ "sdk/create",
+ "sdk/delete",
+ ]
+ },
+ {
+ "tab": "Blog",
+ "href": "https://external-link.com/blog"
+ }
+ ]
+}
+```
+
+## Anchors
+
+Anchors are another way to section your content.
+
+
+ 
+
+ 
+
+
+The configuration is very similar to the tab configuration.
+
+```json docs.json
+"navigation": {
+ "anchors": [
+ {
+ "anchor": "API References",
+ "pages": [
+ "api-reference/get",
+ "api-reference/post",
+ "api-reference/delete"
+ ]
+ },
+ {
+ "anchor": "SDKs",
+ "pages": [
+ "sdk/fetch",
+ "sdk/create",
+ "sdk/delete",
+ ]
+ },
+ {
+ "anchor": "Blog",
+ "href": "https://external-link.com/blog"
+ }
+ ]
+}
+```
+
+## Nested Hierarchy
+
+You can use both anchors and tabs together - either one can be nested within each other interchangeably.
+
+
+
+```json Top-Level Anchors
+{
+ "navigation": {
+ "anchors": [
+ {
+ "anchor": "Anchor 1",
+ "groups": [
+ {
+ "group": "Group 1",
+ "pages": [
+ "some-folder/file-1",
+ "another-folder/file-2"
+ "just-a-file"
+ ]
+ }
+ ]
+ }
+ {
+ "anchor": "Anchor 2",
+ "groups": [
+ {
+ "group": "Group 2",
+ "pages": [
+ "some-other-folder/file-1",
+ "various-different-folders/file-2",
+ "another-file"
+ ]
+ }
+ ]
+ }
+ ]
+ }
+}
+```
+
+```json Top-Level Tabs
+{
+ "navigation": {
+ "tabs": [
+ {
+ "tab": "Tab 1",
+ "groups": [
+ {
+ "group": "Group 1",
+ "pages": [
+ "some-folder/file-1",
+ "another-folder/file-2"
+ "just-a-file"
+ ]
+ }
+ ]
+ }
+ {
+ "tab": "Tab 2",
+ "groups": [
+ {
+ "group": "Group 2",
+ "pages": [
+ "some-other-folder/file-1",
+ "various-different-folders/file-2",
+ "another-file"
+ ]
+ }
+ ]
+ }
+ ]
+ }
+}
+```
+
+
diff --git a/navigation/localization.mdx b/navigation/localization.mdx
new file mode 100644
index 000000000..260733e9e
--- /dev/null
+++ b/navigation/localization.mdx
@@ -0,0 +1,34 @@
+---
+title: Localization
+---
+
+`"languages"` in your `docs.json` can be leveraged to partition your navigation into different languages.
+
+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
+{
+ "navigation": {
+ "languages": [
+ {
+ "language": "en",
+ "groups": [
+ {
+ "group": "Getting Started",
+ "pages": ["en/overview", "en/quickstart", "en/development"]
+ }
+ ]
+ },
+ {
+ "language": "es",
+ "groups": [
+ {
+ "group": "Getting Started",
+ "pages": ["es/overview", "es/quickstart", "es/development"]
+ }
+ ]
+ }
+ ]
+ }
+}
+```
diff --git a/navigation/overview.mdx b/navigation/overview.mdx
new file mode 100644
index 000000000..65e0da16c
--- /dev/null
+++ b/navigation/overview.mdx
@@ -0,0 +1,26 @@
+---
+title: Overview
+description: "The `navigation` property controls the hierarchy of your documentation."
+---
+
+import ConfigUpgrade from "/snippets/config-upgrade.mdx";
+
+It can contain one of seven properties:
+
+- `pages`
+- `groups`
+- `anchors`
+- `tabs`
+- `dropdowns`
+- `versions`
+- `languages`
+
+These properties all serve the function of partitioning your content and creating a hierarchy so that it's
+easier for your users to navigate through your documentation.
+
+
+
+
+ If you want to learn more about the difference between `mint.json` and
+ `docs.json` checkout our [upgrade guide](/navigation/config-upgrade)
+
diff --git a/navigation/pages.mdx b/navigation/pages.mdx
new file mode 100644
index 000000000..c16569ea1
--- /dev/null
+++ b/navigation/pages.mdx
@@ -0,0 +1,51 @@
+---
+title: Pages and Groups
+---
+
+## Pages
+
+If you don't want any hierarchy, you can just define pages within your `navigation` field.
+
+Each entry of the `pages` array must be a path to a file that exists within your repo.
+Note you do not need to append `.mdx` to the file paths.
+
+```json
+{
+ "navigation": {
+ "pages": [
+ "overview",
+ "quickstart",
+ "advanced/components",
+ "advanced/integrations"
+ ]
+ }
+}
+```
+
+## Groups
+
+Groups allow you to group your pages. Groups can also be nested within each other.
+
+```json
+{
+ "navigation": {
+ "groups": [
+ {
+ "group": "Getting Started",
+ "pages": [
+ "quickstart",
+ {
+ "group": "Editing",
+ "icon": "pen-paintbrush",
+ "pages": ["development", "web-editor"]
+ }
+ ]
+ },
+ {
+ "group": "Writing Content",
+ "pages": ["writing-content/page", "writing-content/text"]
+ }
+ ]
+ }
+}
+```
diff --git a/navigation/versions.mdx b/navigation/versions.mdx
new file mode 100644
index 000000000..85756f189
--- /dev/null
+++ b/navigation/versions.mdx
@@ -0,0 +1,63 @@
+---
+title: Versions
+---
+
+`"versions"` in your `docs.json` can be leveraged to partition your navigation into different versions.
+
+```json docs.json
+{
+ "navigation": {
+ "versions": [
+ {
+ "version": "1.0.0",
+ "groups": [
+ {
+ "group": "Getting Started",
+ "pages": ["v1/overview", "v1/quickstart", "v1/development"]
+ }
+ ]
+ },
+ {
+ "version": 2.0.0",
+ "groups": [
+ {
+ "group": "Getting Started",
+ "pages": ["v2/overview", "v2/quickstart", "v2/development"]
+ }
+ ]
+ }
+ ]
+ }
+}
+```
+
+You can also add versioning to a specific section of your docs by nesting a version.
+
+```json docs.json [expandable]
+{
+ "tabs": [
+ {
+ "tab": "Guides",
+ "pages": ["overview", "quickstart"]
+ },
+ {
+ "tab": "SDKs",
+ "versions": [
+ {
+ "version": "latest",
+ "anchors": [
+ {
+ "anchor": "Javascript",
+ "pages": ["sdk/js/create", "sdk/js/edit", "sdk/js/delete"]
+ },
+ {
+ "anchor": "Python",
+ "pages": ["sdk/py/create", "sdk/py/edit", "sdk/py/delete"]
+ }
+ ]
+ }
+ ]
+ }
+ ]
+}
+```
diff --git a/settings/global.mdx b/settings/global.mdx
index db4e2618c..0473031ba 100644
--- a/settings/global.mdx
+++ b/settings/global.mdx
@@ -4,22 +4,11 @@ description: "Configure your documentation using the `docs.json` file"
icon: "wrench"
---
-Every documentation site requires a `docs.json` file that contains the core configuration settings. This file controls everything from styling and navigation to integrations and analytics.
-
-
- If you're currently using the legacy `mint.json` configuration file, please update the Mintlify CLI:
+import ConfigUpgrade from "/snippets/config-upgrade.mdx";
- ```sh
- npm i -g mintlify@latest
- ```
-
- And run the new `upgrade` command in your docs repository:
- ```sh
- mintlify upgrade
- ```
+Every documentation site requires a `docs.json` file that contains the core configuration settings. This file controls everything from styling and navigation to integrations and analytics.
- You should now be using the new `docs.json` configuration file. Feel free to delete the `mint.json` file from your repository.
-
+
## Properties
@@ -27,14 +16,11 @@ Every documentation site requires a `docs.json` file that contains the core conf
The layout theme of the project. Examples:
- [Maple](https://maple.mintlify.app/),
- [Palm](https://palm.mintlify.app/),
+ [Maple](https://maple.mintlify.app/), [Palm](https://palm.mintlify.app/),
- The name of the project, organization, or product
-
- Minimum length: 1
+ The name of the project, organization, or product Minimum length: 1
@@ -174,6 +160,7 @@ The path to the favicon. Can be a single file or a pair for light and dark mode.
+
@@ -212,16 +199,17 @@ The path to the favicon. Can be a single file or a pair for light and dark mode.
The color in hex format to use in light mode
-
+
Must match pattern: ^#([a-fA-F0-9]{6}|[a-fA-F0-9]{3})$
The color in hex format to use in dark mode
-
+
Must match pattern: ^#([a-fA-F0-9]{6}|[a-fA-F0-9]{3})$
+
@@ -254,6 +242,7 @@ The path to the favicon. Can be a single file or a pair for light and dark mode.
+
@@ -287,7 +276,7 @@ The path to the favicon. Can be a single file or a pair for light and dark mode.
The name of the version
-
+
Minimum length: 1
@@ -306,7 +295,7 @@ The path to the favicon. Can be a single file or a pair for light and dark mode.
The name of the tab
-
+
Minimum length: 1
@@ -325,7 +314,7 @@ The path to the favicon. Can be a single file or a pair for light and dark mode.
The name of the anchor
-
+
Minimum length: 1
@@ -336,12 +325,12 @@ The path to the favicon. Can be a single file or a pair for light and dark mode.
The color in hex format to use in light mode
-
+
Must match pattern: ^#([a-fA-F0-9]{6}|[a-fA-F0-9]{3})$
The color in hex format to use in dark mode
-
+
Must match pattern: ^#([a-fA-F0-9]{6}|[a-fA-F0-9]{3})$
@@ -380,6 +369,7 @@ The path to the favicon. Can be a single file or a pair for light and dark mode.
An array of page paths or groups
+
@@ -403,7 +393,7 @@ The path to the favicon. Can be a single file or a pair for light and dark mode.
The header title of the column
-
+
Minimum length: 1
@@ -412,7 +402,7 @@ The path to the favicon. Can be a single file or a pair for light and dark mode.
The label of the link
-
+
Minimum length: 1
@@ -422,6 +412,7 @@ The path to the favicon. Can be a single file or a pair for light and dark mode.
+
@@ -448,7 +439,7 @@ The path to the favicon. Can be a single file or a pair for light and dark mode.
-
+
Minimum length: 1
@@ -496,6 +487,7 @@ The path to the favicon. Can be a single file or a pair for light and dark mode.
+
@@ -555,7 +547,7 @@ The path to the favicon. Can be a single file or a pair for light and dark mode.
-
+
Minimum length: 6
@@ -564,7 +556,7 @@ The path to the favicon. Can be a single file or a pair for light and dark mode.
-
+
Must match pattern: ^G
@@ -573,7 +565,7 @@ The path to the favicon. Can be a single file or a pair for light and dark mode.
-
+
Must match pattern: ^G
@@ -598,7 +590,7 @@ The path to the favicon. Can be a single file or a pair for light and dark mode.
-
+
Minimum length: 6
@@ -607,7 +599,7 @@ The path to the favicon. Can be a single file or a pair for light and dark mode.
-
+
Minimum length: 2
@@ -644,7 +636,7 @@ The path to the favicon. Can be a single file or a pair for light and dark mode.
-
+
Must match pattern: ^phc\_
@@ -667,6 +659,7 @@ The path to the favicon. Can be a single file or a pair for light and dark mode.
+
@@ -699,13 +692,15 @@ The `docs.json` file is validated against a JSON schema to ensure proper configu
settings. Learn more about the [properties](#properties) or from an
[example](#example-mint-json)
- ## Properties
+## Properties
+
+### Styling
- ### Styling
+{" "}
-
- Name of your company or project. Used for the global title.
-
+
+ Name of your company or project. Used for the global title.
+
Path to logo image or object with path to "light" and "dark" mode logo images,
@@ -726,12 +721,15 @@ The `docs.json` file is validated against a JSON schema to ensure proper configu
-
-
- Path to the favicon image. For example: `/path/to/favicon.svg`
+{" "}
+
+
+ Path to the favicon image. For example: `/path/to/favicon.svg`
+
+
Hex color codes for your global theme
@@ -765,23 +763,28 @@ The `docs.json` file is validated against a JSON schema to ensure proper configu
-
-
- A preset theme configuration that changes the look and feel of the project. A
- theme is a set of default styling configurations. Examples:
- [Venus](https://starter-venus.mintlify.app),
- [Quill](https://starter-quill.mintlify.app),
- [Prism](https://starter-prism.mintlify.app)
-
- The global layout style of the documentation.
-
+{" "}
+
+
+ A preset theme configuration that changes the look and feel of the project. A
+ theme is a set of default styling configurations. Examples:
+ [Venus](https://starter-venus.mintlify.app),
+ [Quill](https://starter-quill.mintlify.app),
+ [Prism](https://starter-prism.mintlify.app)
+
+
+{" "}
+
+
+ The global layout style of the documentation.
+
Set a decorative background.
@@ -791,12 +794,15 @@ The `docs.json` file is validated against a JSON schema to ensure proper configu
The style of the decorative background.
-
-
- Set a custom background image to be displayed behind every page.
+{" "}
+
+
+ Set a custom background image to be displayed behind every page.
+
+
@@ -842,6 +848,7 @@ The `docs.json` file is validated against a JSON schema to ensure proper configu
+
@@ -874,6 +881,7 @@ The `docs.json` file is validated against a JSON schema to ensure proper configu
+
@@ -884,6 +892,7 @@ The `docs.json` file is validated against a JSON schema to ensure proper configu
The styling of the navigation item.
+
@@ -894,6 +903,7 @@ The `docs.json` file is validated against a JSON schema to ensure proper configu
The styling of the navigation item.
+
@@ -904,12 +914,15 @@ The `docs.json` file is validated against a JSON schema to ensure proper configu
The location of the search bar.
-
-
- The style of the rounded edges.
+{" "}
+
+
+ The style of the rounded edges.
+
+
The style of the code block.
@@ -919,9 +932,10 @@ The `docs.json` file is validated against a JSON schema to ensure proper configu
user's system preferences.
+
- ### Structure
+### Structure
An array of groups with all the pages within that group
@@ -944,6 +958,7 @@ The `docs.json` file is validated against a JSON schema to ensure proper configu
+
@@ -959,6 +974,7 @@ The `docs.json` file is validated against a JSON schema to ensure proper configu
+
@@ -986,27 +1002,30 @@ The `docs.json` file is validated against a JSON schema to ensure proper configu
+
Array of version names. Only use this if you want to show different versions
of docs with a dropdown in the navigation bar.
- Versions can be leveraged for localization. You can store translated content
- under a version, and once you specify the `locale` any fixed text in Mintlify,
- such as 'Was this page helpful?', will automatically be translated based on the
- locale. We currently support localization in English, Chinese, Spanish, French,
- Japanese, and Portuguese.
+Versions can be leveraged for localization. You can store translated content
+under a version, and once you specify the `locale` any fixed text in Mintlify,
+such as 'Was this page helpful?', will automatically be translated based on the
+locale. We currently support localization in English, Chinese, Spanish, French,
+Japanese, and Portuguese.
+
+{" "}
-
- Localization auto-translates the UI and fixed assets in the docs, such as "Was
- this page helpful?". You must translate the content of the pages yourself.
-
+
+ Localization auto-translates the UI and fixed assets in the docs, such as "Was
+ this page helpful?". You must translate the content of the pages yourself.
+
- For more information, please refer to our
- [versioning & localization documentation](/settings/versioning).
+For more information, please refer to our
+[versioning & localization documentation](/navigation/versions).
- Example:
+Example:
```json Default
@@ -1042,24 +1061,29 @@ The `docs.json` file is validated against a JSON schema to ensure proper configu
+
An array of the anchors, includes the icon, color, and url.
- {" "}
+{" "}
+
+{" "}
- 
+
- {" "}
+{" "}
- 
+{" "}
+
+
@@ -1095,6 +1119,7 @@ The `docs.json` file is validated against a JSON schema to ensure proper configu
+
@@ -1115,25 +1140,26 @@ The `docs.json` file is validated against a JSON schema to ensure proper configu
+
An array of navigational tabs.
- Example:
+Example:
- ```json
- "tabs": [
- {
- "name": "Writing Content",
- "url": "content"
- },
- {
- "name": "API References",
- "url": "api-playground"
- }
- ]
- ```
+```json
+"tabs": [
+ {
+ "name": "Writing Content",
+ "url": "content"
+ },
+ {
+ "name": "API References",
+ "url": "api-playground"
+ }
+]
+```
@@ -1150,33 +1176,34 @@ The `docs.json` file is validated against a JSON schema to ensure proper configu
+
An object to configure the footer with socials and links.
Example:
- ```json
- "footer": {
- "socials": { "x": "https://x.com/mintlify", "website": "https://mintlify.com" },
- "links": [
- {
- "title": "Column 1",
- "links": [
- { "label": "Column 1 Link 1", "url": "https://mintlify.com" },
- { "label": "Column 1 Link 2", "url": "https://mintlify.com" }
- ]
- },
- {
- "title": "Column 2",
- "links": [
- { "label": "Column 2 Link 1", "url": "https://mintlify.com" },
- { "label": "Column 2 Link 2", "url": "https://mintlify.com" }
- ]
- }
- ]
- }
- ```
+```json
+"footer": {
+ "socials": { "x": "https://x.com/mintlify", "website": "https://mintlify.com" },
+ "links": [
+ {
+ "title": "Column 1",
+ "links": [
+ { "label": "Column 1 Link 1", "url": "https://mintlify.com" },
+ { "label": "Column 1 Link 2", "url": "https://mintlify.com" }
+ ]
+ },
+ {
+ "title": "Column 2",
+ "links": [
+ { "label": "Column 2 Link 1", "url": "https://mintlify.com" },
+ { "label": "Column 2 Link 2", "url": "https://mintlify.com" }
+ ]
+ }
+ ]
+}
+```
@@ -1203,6 +1230,7 @@ The `docs.json` file is validated against a JSON schema to ensure proper configu
+
@@ -1226,6 +1254,7 @@ The `docs.json` file is validated against a JSON schema to ensure proper configu
+
@@ -1236,9 +1265,10 @@ The `docs.json` file is validated against a JSON schema to ensure proper configu
Set the prompt for the search bar. Default is `Search...`
+
- ### API Configurations
+### API Configurations
Configuration for API settings. Learn more about API pages at [API Components](/api-playground).
@@ -1322,13 +1352,14 @@ The `docs.json` file is validated against a JSON schema to ensure proper configu
+
A string or an array of strings of URL(s) or relative path(s) pointing to your
OpenAPI file.
- Examples:
+Examples:
```json Absolute
@@ -1344,9 +1375,10 @@ The `docs.json` file is validated against a JSON schema to ensure proper configu
```
+
- ### Integrations
+### Integrations
Configurations to add third-party integrations (excluding analytics integrations)
@@ -1361,28 +1393,31 @@ The `docs.json` file is validated against a JSON schema to ensure proper configu
-
-
- Configurations to add third-party analytics integrations. See full list of
- supported analytics [here](/integrations/analytics/overview).
- ### Redirects
+{" "}
+
+
+ Configurations to add third-party analytics integrations. See full list of
+ supported analytics [here](/integrations/analytics/overview).
+
+
+### Redirects
An array of paths you want to configure to permanently redirect to another path
- Example:
+Example:
- ```json
- "redirects": [
- {
- "source": "/source/path",
- "destination": "/destination/path"
- }
- ]
- ```
+```json
+"redirects": [
+ {
+ "source": "/source/path",
+ "destination": "/destination/path"
+ }
+]
+```
@@ -1398,31 +1433,33 @@ The `docs.json` file is validated against a JSON schema to ensure proper configu
+
- ### Search Engine Optimization
+### Search Engine Optimization
Settings for Search Engine Optimization.
- Example:
+Example:
- ```json
- "seo": {
- "indexHiddenPages": true
- }
- ```
+```json
+"seo": {
+ "indexHiddenPages": true
+}
+```
Enables indexing pages not included in `navigation`.
+
- ## Example `mint.json`
+## Example `mint.json`
- Click on the following dropdown to view a sample configuration file
+Click on the following dropdown to view a sample configuration file
```json
diff --git a/settings/navigation.mdx b/settings/navigation.mdx
index b5727b718..d84e373aa 100644
--- a/settings/navigation.mdx
+++ b/settings/navigation.mdx
@@ -1,192 +1,237 @@
---
title: "Navigation"
-description: "Organize your docs directory to guide your users to the information they need "
+description: "Organize your docs to guide your users to the information they need"
icon: "map"
---
-## Tabs
+The `navigation` property controls the hierarchy of your documentation.
-Tabs help distinguish between different topics or sections of your
-documentation. They show up above the main sidebar.
+## Pages
-
-
-
-
-
+If you don't want any hierarchy, you can just define pages within your `navigation` field.
-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.
+Each entry of the `pages` array must be a path to a file that exists within your repo.
+Note you do not need to append `.mdx` to the file paths.
```json
-"navigation": {
- "global": {
- "tabs": [
- {
- "tab": "API References",
- "href": "https://your-website.com/api-reference"
- },
- {
- "tab": "Content",
- "href": "https://your-website.com/content"
- },
- {
- "tab": "Blog",
- "href": "https://your-website.com/blog"
- }
+{
+ "navigation": {
+ "pages": [
+ "overview",
+ "quickstart",
+ "advanced/components",
+ "advanced/integrations"
]
}
}
```
-## Anchors
-
-Anchors provide another way to direct users to sections of your documentation,
-or link out to external URLs.
-
-
-
-
-
-
+## Groups
-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).
+Groups allow you to group your pages. Groups can also be nested within each other.
```json
-"navigation": {
- "global": {
- "anchors": [
- {
- "anchor": "API References",
- "icon": "code",
- "href": "https://your-website.com/api-reference"
- },
+{
+ "navigation": {
+ "groups": [
{
- "anchor": "Content",
- "icon": "pencil",
- "href": "https://your-website.com/content"
+ "group": "Getting Started",
+ "pages": [
+ "quickstart",
+ {
+ "group": "Editing",
+ "icon": "pen-paintbrush",
+ "pages": ["development", "web-editor"]
+ }
+ ]
},
{
- "anchor": "Contact us",
- "icon": "envelope",
- "href": "https://mintlify.com/contact-us"
+ "group": "Writing Content",
+ "pages": ["writing-content/page", "writing-content/text"]
}
]
}
}
```
-## Sidebar
+## Tabs
-Organize your navigation by defining the `navigation` property in your
-docs.json, You don't need to include `.mdx` in page names.
+Tabs help distinguish between different topics or sections of your
+documentation.
-
- Once you add a page to your docs directory, you'll need to add the path to
- `docs.json` to add it to the sidebar. Pages do not show up automatically.
-
+
+
+
+
+
-```json Regular Navigation
+```json docs.json
"navigation": {
"tabs": [
{
- "tab": "Docs",
- "groups": [
- {
- "group": "Getting Started",
- "pages": ["quickstart"]
- }
+ "tab": "API References",
+ "pages": [
+ "api-reference/get",
+ "api-reference/post",
+ "api-reference/delete"
+ ]
+ },
+ {
+ "tab": "SDKs",
+ "pages": [
+ "sdk/fetch",
+ "sdk/create",
+ "sdk/delete",
]
+ },
+ {
+ "tab": "Blog",
+ "href": "https://external-link.com/blog"
}
]
}
```
-### Groups
+## Anchors
+
+Anchors are another way to section your content.
+
+
+
+
+
+
+
+The configuration is very similar to the tab configuration.
-Create groups by recursively nesting a group within a group.
-```json Nested Navigation
+```json docs.json
"navigation": {
- "tabs": [
+ "anchors": [
{
- "tab": "Docs",
- "groups": [
- {
- "group": "Getting Started",
- "pages": [
- "quickstart",
- {
- "group": "Nested Reference Pages",
- "pages": ["nested-reference-page"]
- }
- ]
- }
+ "anchor": "API References",
+ "pages": [
+ "api-reference/get",
+ "api-reference/post",
+ "api-reference/delete"
]
+ },
+ {
+ "anchor": "SDKs",
+ "pages": [
+ "sdk/fetch",
+ "sdk/create",
+ "sdk/delete",
+ ]
+ },
+ {
+ "anchor": "Blog",
+ "href": "https://external-link.com/blog"
}
]
}
```
-### Folders
-
-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
-`your-page.mdx`.
+## Nested Hierarchy
-
- You cannot use `api` for the name of a folder unless you nest it inside
- another folder. Mintlify uses Next.js which reserves the top-level `api`
- folder for internal server calls. We recommend using the folder name
- `api-reference` instead.
-
+You can use both anchors and tabs together - either one can be nested within each other interchangeably.
-```json Navigation with Folder
-"navigation": {
- "tabs": [
- {
- "tab": "Docs",
- "groups": [
- {
- "group": "Group Name",
- "pages": ["your-folder/your-page"]
- }
- ]
- }
- ]
+
+```json Top-Level Anchors
+{
+ "navigation": {
+ "anchors": [
+ {
+ "anchor": "Anchor 1",
+ "groups": [
+ {
+ "group": "Group 1",
+ "pages": [
+ "some-folder/file-1",
+ "another-folder/file-2"
+ "just-a-file"
+ ]
+ }
+ ]
+ }
+ {
+ "anchor": "Anchor 2",
+ "groups": [
+ {
+ "group": "Group 2",
+ "pages": [
+ "some-other-folder/file-1",
+ "various-different-folders/file-2",
+ "another-file"
+ ]
+ }
+ ]
+ }
+ ]
+ }
}
```
-```json Nested Navigation
-"navigation": {
- "tabs": [
- {
- "tab": "Docs",
- "groups": [
- {
- "group": "Getting Started",
- "pages": [
- "quickstart",
- {
- "group": "Nested Reference Pages",
- "pages": ["nested-reference-page"]
- }
- ]
- }
- ]
- }
- ]
+```json Top-Level Tabs
+{
+ "navigation": {
+ "tabs": [
+ {
+ "tab": "Tab 1",
+ "groups": [
+ {
+ "group": "Group 1",
+ "pages": [
+ "some-folder/file-1",
+ "another-folder/file-2"
+ "just-a-file"
+ ]
+ }
+ ]
+ }
+ {
+ "tab": "Tab 2",
+ "groups": [
+ {
+ "group": "Group 2",
+ "pages": [
+ "some-other-folder/file-1",
+ "various-different-folders/file-2",
+ "another-file"
+ ]
+ }
+ ]
+ }
+ ]
+ }
}
```
+## Global Links
+
+If you want to use tabs or anchors solely for the purpose of listing external links use the `navigation.global` property.
+
+```json
+"navigation": {
+ "global": {
+ "anchors": [
+ {
+ "anchor": "Slack",
+ "icon": "slack",
+ "href": "https://slack.com
+ },
+ {
+ "anchor": "API Reference",
+ "icon": "code",
+ "href": "https://api-reference.com"
+ }
+ ]
+ }
+}
+```
+
### Hidden Pages
MDX files not included in `docs.json` will not show up in the sidebar but are
@@ -197,7 +242,7 @@ would like to override this behavior, you can set the
[`seo.indexing`](/settings/global#param-indexing) attribute
in your `docs.json` to `navigable`.
-## Topbar
+## Navbar
### Links
@@ -208,6 +253,7 @@ Add links to the topbar with the `links` field in the `docs.json` file.
The `links` field supports the following fields: `label`, `href`.
+
```json
"navbar": {
"links": [
@@ -229,6 +275,7 @@ field.
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
"navbar": {
"primary": {
@@ -256,4 +303,3 @@ repository. Use the `primary` field with the `type` set to `github`.
}
}
```
-
diff --git a/settings/versioning.mdx b/settings/versioning.mdx
deleted file mode 100644
index 5d59e544d..000000000
--- a/settings/versioning.mdx
+++ /dev/null
@@ -1,207 +0,0 @@
----
-title: "Versioning & Localization"
-description: "Build separate versions or localizations"
-icon: "square-chevron-down"
----
-
-Mintlify supports versioning or localization. You can use one or the other, not both.
-
-These guides will assume `v1` pages are in a folder named `v1`, `v2` pages are in a folder named `v2`, and so on. While this method of structuring your files isn't strictly necessary, it's a great way to keep your files organized.
-
-## Versioning
-
-### Setup
-
-Add `"versions": ["v2", "v1"]` to your `docs.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
-"global": {
- "versions": [
- {
- "version": "v1",
- "default": true,
- "href": "pathname-to-v1"
- },
- {
- "version": "v2",
- "href": "pathname-to-v2"
- }
- ]
-}
-```
-
-
- The versions dropdown will show your versions in the order you include them in
- `docs.json`.
-
-
-### Versioning Groups and Pages
-
-The best way to specify page versions is by adding a version value to a group in the navigation. When you specify the version of a group, that version is applied to all pages within that group.
-
-You can also specify the version of a single page in the page metadata. Versions on individual pages always take precedence.
-
-
-```json Groups (docs.json)
-"navigation": [
- "tabs": [
- {
- "tab": "Docs",
- "groups": [
- {
- "group": "Getting Started",
- "version": "v1",
- "pages": [...]
- }
- ]
- }
- ]
-],
-```
-
-```yaml Pages (quickstart.mdx)
----
-title: "Quickstart"
-version: "v2"
----
-```
-
-
-
-
- While it is possible to nest versioned groups within versioned groups, it is
- not recommended. If you do take this approach, the more deeply-nested version
- takes precedence.
-
-
-#### Versioning Tabs and Anchors
-
-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 `docs.json`, simply add `version` to your tab or anchor. Tabs and anchors without a specified version are shown in every version.
-
-
-```json Tabs
-"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
-"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"
- }
- ]
- }
-}
-```
-
-
-
-#### Sharing Between Versions
-
-Not _all_ content has to be hidden though! Any content without a specified version appears in every version so you don't have to duplicate content!
-
-
- When using localization with versioning, each version can have its own set of
- translations. This means you can have different language versions for
- different API versions, giving you full flexibility in managing both versioned
- and localized content.
-
-
-### Troubleshooting
-
-Common errors and how to fix them
-
-
-
- You likely nested a version inside of another. For example, your group had version "v1" but your page had version "v2".
-
- We do not recommend nesting versions inside of each other because it's hard to maintain your docs later.
-
-
-
-
- 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 `docs.json`.
-
-
-
-## Localization
-
-### Setup
-
-`"languages"` in your `docs.json` can be leveraged to create different language versions by adding a `language` value to the version. The first language from the array serves as the default language.
-
-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 languages dropdown will show your languages 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/snippets/config-upgrade.mdx b/snippets/config-upgrade.mdx
new file mode 100644
index 000000000..072e9c151
--- /dev/null
+++ b/snippets/config-upgrade.mdx
@@ -0,0 +1,16 @@
+
+ If you're currently using the legacy `mint.json` configuration file, please update the Mintlify CLI:
+
+```sh
+npm i -g mintlify@latest
+```
+
+And run the new `upgrade` command in your docs repository:
+
+```sh
+mintlify upgrade
+```
+
+This will generate a `docs.json` based off of your `mint.json`. Then, please delete the `mint.json` file from your repository.
+
+
diff --git a/snippets/dean.mdx b/snippets/dean.mdx
deleted file mode 100644
index 0368cb6ad..000000000
--- a/snippets/dean.mdx
+++ /dev/null
@@ -1 +0,0 @@
-Hello Arianna! Welcome to Mintlify!!!
\ No newline at end of file