From a429d2e22a41f207321d942dfe6070089cadfc62 Mon Sep 17 00:00:00 2001
From: "mintlify[bot]" <109931778+mintlify[bot]@users.noreply.github.com>
Date: Tue, 21 Jan 2025 18:44:56 +0000
Subject: [PATCH] Documentation edits made through Mintlify web editor
---
api-playground/overview.mdx | 84 +++-
development.mdx | 130 +++--
mint.json | 20 +-
quickstart.mdx | 223 ++++-----
settings/global.mdx | 928 +++++++++--------------------------
snippets/getting-started.mdx | 107 ++++
6 files changed, 604 insertions(+), 888 deletions(-)
create mode 100644 snippets/getting-started.mdx
diff --git a/api-playground/overview.mdx b/api-playground/overview.mdx
index c222ffedf..bf71c0766 100644
--- a/api-playground/overview.mdx
+++ b/api-playground/overview.mdx
@@ -1,15 +1,85 @@
---
title: 'Interactive Playground'
-description: 'Enable users to interact with your API'
+description: 'Test and explore your API endpoints in real-time'
openapi: 'GET /plants/{id}'
hideApiMarker: true
icon: 'play'
---
-The API playground is an interactive environment to make requests and preview an API endpoint.
+## What is the API Playground?
-
- Autogenerating API pages with OpenAPI will automatically generate API
- playground. Read more about using OpenAPI with Mintlify
- [here](/api-playground/openapi).
-
+The API playground is an interactive environment that lets you test API endpoints directly in your documentation. Instead of copy-pasting code or using external tools, you can make API calls and see responses right on the page.
+
+
+ 
+ 
+
+
+## Key Features
+
+- **Real-time Testing**: Make API requests and see responses instantly
+- **Authentication Support**: Securely test endpoints that require authentication
+- **Parameter Editor**: Easily modify query parameters, headers, and request bodies
+- **Response Viewer**: See formatted API responses with syntax highlighting
+- **Code Snippets**: Get example code in multiple programming languages
+
+## Getting Started
+
+
+
+ Navigate to any API reference page in the documentation to see the interactive playground.
+
+
+
+ Fill in any required parameters, headers, or request body fields in the playground interface.
+
+
+
+ Click the "Send API Request" button to test the endpoint and see the response.
+
+
+
+ The response will appear below, showing the status code, headers, and formatted response body.
+
+
+
+
+ If you've configured your API documentation using OpenAPI (formerly Swagger), the API playground will be automatically generated for each endpoint. Learn more about using OpenAPI with Mintlify [here](/api-playground/openapi).
+
+
+## Example Playground
+
+Here's an example of what the playground looks like in action:
+
+
+ 
+ 
+
+
+The playground includes:
+1. Method selector and endpoint URL
+2. Authentication settings (if required)
+3. Parameter inputs
+4. Request body editor (for POST/PUT requests)
+5. Response viewer
+6. Code snippet generator
+
+## Common Questions
+
+
+
+ If the API endpoint requires authentication, you'll need the appropriate credentials (like an API key) to make successful requests.
+
+
+
+ Currently, parameter values and configurations are not saved between sessions. We recommend keeping track of commonly used test values separately.
+
+
+
+ The playground follows the same rate limits and restrictions as your API. Make sure to check your API's documentation for specific limitations.
+
+
+
+
+ You can customize how the API playground appears in your documentation using global settings. See the [API playground configuration guide](/api-playground/configuration) for more details.
+
\ No newline at end of file
diff --git a/development.mdx b/development.mdx
index 856629aaf..fc60ca263 100644
--- a/development.mdx
+++ b/development.mdx
@@ -1,18 +1,27 @@
---
title: 'Local Development'
-description: 'Preview changes locally to update your docs'
+description: 'Learn how to preview and test your documentation changes locally'
---
-
+## Prerequisites
-**Prerequisite**: Please install Node.js (version 19 or higher) before proceeding.
+Before you begin, make sure you have:
-
+1. Installed Node.js version 19 or higher
+2. Access to a command line terminal
+3. Your documentation files on your local machine
-**Step 1**: Install Mintlify:
+
+ Not sure if you have Node.js installed? Open your terminal and run `node --version`. If you see a version number ≥ 19, you're good to go. If not, [download Node.js here](https://nodejs.org/).
+
-
+## Setting Up Local Development
+
+### Step 1: Install Mintlify CLI
+
+Choose one of these commands to install the Mintlify CLI (Command Line Interface) tool:
+
```bash npm
npm i -g mintlify
```
@@ -24,16 +33,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 Mintlify directly:
```bash npm
@@ -47,35 +49,44 @@ Alternatively, if you do not want to install Mintlify globally you can use a run
```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.
-
+
+ If using Yarn, make sure you have version 2 or higher for the `dlx` command. [Learn more](https://yarnpkg.com/cli/dlx)
+
-A local preview of your documentation will be available at `http://localhost:3000`.
+### Step 2: Start the Development Server
-### Custom Ports
+1. Open your terminal
+2. Navigate to your documentation folder (where `mint.json` is located)
+3. Run the following command:
-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:
+```bash
+mintlify dev
+```
+
+Your documentation will now be available at `http://localhost:3000`. Any changes you make to your documentation files will automatically appear on this local preview.
+
+## Customizing Your Setup
+
+### Using a Different Port
+
+By default, Mintlify runs on port 3000. To use a different port:
```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:
-
-```md
+If your chosen port is already in use, Mintlify will automatically try the next available port:
+```text
Port 3000 is already in use. Trying 3001 instead.
```
-## Mintlify Versions
+### Updating Mintlify
-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:
+Keep your Mintlify CLI up to date to ensure you have the latest features. Update using the same tool you used to install:
-
```bash npm
npm i -g mintlify@latest
```
@@ -87,45 +98,62 @@ Please note that each CLI release is associated with a specific version of Mintl
```bash pnpm
pnpm up --global mintlify
```
-
-## Validating Links
+## Development Tools
-The CLI can assist with validating reference links made in your documentation. To identify any broken links, use the following command:
+### Check for Broken Links
+
+Find and fix broken links in your documentation with this command:
```bash
mintlify broken-links
```
-## Deployment
-
-If the deployment is successful, you should see the following:
-
-
- 
-
+### Code Editor Setup
-## Code Formatting
+For the best development experience, we recommend:
-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. Install the [MDX VSCode extension](https://marketplace.visualstudio.com/items?itemName=unifiedjs.vscode-mdx) for proper syntax highlighting
+2. Use [Prettier](https://marketplace.visualstudio.com/items?itemName=esbenp.prettier-vscode) for consistent formatting
-## Troubleshooting
+## Common Issues and Solutions
-
+
+ If you see an error about the "sharp" module on Mac:
+ 1. Uninstall Mintlify: `npm remove -g mintlify`
+ 2. Update to Node.js v19 or higher
+ 3. Reinstall Mintlify: `npm install -g mintlify`
+
- 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.
- 3. Reinstall mintlify: `npm install -g mintlify`
+
+ If you encounter unexpected issues:
+ 1. Open your terminal
+ 2. Navigate to your home directory: `cd ~`
+ 3. Delete the Mintlify folder: `rm -rf .mintlify`
+ 4. Try running `mintlify dev` again
-
-
- Solution: Go to the root of your device and delete the \~/.mintlify folder. Afterwards, run `mintlify dev` again.
+
+ If your changes aren't appearing:
+ 1. Check that your development server is running
+ 2. Try refreshing your browser
+ 3. Clear your browser cache
+ 4. Restart the development server
+
+## Deployment Status
+
+When your changes are successfully deployed, you'll see this confirmation:
+
+
+
+
+
+Need help? Join our [community](https://mintlify.com/community) or contact [support](mailto:support@mintlify.com).
\ No newline at end of file
diff --git a/mint.json b/mint.json
index 3c1bef202..85ec5462e 100644
--- a/mint.json
+++ b/mint.json
@@ -65,12 +65,16 @@
"icon": "pen-paintbrush",
"pages": [
"development",
- "web-editor"
+ "web-editor",
+ "quickstart"
]
},
"settings/global",
"settings/navigation",
- "migration"
+ "migration",
+ "development",
+ "settings/global",
+ "snippets/getting-started"
]
},
{
@@ -105,7 +109,8 @@
"api-playground/mdx/authentication"
]
},
- "api-playground/troubleshooting"
+ "api-playground/troubleshooting",
+ "api-playground/overview"
]
},
{
@@ -192,11 +197,10 @@
{
"group": "Chat API",
"pages": [
- "advanced/rest-api/chat/create-topic",
- "advanced/rest-api/chat/generate-message"
- ]
- }
-
+ "advanced/rest-api/chat/create-topic",
+ "advanced/rest-api/chat/generate-message"
+ ]
+ }
]
}
]
diff --git a/quickstart.mdx b/quickstart.mdx
index fd4ba0858..5da25fa7d 100644
--- a/quickstart.mdx
+++ b/quickstart.mdx
@@ -15,172 +15,145 @@ icon: "rocket"
/>
-## Getting Started
+## Welcome to Mintlify
-Welcome! Follow the instructions below to learn how to deploy, update and
-supercharge your documentation with Mintlify.
+Build beautiful, modern documentation that your users will love. Get started in three simple steps:
-### Creating the Repository
+1. Create your documentation repository
+2. Set up your content
+3. Deploy to the world
-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.
+Let's walk through each step!
-
-
-
-
- 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.
-
-
- 
-
-
-
-
-
- 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.
+## Step 1: Getting Your Repository Ready
-
-
- 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).
-
+
+ The fastest way to get started is through our [dashboard](https://dashboard.mintlify.com). Just sign in and we'll help you create your first documentation repository with everything configured for you.
-
+
+ If you prefer to set things up manually:
+ 1. Visit our [starter template](https://github.com/mintlify/starter)
+ 2. Click "Use this template" to create your own repository
+ 3. Clone your new repository to your computer
+
+
- Learn more about how to use the web editor on our [guide](/web-editor).
+### Connect with GitHub
-
+
+ This step ensures your documentation automatically updates whenever you make changes.
+
-
-
- Easily customize colors, logos and buttons among other configurations in our `mint.json` file. Start with these basic configurations:
-
- ```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",
- },
- ```
-
- A full list of supported configurations can be found at [global settings](/settings/global).
+1. Go to your [dashboard settings](https://dashboard.mintlify.com/settings)
+2. Look for the GitHub app installation section
+3. Click to install our GitHub app for your repository
-
+Once installed, you'll see a green checkmark next to your repository, confirming the connection is working:
-
+
+ 
+
- Add content with simple MDX files. Initiate your pages with this template:
+## Step 2: Adding Your Content
- ```md
- ---
- title: "Page Title"
- sidebarTitle: "Sidebar title (optional - if different from page title)"
- description: "Subtitle (optional)"
- ---
- ```
+You have two ways to edit your documentation:
- Learn more about adding images, tables, lists, and more using the [MDX syntax](/text). We also offer a [wide array of components](/content/components).
+
+
+ Edit directly in your browser with live previews. Perfect if you want to:
+ - Make quick updates
+ - See changes in real-time
+ - Edit without setting up locally
+ [Learn how to use the web editor →](/web-editor)
-
+
+ Edit files on your computer. Great if you want to:
+ - Work with your favorite code editor
+ - Test changes before publishing
+ - Make bulk updates
- 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).
-
-
- 
-
+ Quick setup:
+ 1. Install our preview tool: `npm i -g mintlify`
+ 2. Run `mintlify dev` in your docs folder
+ 3. Open `localhost:3000` to see changes live
+ [Learn more about local development →](/development)
+
-
+### Customizing Your Docs
- You can easily set up your API references using an OpenAPI document.
+Make the docs your own by updating the `mint.json` configuration file. Here are the essential settings to start with:
- 1. Add your `openapi.yaml` or `openapi.json` file into your docs repository or define the `openapi` field in `mint.json` with a URL.
+```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"
+ }
+}
+```
- ```json
- "openapi": "link-to-your-openapi-file"
- ```
+[See all configuration options →](/settings/global)
- 2. Use our [scraper](/api-playground/openapi/setup#autogenerate-files-recommended) to autogenerate your OpenAPI endpoints files as:
+### Creating Pages
- ```bash
- npx @mintlify/scraping@latest openapi-file
- ```
+Create new pages using simple MDX files. Start each file with this header:
- 3. Finally, include the generated endpoint MDX files to your `mint.json` under `navigation`.
+```mdx
+---
+title: "Your Page Title"
+description: "A brief description of what this page covers"
+---
- 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).
+Your content goes here...
+```
-
+Learn more about:
+- [Writing content with MDX →](/text)
+- [Adding components →](/content/components)
+- [API documentation →](/api-playground/overview)
-
+## Step 3: Publishing Your Docs
- 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).
+### Deploy Your Changes
- We also support integrations with a range of analytics providers. You can find the list of providers [here](/integrations/analytics/overview).
+Whenever you're ready to update your live documentation:
-
-
+1. Commit your changes
+2. Push to your repository
+3. We'll automatically deploy the updates
- 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).
+ If you need help deploying, you can always update manually through our [dashboard](https://dashboard.mintlify.com).
-### Publishing
-
-
+### Add Your Custom Domain
-Integrate your docs into your website by hosting them on a custom domain. This is included in the free plan.
+Want your docs at your own domain (like `docs.yourcompany.com`)?
-Navigate to your [dashboard settings](https://www.dashboard.mintlify.com/settings) to add a custom domain.
+1. Go to your [dashboard settings](https://dashboard.mintlify.com/settings)
+2. Add your custom domain
+3. Update your DNS settings (we'll provide the details)
-
+
+ 
+
-
+## Need Help?
-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) to connect with other users
+- Email us at [support@mintlify.com](mailto:support@mintlify.com)
+- For enterprise needs or white-glove migrations, [contact our sales team](mailto:sales@mintlify.com)
diff --git a/settings/global.mdx b/settings/global.mdx
index 350cb3c18..5fad65902 100644
--- a/settings/global.mdx
+++ b/settings/global.mdx
@@ -1,808 +1,342 @@
---
title: "Global Settings"
-description: "Customize your documentation using the mint.json file"
+description: "Learn how to configure your documentation site with mint.json"
icon: "wrench"
---
-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)
+Every Mintlify site needs a `mint.json` file for core configuration. This guide covers essential settings for getting started and advanced options for customization.
-## Properties
+
+ We recommend starting with the essential configurations below. You can add more advanced options as needed later.
+
-### Styling
+## Essential Configurations ✨
-
- 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,
- and where the logo links to. SVG format is recommended. It does not pixelate
- and the file size is generally smaller.
-
-
-
- Path to the logo in light mode. For example: `/path/to/logo.svg`
-
-
-
- Path to the logo in dark mode. For example: `/path/to/logo.svg`
-
-
-
- Where clicking on the logo links you to
-
-
-
-
-
-
- Path to the favicon image. For example: `/path/to/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
-
-
-
- The primary color for important buttons
-
-
-
- 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
-
-
-
-
-
-
+These are the most important settings to get your docs up and running.
-
- 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)
-
+### Basic Site Info
-
- The global layout style of the documentation.
-
-
-
- Set a decorative background.
-
-
-
- The style of the decorative background.
-
-
-
+
+ The name of your company or project. This appears as the global title.
-
- Set a custom background image to be displayed behind every page.
+Example:
+```json
+"name": "Acme Docs"
+```
-
- Custom fonts. Apply globally or set different fonts for headings and the body
- text.
+
+ Your documentation logo. Can be a single path or separate light/dark mode logos.
Example:
+```json Simple Logo
+{
+ "logo": "/logo.svg"
+}
+```
-```json
-"font": {
- "headings": {
- "family": "Roboto"
- },
- "body": {
- "family": "Oswald"
+```json Light/Dark Logos
+{
+ "logo": {
+ "light": "/logo-light.svg",
+ "dark": "/logo-dark.svg",
+ "href": "https://acme.com" // Optional: where logo links to
}
}
```
-
-
- 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.
-
-
-
- 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.
-
-
-
- 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:
-
-
- ```json Only Dark Mode
- "modeToggle": {
- "default": "dark",
- "isHidden": true
- }
- ```
-
- ```json Only Light Mode
- "modeToggle": {
- "default": "light",
- "isHidden": true
- }
- ```
-
-
-
-
-
-
-
- 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.
-
-
+
+ We recommend SVG format for logos - they look crisp at any size and have smaller file sizes.
+
-
- 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.
+
+ The icon shown in browser tabs.
-
-
- `auto` will automatically switch between light and dark mode based on the
- user's system preferences.
-
-
+Example:
+```json
+"favicon": "/favicon.svg"
+```
-### Structure
+### Navigation 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
-
+ Define the pages and groups shown in your sidebar navigation.
-
+Example:
+```json
+"navigation": [
+ {
+ "group": "Getting Started",
+ "pages": ["introduction", "quickstart"]
+ },
+ {
+ "group": "Guides",
+ "pages": ["guides/installation", "guides/deployment"]
+ }
+]
+```
-
- Array of names and urls of links you want to include in the topbar
-
-
-
- The name of the button.
-
+### Brand Colors
-
- The url once you click on the button. Example: `https://mintlify.com/contact`
-
+
+ Define your brand colors. The primary color is the most important.
-
+Example:
+```json
+"colors": {
+ "primary": "#2563EB",
+ "light": "#3B82F6", // Optional: Used in dark mode
+ "dark": "#1D4ED8" // Optional: Used for buttons
+}
+```
-
-
-
- Link shows a button. GitHub shows the repo information at the url provided
- including the number of GitHub stars.
-
+## Styling ✨
-
- If type is a link: What the button links to. If type is a github: Link to
- the repository to load GitHub information from.
-
+These options help customize the look and feel of your docs.
-
- Text inside the button. Only required if type is a link.
-
+### Theme Presets
-
- The style of the button.
-
+
+ Use a pre-built theme to quickly style your docs:
-
- Whether to display the arrow
-
+- `venus` - Modern and clean ([Preview](https://starter-venus.mintlify.app))
+- `quill` - Classic documentation ([Preview](https://starter-quill.mintlify.app))
+- `prism` - Bold and colorful ([Preview](https://starter-prism.mintlify.app))
-
+Example:
+```json
+"theme": "venus"
+```
-
- 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.
+### Layout Options
-
- 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.
-
+
+ Choose the main navigation layout:
-For more information, please refer to our
-[versioning & localization documentation](/settings/versioning).
+- `topnav` - Navigation bar on top (default)
+- `sidenav` - Navigation on the left side
+- `solidSidenav` - Solid left sidebar
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.
-
-
-
+```json
+"layout": "sidenav"
+```
-
- An array of the anchors, includes the icon, color, and url.
-
-{" "}
-
-
-
-{" "}
-
-
+### Font Customization
-
-
- The name of the anchor label.
+
+ Set custom fonts for headings and body text. Supports [Google Fonts](https://fonts.google.com).
- 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"
-
-
-
+Example:
+```json
+"font": {
+ "headings": {
+ "family": "Roboto",
+ "weight": 600
+ },
+ "body": {
+ "family": "Inter"
+ }
+}
+```
-
- 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
-
+## Navigation Components 🧭
-
- Font Awesome icon.
-
-
-
- One of: "brands", "duotone", "light", "sharp-solid", "solid", or "thin"
-
-
-
-
+### Top Bar
-
- An array of navigational tabs.
+
+ Add links to your top navigation bar.
Example:
-
```json
-"tabs": [
+"topbarLinks": [
{
- "name": "Writing Content",
- "url": "content"
+ "name": "Contact Us",
+ "url": "mailto:support@acme.com"
},
{
- "name": "API References",
- "url": "api-playground"
+ "name": "Blog",
+ "url": "https://acme.com/blog"
}
]
```
-
-
-
- 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.
-
-
-
- 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:
+
+ Add a call-to-action button to the top bar.
+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" }
- ]
- }
- ]
+"topbarCtaButton": {
+ "name": "Get Started",
+ "url": "https://app.acme.com"
}
```
-
-
-
- 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.
+### Versions
- If method is `basic`, the format should be `[usernameName]:[passwordName]`
-
+
+ Show different versions of your docs or add language translations.
-
- 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
-
- `"none"` - every expandable component is closed (default behavior)
-
-
-
+Example for versions:
+```json
+"versions": ["v1.0", "v2.0"]
+```
-
+Example for translations:
+```json
+"versions": [
+ {
+ "name": "English",
+ "locale": "en"
+ },
+ {
+ "name": "Español",
+ "locale": "es"
+ }
+]
+```
-
- 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"
- ```
+## Advanced Features 🚀
- ```json Multiple
- "openapi": ["https://example.com/openapi1.json", "/openapi2.json", "/openapi3.json"]
- ```
+
+### Analytics
-
-
-
-### Integrations
+Add analytics integrations to track documentation usage. See [Analytics Overview](/integrations/analytics/overview).
-
- Configurations to add third-party integrations (excluding analytics integrations)
-
-
-
- Enables Intercom widget on docs site. The value should be your Intercom App ID.
-
+Example:
+```json
+"analytics": {
+ "ga4": {
+ "measurementId": "G-XXXXXXXXXX"
+ }
+}
+```
-
- Enables Frontchat widget on docs site. The value should be your Frontchat App ID.
-
+### Third-Party Tools
-
-
+Add support widgets and other integrations.
-
- Configurations to add third-party analytics integrations. See full list of
- supported analytics [here](/integrations/analytics/overview).
-
+Example:
+```json
+"integrations": {
+ "intercom": "abc123",
+ "frontchat": "xyz789"
+}
+```
+
-### Redirects
+
+### API Settings
-
- An array of paths you want to configure to permanently redirect to another path
+Configure settings for API documentation. Learn more at [API Components](/api-playground).
Example:
-
```json
-"redirects": [
- {
- "source": "/source/path",
- "destination": "/destination/path"
+"api": {
+ "baseUrl": "https://api.acme.com",
+ "auth": {
+ "method": "bearer"
}
-]
+}
```
-
-
- The path that you want to redirect from.
-
- Example: `/source`
-
+### OpenAPI/Swagger
-
- The path that you want to redirect to.
+Import OpenAPI/Swagger specifications.
- Example: `/destination`
-
-
-
-
+Example:
+```json
+"openapi": "/openapi.json"
+```
+
+
### Search Engine Optimization
-
- Settings for Search Engine Optimization.
+Control search engine indexing behavior.
Example:
-
```json
"seo": {
"indexHiddenPages": true
}
```
-
-
- Enables indexing pages not included in `navigation`.
-
-
-
-
-## Example `mint.json`
+### URL Redirects
-Click on the following dropdown to view a sample configuration file
+Set up URL redirects for moved pages.
-
- ```json
+Example:
+```json
+"redirects": [
{
- "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"
+ "source": "/old-page",
+ "destination": "/new-page"
+ }
+]
+```
+
+
+## Example Configuration
+
+Click below to see a complete `mint.json` example with common settings:
+
+
+```json
+{
+ "name": "Acme Docs",
+ "logo": {
+ "light": "/logo/light.svg",
+ "dark": "/logo/dark.svg"
+ },
+ "favicon": "/favicon.svg",
+ "colors": {
+ "primary": "#2563EB",
+ "light": "#3B82F6",
+ "dark": "#1D4ED8"
+ },
+ "topbarLinks": [
+ {
+ "name": "Contact",
+ "url": "mailto:support@acme.com"
+ }
+ ],
+ "topbarCtaButton": {
+ "name": "Get Started",
+ "url": "https://app.acme.com"
+ },
+ "navigation": [
+ {
+ "group": "Getting Started",
+ "pages": ["introduction", "quickstart"]
},
- "integrations": {
- "intercom": "APP_ID",
- "frontchat": "CHAT_ID"
+ {
+ "group": "Guides",
+ "pages": ["guides/installation", "guides/deployment"]
}
+ ],
+ "footerSocials": {
+ "github": "https://github.com/acme",
+ "twitter": "https://twitter.com/acme"
}
- ```
+}
+```
-## More Customization
+## Next Steps
+
+- Learn how to [customize individual pages](/settings/page)
+- Add [custom CSS & JavaScript](/advanced/custom)
+- Set up [authentication](/settings/authentication)
-Learn more about how to further customize your docs with custom CSS and JS in
-[Custom Scripts](https://mintlify.com/docs/advanced/custom/).
+Need 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/snippets/getting-started.mdx b/snippets/getting-started.mdx
new file mode 100644
index 000000000..b39ac7766
--- /dev/null
+++ b/snippets/getting-started.mdx
@@ -0,0 +1,107 @@
+## Welcome to Mintlify 👋
+
+Let's get you started with your documentation in just a few steps.
+
+### What is Mintlify?
+
+Mintlify helps you create beautiful documentation that your users will love. We handle the design, hosting, and tools so you can focus on writing great content.
+
+### Quick Setup Guide
+
+
+
+ Choose one of these options to get your docs repository:
+ - Visit the [dashboard](https://dashboard.mintlify.com) to create one automatically
+ - Clone our [starter template](https://github.com/mintlify/starter)
+
+
+
+ Your docs are just MDX files! Here's what you need to know:
+
+ - Add pages to the `docs` folder
+ - Include them in `mint.json` navigation to show them in the sidebar
+ - Use familiar Markdown syntax with extra features like components
+
+ ```md Example Page
+ ---
+ title: 'Your Page Title'
+ description: 'A short description of the page'
+ ---
+
+ ## Your Content Here
+
+ Write your documentation using Markdown!
+ ```
+
+
+
+ See your changes before publishing:
+
+ ```bash
+ npm i -g mintlify
+ mintlify dev
+ ```
+
+ Your docs will be available at `http://localhost:3000`
+
+
+
+ When you're ready to share your docs:
+
+ 1. Push your changes to your Git repository
+ 2. Connect your repository in the [dashboard](https://dashboard.mintlify.com)
+ 3. Your docs will automatically deploy! 🎉
+
+
+
+### Need More Help?
+
+
+
+ Get help from Mintlify team members and other users
+
+
+ Dive deeper into features and customization
+
+
+
+### Customization Quick Links
+
+
+
+ Update your `mint.json` with your brand's colors and styling:
+ ```json
+ {
+ "name": "Your Company",
+ "logo": "/logo.png",
+ "colors": {
+ "primary": "#0D9373",
+ "light": "#07C983",
+ "dark": "#0D9373"
+ }
+ }
+ ```
+
+
+
+ Make your docs interactive with built-in components:
+ - `` for highlighting content
+ - `` for tutorials
+ - `` for multiple code examples
+ - ``, ``, and `` for callouts
+
+
+
+ Organize your docs in `mint.json`:
+ ```json
+ {
+ "navigation": [
+ {
+ "group": "Getting Started",
+ "pages": ["introduction", "quickstart"]
+ }
+ ]
+ }
+ ```
+
+