diff --git a/development.mdx b/development.mdx
index 856629aaf..a1cf9a43f 100644
--- a/development.mdx
+++ b/development.mdx
@@ -1,18 +1,21 @@
---
title: 'Local Development'
-description: 'Preview changes locally to update your docs'
+description: 'Set up your docs locally to preview changes before updating your site'
---
+ **Before you start**: Make sure you have Node.js version 19 or higher installed. You can download it from the [Node.js website](https://nodejs.org).
+
-**Prerequisite**: Please install Node.js (version 19 or higher) before proceeding.
+## Setting Up Local Development
-
+Get your documentation running locally in three simple steps:
-**Step 1**: Install Mintlify:
+### Step 1: Install the Mintlify CLI
-
+The Mintlify CLI (Command Line Interface) helps you run and test your documentation locally. Install it using one of these commands:
+
```bash npm
npm i -g mintlify
```
@@ -24,16 +27,9 @@ description: 'Preview changes locally to update your docs'
```bash pnpm
pnpm add -g mintlify
```
-
-**Step 2**: Navigate to the docs directory (where the `mint.json` file is located) and execute the following command:
-
-```bash
-mintlify dev
-```
-
-Alternatively, if you do not want to install Mintlify globally you can use a run script available:
+Don't want to install globally? You can run it directly:
```bash npm
@@ -41,41 +37,55 @@ Alternatively, if you do not want to install Mintlify globally you can use a run
```
```bash yarn
- yarn dlx mintlify dev
+ yarn dlx mintlify dev # Requires yarn >2
```
```bash pnpm
pnpm dlx mintlify dev
```
-
-
- Yarn's "dlx" run script requires yarn version >2. See [here](https://yarnpkg.com/cli/dlx) for more information.
-
+### Step 2: Go to Your Docs Folder
+
+Navigate to the folder containing your docs (where your `mint.json` file is located).
+
+### Step 3: Start the Development Server
+
+Run this command to start your local docs:
+
+```bash
+mintlify dev
+```
-A local preview of your documentation will be available at `http://localhost:3000`.
+Once started, you can view your documentation at `http://localhost:3000`. The preview updates automatically when you save changes to your files.
-### Custom Ports
+## Common Tasks
-By default, Mintlify uses port 3000. You can customize the port Mintlify runs on by using the `--port` flag. To run Mintlify on port 3333, for instance, use this command:
+### Using a Different Port
+
+By default, Mintlify runs on port 3000. To use a different port, add the `--port` flag:
```bash
mintlify dev --port 3333
```
-If you attempt to run Mintlify on a port that's already in use, it will use the next available port:
+If the port you specify is already in use, Mintlify will automatically try the next available port.
+
+### Checking for Broken Links
-```md
-Port 3000 is already in use. Trying 3001 instead.
+Keep your documentation reliable by checking for broken links:
+
+```bash
+mintlify broken-links
```
-## Mintlify Versions
+This command scans your docs and reports any broken internal links.
-Please note that each CLI release is associated with a specific version of Mintlify. If your local website doesn't align with the production version, please update the CLI:
+### Updating Mintlify
-
+If your local preview looks different from your deployed site, you might need to update Mintlify. Use one of these commands:
+
```bash npm
npm i -g mintlify@latest
```
@@ -87,45 +97,44 @@ Please note that each CLI release is associated with a specific version of Mintl
```bash pnpm
pnpm up --global mintlify
```
-
-## Validating Links
-
-The CLI can assist with validating reference links made in your documentation. To identify any broken links, use the following command:
+## Editor Setup
-```bash
-mintlify broken-links
-```
+To make editing documentation easier, we recommend installing:
-## Deployment
-
-If the deployment is successful, you should see the following:
-
-
- 
-
-
-## Code Formatting
-
-We suggest using extensions on your IDE to recognize and format MDX. If you're a VSCode user, consider the [MDX VSCode extension](https://marketplace.visualstudio.com/items?itemName=unifiedjs.vscode-mdx) for syntax highlighting, and [Prettier](https://marketplace.visualstudio.com/items?itemName=esbenp.prettier-vscode) for code formatting.
+1. [MDX VS Code Extension](https://marketplace.visualstudio.com/items?itemName=unifiedjs.vscode-mdx) - Adds syntax highlighting for MDX files
+2. [Prettier](https://marketplace.visualstudio.com/items?itemName=esbenp.prettier-vscode) - Helps format your code consistently
## Troubleshooting
-
-
+Here are solutions to common issues you might encounter:
- This may be due to an outdated version of node. Try the following:
- 1. Remove the currently-installed version of mintlify: `npm remove -g mintlify`
- 2. Upgrade to Node v19 or higher.
+
+
+ If you see an error about the "sharp" module not loading for darwin-arm64, follow these steps:
+ 1. Remove mintlify: `npm remove -g mintlify`
+ 2. Update Node.js to version 19 or higher
3. Reinstall mintlify: `npm install -g mintlify`
-
-
- Solution: Go to the root of your device and delete the \~/.mintlify folder. Afterwards, run `mintlify dev` again.
+
+ If you encounter any unexpected errors:
+ 1. Go to your root directory
+ 2. Delete the hidden ~/.mintlify folder
+ 3. Run `mintlify dev` again
+
+
+
+ If your changes aren't appearing in the preview:
+ 1. Check that you're in the correct directory (where mint.json is located)
+ 2. Make sure you've saved your files
+ 3. Try refreshing your browser
+ 4. Restart the development server
+
+
+ Need more help? Join our [community](https://mintlify.com/community) or contact
+ [support@mintlify.com](mailto:support@mintlify.com)
+
\ No newline at end of file
diff --git a/mint.json b/mint.json
index 65c9d33d9..08506b09d 100644
--- a/mint.json
+++ b/mint.json
@@ -70,7 +70,8 @@
},
"settings/global",
"settings/navigation",
- "migration"
+ "migration",
+ "snippets/developer-guide"
]
},
{
diff --git a/quickstart.mdx b/quickstart.mdx
index fd4ba0858..0db15e8d0 100644
--- a/quickstart.mdx
+++ b/quickstart.mdx
@@ -15,172 +15,128 @@ icon: "rocket"
/>
-## Getting Started
+## Welcome to Mintlify! π
-Welcome! Follow the instructions below to learn how to deploy, update and
-supercharge your documentation with Mintlify.
+Let's get you set up with beautiful documentation in three simple steps.
-### Creating the Repository
+### Step 1: Set Up Your Repository
-Mintlify docs are rendered from MDX files and configurations defined in our
-[starter kit](https://github.com/mintlify/starter). We use GitHub to integrate
-your docs with your code, and make source control effortless. Onboard through the [dashboard](https://dashboard.mintlify.com) or clone our [starter kit](https://github.com/mintlify/starter) to get started.
-
-
-
-
-
- Install our GitHub app to ensure that your updates are automatically deployed when you push changes. You can find the installation link in the [dashboard](https://dashboard.mintlify.com/settings), on the Settings page. Upon successful installation, a check mark will appear next to the commit hash of the repository.
+
+
+ Choose one of two ways to get started:
+ 1. Use our [dashboard](https://dashboard.mintlify.com) for the fastest setup
+ 2. Clone our [starter template](https://github.com/mintlify/starter) manually
+
+
+ This lets us automatically update your docs whenever you make changes.
- 
+ 
-
-
-
- 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
- [dashboard](https://dashboard.mintlify.com/settings/deployment/git-settings)
-
- 
- 
-
-
-
-
-
-### Updating the Content
-
-Mintlify enables you to easily customize the style, structure, and content of
-your docs.
+ Find the installation link in your [dashboard settings](https://dashboard.mintlify.com/settings).
+
+
+
+
+ Want your docs to live with your code? You can set up a monorepo! Just put your docs in your code repository and set the path in your [dashboard settings](https://dashboard.mintlify.com/settings/deployment/git-settings).
+
+
+### Step 2: Update Your Content
+
+Choose your preferred way to edit:
+
+
+
+ 1. Install our CLI: `npm i -g mintlify`
+ 2. Clone your docs: `git clone `
+ 3. Preview changes: `mintlify dev`
+
+ [See local development guide β](/development)
+
+
+ Use our web editor for a simple, visual editing experience.
+
+ No coding required!
+
+ [Try the web editor β](/web-editor)
+
+
+
+### Step 3: Make It Yours
-
-
- 1. Install [git](https://git-scm.com/book/en/v2/Getting-Started-Installing-Git).
- 2. Once git is installed, clone your docs repository using `git clone `. If you haven't set it up yet, now would be a good time to do so with these [SSH keys](https://docs.github.com/en/authentication/connecting-to-github-with-ssh/generating-a-new-ssh-key-and-adding-it-to-the-ssh-agent).
- 3. Use your favorite IDE to open the repository.
- 4. Install our Mintlify CLI to preview changes with `npm i -g mintlify`.
-
- Learn more about this in our [local development guide](/development).
-
-
-
-
-
- Learn more about how to use the web editor on our [guide](/web-editor).
-
-
-
-
-
- Easily customize colors, logos and buttons among other configurations in our `mint.json` file. Start with these basic configurations:
+
+ Add your brand colors and logo in `mint.json`:
```json
- "name": "Your Company"
- "logo": {
- "light": "/logo/light.svg",
- "dark": "/logo/dark.svg",
- "href": "https://yourcompany.com"
- },
- "favicon": "/favicon.svg",
- "colors": {
- "primary": "#2AB673",
- "light": "#55D799",
- "dark": "#117866",
- },
+ {
+ "name": "Your Company",
+ "logo": {
+ "light": "/logo/light.svg",
+ "dark": "/logo/dark.svg"
+ },
+ "favicon": "/favicon.svg",
+ "colors": {
+ "primary": "#2AB673",
+ "light": "#55D799",
+ "dark": "#117866"
+ }
+ }
```
- A full list of supported configurations can be found at [global settings](/settings/global).
-
+ [See all styling options β](/settings/global)
-
+
+ Create new pages using simple MDX files:
- Add content with simple MDX files. Initiate your pages with this template:
-
- ```md
+ ```mdx
---
- title: "Page Title"
- sidebarTitle: "Sidebar title (optional - if different from page title)"
- description: "Subtitle (optional)"
+ title: "My New Page"
+ description: "A quick description"
---
- ```
- Learn more about adding images, tables, lists, and more using the [MDX syntax](/text). We also offer a [wide array of components](/content/components).
-
-
-
-
-
- Once ready, commit and push your changes to update your docs site. Here is a [guide](https://docs.github.com/en/get-started/using-git/pushing-commits-to-a-remote-repository#about-git-push) on how to do that. If the GitHub app is unable to successfully deploy your changes, you can manually update your docs through our [dashboard](https://dashboard.mintlify.com).
-
-
- 
-
+ Hello world!
+ ```
+ [Learn MDX basics β](/text)
+ [See available components β](/content/components)
-
-
- 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.
+
+ Have an OpenAPI/Swagger file? We'll help you turn it into beautiful API docs:
```json
- "openapi": "link-to-your-openapi-file"
+ // In mint.json
+ {
+ "openapi": "path/to/openapi.yaml"
+ }
```
- 2. Use our [scraper](/api-playground/openapi/setup#autogenerate-files-recommended) to autogenerate your OpenAPI endpoints files as:
-
- ```bash
- npx @mintlify/scraping@latest openapi-file
- ```
-
- 3. Finally, include the generated endpoint MDX files to your `mint.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).
-
+ [Set up API docs β](/api-playground/openapi/setup)
-
-
- Our in-house analytics give you insights into page views, search analytics, session recordings and more. Access these on your [dashboard](https://dashboard.mintlify.com/analytics).
-
- We also support integrations with a range of analytics providers. You can find the list of providers [here](/integrations/analytics/overview).
+
+ Track how users interact with your docs:
+ 1. Use our built-in analytics on the [dashboard](https://dashboard.mintlify.com/analytics)
+ 2. Or connect your favorite tool like [Google Analytics](/integrations/analytics/google-analytics)
-
- We provide a white-glove migration service as part of our Enterprise plan.
- Interested? You can request it by [contacting us](mailto:sales@mintlify.com).
-
-
-### Publishing
-
-
+## Publishing Your Docs
-Integrate your docs into your website by hosting them on a custom domain. This is included in the free plan.
+Host your docs on your own domain! Go to your [dashboard settings](https://www.dashboard.mintlify.com/settings) to add a custom domain.
-Navigate to your [dashboard settings](https://www.dashboard.mintlify.com/settings) to add a custom domain.
+
+ 
+
-
+## Need Help?
-
+We're here to help you build amazing documentation!
-Congrats! You've set up your Mintlify Docs and it's looking amazing! Need
-support or want to give some feedback? You can join our
-[community](https://mintlify.com/community) or drop us an email at
-[support@mintlify.com](mailto:support@mintlify.com).
+- Join our [community](https://mintlify.com/community)
+- Email us at [support@mintlify.com](mailto:support@mintlify.com)
+- Check out our [Enterprise plan](mailto:sales@mintlify.com) for white-glove migration service
\ No newline at end of file
diff --git a/settings/global.mdx b/settings/global.mdx
index 350cb3c18..1e86ed1cc 100644
--- a/settings/global.mdx
+++ b/settings/global.mdx
@@ -1,808 +1,286 @@
----
-title: "Global Settings"
-description: "Customize your documentation using the mint.json file"
-icon: "wrench"
----
+# Global Settings
-Every Mintlify site needs a `mint.json` file with the core configuration
-settings. Learn more about the [properties](#properties) or from an
-[example](#example-mint-json)
+Your Mintlify site is configured through the `mint.json` file. Think of this as your site's control panel - it's where you customize everything from the look and feel to navigation and integrations.
-## Properties
+Let's break down each section so you can easily configure your docs:
-### Styling
+## Basics
-
- Name of your company or project. Used for the global title.
-
+The bare minimum you need in your `mint.json`:
-
- Path to logo image or object with path to "light" and "dark" mode logo images,
- and where the logo links to. SVG format is recommended. It does not pixelate
- and the file size is generally smaller.
+```json Basic Configuration
+{
+ "name": "Your Company",
+ "logo": {
+ "light": "/logo/light.svg",
+ "dark": "/logo/dark.svg"
+ }
+}
+```
-
-
- Path to the logo in light mode. For example: `/path/to/logo.svg`
-
+## Make It Your Own
-
- Path to the logo in dark mode. For example: `/path/to/logo.svg`
-
+### Colors and Branding π¨
-
- Where clicking on the logo links you to
-
+
+ Your company/project name that shows up in browser tabs and search results.
+
-
+
+ Add your logo! Best to use SVG files - they stay sharp at any size. You can either:
+ - Use one logo for all modes: `"logo": "/logo.svg"`
+ - Have different logos for light/dark mode:
+ ```json
+ "logo": {
+ "light": "/logo-light.svg",
+ "dark": "/logo-dark.svg",
+ "href": "https://yoursite.com" // Optional - where the logo links to
+ }
+ ```
- Path to the favicon image. For example: `/path/to/favicon.svg`
+ The small icon that shows up in browser tabs. Example: `"favicon": "/favicon.svg"`
-
- Hex color codes for your global theme
-
-
-
- The primary color. Used most often for highlighted content, section
- headers, accents, in light mode
-
-
-
- The primary color for dark mode. Used most often for highlighted content,
- section headers, accents, in dark mode
-
+### Theme Colors π
-
- The primary color for important buttons
-
+Customize your site's color scheme:
-
- The color of the background in both light and dark mode
-
-
-
- The hex color code of the background in light mode
-
-
-
- The hex color code of the background in dark mode
-
-
-
-
-
-
-
-
- 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.
-
+```json Theme Example
+{
+ "colors": {
+ "primary": "#0D9373",
+ "light": "#07C983", // Used in dark mode
+ "dark": "#0A7355", // Used for buttons
+ "background": {
+ "light": "#ffffff", // Light mode background
+ "dark": "#000000" // Dark mode background
+ }
+ }
+}
+```
-
- Set a decorative background.
+### Fonts π
-
-
- The style of the decorative background.
-
-
-
+Use custom fonts from Google Fonts or your own hosted fonts:
-
- Set a custom background image to be displayed behind every page.
-
-
-
- Custom fonts. Apply globally or set different fonts for headings and the body
- text.
-Example:
+// OR use different fonts for headings and body text
+{
+ "font": {
+ "headings": {
+ "family": "Roboto",
+ "weight": 600
+ },
+ "body": {
+ "family": "Open Sans"
+ }
+ }
+}
+```
+For custom fonts (not from Google):
```json
-"font": {
- "headings": {
- "family": "Roboto"
- },
- "body": {
- "family": "Oswald"
+{
+ "font": {
+ "headings": {
+ "family": "CustomFont",
+ "url": "https://yourdomain.com/fonts/CustomFont.woff2",
+ "format": "woff2"
+ }
}
}
```
-
-
- The font family name. Custom fonts and all [Google
- Fonts](https://fonts.google.com/) are supported. e.g. "Open Sans",
- "Playfair Display"
-
-
-
- The font weight. Precise values such as `560` are also supported for
- variable fonts. Check under the Styles section for your Google Font for
- the available weights.
-
-
-
- The URL to the font file. Can be used to specify a font that is not from
- Google Fonts.
-
-
-
- The font format. Required if using a custom font source (`url`).
-
-
-
-
-
-
- Customize the dark mode toggle.
+## Navigation
-
-
- Set if you always want to show light or dark mode for new users. When not
- set, we default to the same mode as the user's operating system.
-
+### Sidebar Pages π
-
- Set to true to hide the dark/light mode toggle. You can combine `isHidden` with `default` to force your docs to only use light or dark mode. For example:
+Group your documentation pages into sections:
-
- ```json Only Dark Mode
- "modeToggle": {
- "default": "dark",
- "isHidden": true
- }
- ```
-
- ```json Only Light Mode
- "modeToggle": {
- "default": "light",
- "isHidden": true
+```json Navigation Example
+{
+ "navigation": [
+ {
+ "group": "Getting Started",
+ "pages": ["quickstart", "installation", "features"]
+ },
+ {
+ "group": "Advanced Guides",
+ "pages": [
+ "advanced/configuration",
+ {
+ "group": "Deployment",
+ "pages": ["advanced/deploy/hosting", "advanced/deploy/docker"]
}
- ```
-
-
-
-
-
-
-
- Customize the styling of components within the sidebar.
-
-
-
- The styling of the navigation item.
-
-
-
-
-
- Styling configurations for the topbar.
-
-
-
- The styling of the navigation item.
-
-
-
-
-
- The location options for the search bar.
-
-
-
- The location of the search bar.
-
-
-
-
-
- The style of the rounded edges.
-
-
-
- The style of the code block.
-
-
-
- `auto` will automatically switch between light and dark mode based on the
- user's system preferences.
-
-
-
-
-### Structure
-
-
- An array of groups with all the pages within that group
-
-
-
- The name of the group.
-
-
-
- The relative paths to the markdown files that will serve as pages. Note: groups are recursive, so to add a sub-folder add another group object in the page array.
-
-
-
- The [Fontawesome](https://fontawesome.com/icons) icon for the group. Note: this only applies to sub-folders.
-
-
-
- The type of [Fontawesome](https://fontawesome.com/icons) icon. Must be one of: brands, duotone, light, sharp-solid, solid, thin
-
-
-
-
-
-
- Array of names and urls of links you want to include in the topbar
-
-
-
- The name of the button.
-
-
-
- The url once you click on the button. Example: `https://mintlify.com/contact`
-
-
-
-
-
-
-
-
- Link shows a button. GitHub shows the repo information at the url provided
- including the number of GitHub stars.
-
-
-
- If type is a link: What the button links to. If type is a github: Link to
- the repository to load GitHub information from.
-
-
-
- Text inside the button. Only required if type is a link.
-
-
-
- The style of the button.
-
-
-
- Whether to display the arrow
-
-
-
-
-
-
- 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.
-
-
- 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).
-
-Example:
-
-
- ```json Default
- "versions": ["v1.0", "v1.1"]
- ```
-
- ```json Localization
- "versions": [
- {
- "name": "English",
- "locale": "en",
- },
- {
- "name": "EspaΓ±ol",
- "locale": "es"
- }
- ]
- ```
-
-
-
-
-
- The version name.
-
-
-
- The locale of the version. Supported locales are `en`, `cn`, `es`, `fr`, `jp`, `pt`, `pt-BR`, `de`.
-
-
-
- Whether the version is the default version. Handy for when you have a "latest" and "stable" version and you want to default to the stable version.
-
-
-
-
-
-
- An array of the anchors, includes the icon, color, and url.
-
-{" "}
-
-
-
-{" "}
-
-
-
-
-
- The name of the anchor label.
-
- Example: `Community`
-
-
-
- The [Font Awesome](https://fontawesome.com/search?q=heart) icon used to feature the anchor.
-
- Example: `comments`
-
-
-
- The start of the URL that marks what pages go in the anchor. Generally, this is the name of the folder you put your pages in.
-
-
-
- The hex color of the anchor icon background. Can also be a gradient if you pass an object with the properties `from` and `to` that are each a hex color.
-
-
-
- Used if you want to hide an anchor until the correct docs version is selected.
-
-
-
- Pass `true` if you want to hide the anchor until you directly link someone to docs inside it.
-
-
-
- One of: "brands", "duotone", "light", "sharp-solid", "solid", or "thin"
-
-
-
-
-
-
- Override the default configurations for the top-most anchor. Note: if you have
- tabs configured, this does not apply.
-
-
-
- The name of the top-most anchor
-
-
-
- Font Awesome icon.
-
-
-
- One of: "brands", "duotone", "light", "sharp-solid", "solid", or "thin"
-
-
-
-
+ ]
+ }
+ ]
+}
+```
-
- An array of navigational tabs.
+### Top Navigation Bar π
-Example:
+Add links and a call-to-action button to your top bar:
-```json
-"tabs": [
- {
- "name": "Writing Content",
- "url": "content"
- },
- {
- "name": "API References",
- "url": "api-playground"
+```json Top Bar Example
+{
+ "topbarLinks": [
+ {
+ "name": "Documentation",
+ "url": "https://docs.yoursite.com"
+ }
+ ],
+ "topbarCtaButton": {
+ "name": "Get Started",
+ "url": "https://yoursite.com/start"
}
-]
+}
```
-
-
- The name of the tab label.
-
-
-
- The start of the URL that marks what pages go in the tab. Generally, this
- is the name of the folder you put your pages in.
-
+### Anchors and Tabs βοΈ
-
- Pass `true` if you want to hide the tab until you directly link someone to docs inside it.
-
-
-
-
-
-
- An object to configure the footer with socials and links.
- Example:
+Use anchors for major sections and tabs for different content types:
```json
-"footer": {
- "socials": { "x": "https://x.com/mintlify", "website": "https://mintlify.com" },
- "links": [
+{
+ "anchors": [
{
- "title": "Column 1",
- "links": [
- { "label": "Column 1 Link 1", "url": "https://mintlify.com" },
- { "label": "Column 1 Link 2", "url": "https://mintlify.com" }
- ]
+ "name": "API Reference",
+ "icon": "code",
+ "url": "api"
+ }
+ ],
+ "tabs": [
+ {
+ "name": "Guides",
+ "url": "guides"
},
{
- "title": "Column 2",
- "links": [
- { "label": "Column 2 Link 1", "url": "https://mintlify.com" },
- { "label": "Column 2 Link 2", "url": "https://mintlify.com" }
- ]
+ "name": "API",
+ "url": "api"
}
]
}
```
-
-
- One of the following values `website`, `facebook`, `x`, `youtube`, `discord`, `slack`, `github`, `linkedin`, `instagram`, `hacker-news`, `medium`, `telegram`, `twitter`
-
- Example: `x`
-
-
-
- The URL to the social platform.
-
- Example: `https://x.com/mintlify`
-
-
-
-
-
-
- Title of the column
-
-
-
- The link items in the column. External urls that starts with `https://` or `http://` will be opened in new tab.
-
-
-
-
-
-
- Configurations to enable feedback buttons
-
-
-
- Enables a rating system for users to indicate whether the page has been helpful
-
-
-
- Enables a button to allow users to suggest edits via pull requests for public repositories.
-
-
- If your docs repo is private, `suggestEdit` will not work.
-
-
-
-
- Enables a button to allow users to raise an issue about the documentation
-
-
-
-
-
-
- Configurations to change the search prompt
-
-
-
- Set the prompt for the search bar. Default is `Search...`
-
-
-
-
-### API Configurations
-
-
- Configuration for API settings. Learn more about API pages at [API Components](/api-playground).
-
-
-
- The base url for all API endpoints. If `baseUrl` is an array, it will enable for multiple base url
- options that the user can toggle.
-
-
-
-
-
- The authentication strategy used for all API endpoints.
-
-
-
- The name of the authentication parameter used in the API playground.
-
- If method is `basic`, the format should be `[usernameName]:[passwordName]`
-
-
-
- The default value that's designed to be a prefix for the authentication input field.
-
- E.g. If an `inputPrefix` of `AuthKey` would inherit the default input result of the authentication field as `AuthKey`.
-
-
-
-
-
- Configurations for the API playground
-
-
-
- Whether the playground is showing, hidden, or only displaying the endpoint with no added user interactivity `simple`
-
- Learn more at the [playground guides](/api-playground)
-
-
-
- By default, API playground requests are proxied by Mintlify. This setting can be used to disable this behavior.
-
- Required for select request types, such as file uploads.
-
-
-
-
-
- Configurations for API requests
-
-
-
- Configurations for the auto-generated API request examples
-
-
-
- An array of strings that determine the order of the languages of the auto-generated request examples. You can either define custom languages utilizing [x-codeSamples](/api-playground/openapi/advanced-features#x-codesamples) or use our default languages which include `bash`, `python`, `javascript`, `php`, `go`, `java`
-
-
-
-
-
-
-
- Configurations for the param fields in the API Playground
-
-
-
- The default expanded state of expandable options in the API playground.
-
- `"all"` - every expandable component is expanded
-
- `"topLevel"` - every top-level expandable component is expanded
-
- `"topLevelOneOfs"` - every top-level `oneOf` type is expanded
+## Integrations
- `"none"` - every expandable component is closed (default behavior)
-
-
-
+### Analytics π
-
-
-
-
- A string or an array of strings of URL(s) or relative path(s) pointing to your
- OpenAPI file.
-
-Examples:
-
-
- ```json Absolute
- "openapi": "https://example.com/openapi.json"
- ```
-
- ```json Relative
- "openapi": "/openapi.json"
- ```
-
- ```json Multiple
- "openapi": ["https://example.com/openapi1.json", "/openapi2.json", "/openapi3.json"]
- ```
-
-
-
-
-### Integrations
-
-
- Configurations to add third-party integrations (excluding analytics integrations)
-
-
-
- Enables Intercom widget on docs site. The value should be your Intercom App ID.
-
-
-
- Enables Frontchat widget on docs site. The value should be your Frontchat App ID.
-
-
-
-
+Add analytics tools with a few lines:
-
- 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:
-
-```json
-"redirects": [
- {
- "source": "/source/path",
- "destination": "/destination/path"
+```json Analytics Example
+{
+ "analytics": {
+ "ga4": {
+ "measurementId": "G-XXXXXXXX"
+ },
+ "hotjar": {
+ "hjid": "xxxxx"
+ }
}
-]
+}
```
-
-
- The path that you want to redirect from.
-
- Example: `/source`
-
-
-
- The path that you want to redirect to.
+
+ See our [analytics guide](/integrations/analytics/overview) for all supported platforms.
+
- Example: `/destination`
-
+### API Documentation π
-
-
+If you're documenting an API, configure it like this:
-### Search Engine Optimization
+```json API Configuration
+{
+ "api": {
+ "baseUrl": "https://api.yoursite.com",
+ "auth": {
+ "method": "bearer"
+ }
+ }
+}
+```
-
- Settings for Search Engine Optimization.
+### User Feedback π¬
-Example:
+Enable user feedback features:
```json
-"seo": {
- "indexHiddenPages": true
+{
+ "feedback": {
+ "thumbsRating": true, // Shows ππ rating
+ "suggestEdit": true, // Shows "Edit this page" button
+ "raiseIssue": true // Shows "Report an issue" button
+ }
}
```
-
-
- Enables indexing pages not included in `navigation`.
-
-
-
-
-## Example `mint.json`
+## Example Configuration
-Click on the following dropdown to view a sample configuration file
+Here's a complete example bringing it all together:
-
- ```json
- {
- "name": "Mintlify",
- "logo": {
- "light": "/logo/light.svg",
- "dark": "/logo/dark.svg"
- },
- "favicon": "/favicon.svg",
- "colors": {
- "primary": "#16A34A",
- "light": "#4ADE80",
- "dark": "#166534"
- },
- "topbarLinks": [
- {
- "name": "Contact Us",
- "url": "mailto:support@mintlify.com"
- }
- ],
- "topbarCtaButton": {
- "name": "Get Started",
- "url": "https://mintlify.com/start"
- },
- "anchors": [
- {
- "name": "API Components",
- "icon": "rectangle-terminal",
- "color": "#f59f0b",
- "url": "api-components"
- },
- {
- "name": "Community",
- "icon": "comments",
- "color": "#2564eb",
- "url": "https://mintlify.com/community"
- }
- ],
- "navigation": [
- {
- "group": "Getting Started",
- "pages": ["introduction", "quickstart"]
- },
- {
- "group": "API Components",
- "pages": ["api-playground/overview", "api-playground/configuration"]
- },
- {
- "group": "Settings",
- "pages": ["settings/global", "settings/page"]
- },
- {
- "group": "Analytics",
- "pages": ["analytics/posthog"]
- }
- ],
- "footerSocials": {
- "github": "https://github.com/mintlify",
- "slack": "https://mintlify.com/community",
- "x": "https://x.com/mintlify"
- },
- "integrations": {
- "intercom": "APP_ID",
- "frontchat": "CHAT_ID"
+
+```json
+{
+ "name": "Your Company",
+ "logo": {
+ "light": "/logo/light.svg",
+ "dark": "/logo/dark.svg"
+ },
+ "favicon": "/favicon.svg",
+ "colors": {
+ "primary": "#0D9373",
+ "light": "#07C983",
+ "dark": "#0A7355"
+ },
+ "topbarLinks": [
+ {
+ "name": "Documentation",
+ "url": "/docs"
+ }
+ ],
+ "topbarCtaButton": {
+ "name": "Get Started",
+ "url": "/start"
+ },
+ "anchors": [
+ {
+ "name": "API Reference",
+ "icon": "code",
+ "url": "api"
+ }
+ ],
+ "navigation": [
+ {
+ "group": "Getting Started",
+ "pages": ["quickstart", "installation"]
+ }
+ ],
+ "feedback": {
+ "thumbsRating": true,
+ "suggestEdit": true
+ },
+ "analytics": {
+ "ga4": {
+ "measurementId": "G-XXXXXXXX"
}
}
- ```
+}
+```
-## More Customization
+
+ Start small! You don't need to configure everything at once. Begin with the basics (name and logo) and add more features as you need them.
+
+
+## Need More Help?
-Learn more about how to further customize your docs with custom CSS and JS in
-[Custom Scripts](https://mintlify.com/docs/advanced/custom/).
+
+ Connect with the Mintlify team and other developers. We're here to help!
+
\ No newline at end of file
diff --git a/settings/navigation.mdx b/settings/navigation.mdx
index ec1ab6e76..aaa6b116e 100644
--- a/settings/navigation.mdx
+++ b/settings/navigation.mdx
@@ -1,238 +1,198 @@
---
title: "Navigation"
-description: "Organize your docs directory to guide your users to the information they need "
+description: "Learn how to organize your documentation into an easy-to-navigate structure"
icon: "map"
---
-## Tabs
+## Navigation Basics
-Tabs help distinguish between different topics or sections of your
-documentation. They show up above the main sidebar.
+Your documentation's navigation structure is defined in the `mint.json` file. We'll walk through each element of navigation, from top to bottom:
+
+
+
+ 1. Make sure you have a `mint.json` file in your docs folder
+ 2. Prepare your content files (`.mdx` files) that you want to include in the navigation
+ 3. Think about how you want to organize your content into sections
+
+
+
+ To add pages to your navigation, update the `navigation` property in your `mint.json` file:
+
+ ```json
+ "navigation": [
+ {
+ "group": "Getting Started",
+ "pages": ["quickstart", "development"]
+ }
+ ]
+ ```
+
+
+ You don't need to include the `.mdx` extension when listing pages.
+
+
+
+
+## Navigation Components
+
+Your docs can use three main navigation components:
+
+### 1. Tabs
+
+Tabs appear at the very top of your docs and help separate major sections.
-
-Configure tabs with the `tabs` field of the `mint.json` file. The `url` 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": "Guides",
+ "url": "guides"
},
{
- "name": "Blog",
- "url": "https://your-website.com/blog"
+ "name": "API Reference",
+ "url": "api"
}
]
```
-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"
-}
-```
+
+ Tabs work best for separating different types of content, like guides vs API reference.
+
-## Anchors
+### 2. Anchors
-Anchors provide another way to direct users to sections of your documentation,
-or link out to external URLs.
+Anchors appear below tabs and can link to internal sections or external resources.
-
-Configure anchors with the `anchors` field of the `mint.json` file. The `url`
-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",
+ "name": "API Reference",
"icon": "code",
- "url": "api-references"
- },
- {
- "name": "Content",
- "icon": "pencil",
- "url": "content"
+ "url": "api-reference"
},
{
- "name": "Contact us",
- "icon": "envelope",
- "url": "https://mintlify.com/contact-us"
+ "name": "Community",
+ "icon": "people-group",
+ "url": "https://mintlify.com/community"
}
]
```
-To configure the default `Documentation` top anchor, add the `topAnchor` field
-to your `mint.json`.
+### 3. Sidebar Navigation
+
+The sidebar displays your main content structure. Here are different ways to organize it:
+
+
+
+ Basic grouping of pages under a section:
+
+ ```json
+ "navigation": [
+ {
+ "group": "Getting Started",
+ "pages": ["quickstart", "installation"]
+ }
+ ]
+ ```
+
+
+
+ Groups within groups for more complex hierarchies:
+
+ ```json
+ "navigation": [
+ {
+ "group": "Getting Started",
+ "pages": [
+ "quickstart",
+ {
+ "group": "Advanced Setup",
+ "pages": ["configuration", "customization"]
+ }
+ ]
+ }
+ ]
+ ```
+
+
+
+ For organizing files in subdirectories:
+
+ ```json
+ "navigation": [
+ {
+ "group": "Guides",
+ "pages": ["guides/getting-started", "guides/advanced"]
+ }
+ ]
+ ```
+
+
+ The folder name `api` is reserved. Use `api-reference` instead for API documentation.
+
+
+
+
+## Top Navigation Bar
+
+The top navigation bar can include links and a call-to-action button.
+
+### Adding Links
+
+Add links to the top bar using `topbarLinks`:
```json
-"topAnchor": {
- "name": "Home",
- "icon": "building"
-}
-```
-
-## 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)
-
-
- 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.
-
-
-```json Regular Navigation
-"navigation": [
- {
- "group": "Getting Started",
- "pages": ["quickstart"]
- }
-]
-```
-
-### Groups
-
-Create groups by recursively nesting a group within a group.
-
-```json Nested Navigation
-"navigation": [
- {
- "group": "Getting Started",
- "pages": [
- "quickstart",
- {
- "group": "Nested Reference Pages",
- "pages": ["nested-reference-page"]
- }
- ]
- }
-]
-```
-
-### Folders
-
-Simply put your MDX files in folders and update the paths in `mint.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`.
-
-
- 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.
-
-
-
- ```json Navigation With Folder
- "navigation": [
- {
- "group": "Group Name",
- "pages": ["your-folder/your-page"]
- }
- ]
- ```
-
-```json Nested Navigation
-"navigation": [
+"topbarLinks": [
{
- "group": "Getting Started",
- "pages": [
- "quickstart",
- {
- "group": "Nested Reference Pages",
- "pages": ["nested-reference-page"]
- }
- ]
+ "name": "Documentation",
+ "url": "https://mintlify.com/docs"
}
]
```
-
-
-### Hidden Pages
-
-MDX files not included in `mint.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`.
+### Adding a CTA Button
-## Topbar
-
-### Links
-
-Add links to the topbar with the `topbarLinks` field in the `mint.json` file.
-
-
- 
-
-
-The `topbarLinks` field supports the following fields: `name`, `url`.
+Add a prominent button using `topbarCtaButton`:
```json
- "topbarLinks": [
- {
- "name": "Community",
- "url": "https://mintlify.com/community"
- }
- ]
+"topbarCtaButton": {
+ "name": "Get Started",
+ "url": "https://mintlify.com/start"
+}
```
-### CTA Button
-
-Customize the call-to-action (CTA) button in the topbar using the `topbarCtaButton`
-field.
+
+ You can also link to your GitHub repository by setting `"type": "github"`:
-
- 
-
-
-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).
-
-```json
+ ```json
"topbarCtaButton": {
- "name": "Get Started",
- "url": "https://mintlify.com/get-started"
+ "type": "github",
+ "url": "https://github.com/mintlify/docs"
}
-```
+ ```
+
-#### GitHub
+## Hidden Pages
-You can also configure the CTA button to link directly to your GitHub
-repository. Use the `topbarCtaButton` field with the `type` set to `github`.
+If you don't add a page to your navigation in `mint.json`, it becomes a hidden page. Hidden pages:
-
- 
-
+- Won't appear in the sidebar
+- Are still accessible via direct links
+- Aren't included in search results by default
+
+To include hidden pages in search, add this to your `mint.json`:
```json
- "topbarCtaButton": {
- "type": "github",
- "url": "https://github.com/mintlify/docs"
- }
+"seo": {
+ "indexHiddenPages": true
+}
```
diff --git a/snippets/developer-guide.mdx b/snippets/developer-guide.mdx
new file mode 100644
index 000000000..251edeb85
--- /dev/null
+++ b/snippets/developer-guide.mdx
@@ -0,0 +1,111 @@
+# Developer Guide
+
+This guide explains key concepts you'll encounter while using Mintlify. You can import this guide into any page where technical concepts need explanation.
+
+## Key Concepts
+
+### What is MDX?
+
+MDX is like Markdown with superpowers. If you're familiar with writing in Markdown (using `#` for headings, `*` for bullet points), MDX lets you do all that plus:
+
+- Use React components right in your documentation
+- Import and reuse content across pages
+- Add interactive elements like tabs and accordions
+
+```md Example MDX
+# My Page Title
+
+This is regular markdown text.
+
+
+ This is a Mintlify component inside markdown!
+
+```
+
+### Components
+
+Components are pre-built elements you can use to make your docs more interactive and visually appealing. Think of them like building blocks - you just need to add them to your page and customize the content.
+
+
+```md Component Example
+
+ Start building your docs site with Mintlify.
+
+```
+
+```md Result
+
+ Start building your docs site with Mintlify.
+
+```
+
+
+### File Structure
+
+Your documentation is organized into:
+
+- **Pages**: Individual `.mdx` files that contain your content
+- **Navigation**: Defined in `mint.json` to organize your pages into a sidebar
+- **Snippets**: Reusable content pieces stored in the `snippets/` folder
+
+```
+your-docs/
+βββ mint.json # Main configuration file
+βββ introduction.mdx
+βββ quickstart.mdx
+βββ snippets/ # Folder for reusable content
+ βββ example.mdx
+```
+
+### Configuration Basics
+
+The `mint.json` file is your control center. Here's a minimal example:
+
+```json
+{
+ "name": "Your Project",
+ "logo": {
+ "light": "/logo/light.svg",
+ "dark": "/logo/dark.svg"
+ },
+ "navigation": [
+ {
+ "group": "Getting Started",
+ "pages": ["introduction", "quickstart"]
+ }
+ ]
+}
+```
+
+### Common Terms
+
+
+ The information between `---` at the start of each page that defines properties like title and description.
+
+```yaml
+---
+title: "My Page"
+description: "A great page about my product"
+---
+```
+
+
+
+ Ready-to-use elements like ``, ``, or `` that add functionality to your docs.
+
+
+
+ Content you can import and reuse across multiple pages, stored in the `snippets/` folder.
+
+
+### Getting Help
+
+If you run into issues:
+
+1. Check the [troubleshooting guide](/development#troubleshooting)
+2. Join our [community](https://mintlify.com/community)
+3. Contact [support@mintlify.com](mailto:support@mintlify.com)
+
+
+ Remember: You don't need to be a developer to create great documentation! Mintlify's components and MDX make it easy to create professional-looking docs without coding experience.
+
\ No newline at end of file