From 8fd860fb326945eab1fa0534f808b73c0b07cd0d Mon Sep 17 00:00:00 2001
From: "mintlify[bot]" <109931778+mintlify[bot]@users.noreply.github.com>
Date: Thu, 16 Jan 2025 04:49:12 +0000
Subject: [PATCH] Documentation edits made through Mintlify web editor
---
api-playground/overview.mdx | 55 ++-
development.mdx | 174 ++++---
mint.json | 11 +-
quickstart.mdx | 250 +++++-----
settings/global.mdx | 932 ++++++++---------------------------
snippets/getting-started.mdx | 113 +++++
6 files changed, 604 insertions(+), 931 deletions(-)
create mode 100644 snippets/getting-started.mdx
diff --git a/api-playground/overview.mdx b/api-playground/overview.mdx
index c222ffedf..64ad5431e 100644
--- a/api-playground/overview.mdx
+++ b/api-playground/overview.mdx
@@ -6,10 +6,57 @@ hideApiMarker: true
icon: 'play'
---
-The API playground is an interactive environment to make requests and preview an API endpoint.
+## What is the API Playground?
+
+The API playground is an interactive environment that lets users test your API endpoints directly from your documentation. Think of it as a built-in API testing tool where users can:
+
+- Make real API requests
+- See exactly how the API behaves
+- Test different parameters and inputs
+- View formatted responses
+
+
+ 
+
+
+## Key Benefits
+
+
+
+ Users can learn your API hands-on instead of just reading about it
+
+
+ Test endpoints instantly without setting up a separate API client
+
+
+ See actual API responses with your real data
+
+
+ Understand how errors work by triggering them safely
+
+
+
+## Getting Started
+
+The easiest way to add API playground to your docs is by using OpenAPI (formerly known as Swagger). When you use OpenAPI:
+
+1. The playground is automatically generated for each endpoint
+2. All parameters and response formats are pre-configured
+3. Authentication is handled automatically
- Autogenerating API pages with OpenAPI will automatically generate API
- playground. Read more about using OpenAPI with Mintlify
- [here](/api-playground/openapi).
+ Want to add API playground using OpenAPI? Check out our [OpenAPI setup guide](/api-playground/openapi) for step-by-step instructions.
+
+Don't have an OpenAPI specification? No problem! You can also set up the playground manually for each endpoint. We'll walk you through that in our [manual configuration guide](/api-playground/mdx).
+
+## Example
+
+Here's an example of what an API playground looks like when set up. Try making a request below:
+
+
+This is a live API playground example. Feel free to:
+- Change the parameters
+- Click "Send API Request"
+- See the actual response
+
\ No newline at end of file
diff --git a/development.mdx b/development.mdx
index 856629aaf..9dd2abee4 100644
--- a/development.mdx
+++ b/development.mdx
@@ -1,78 +1,93 @@
---
title: 'Local Development'
-description: 'Preview changes locally to update your docs'
+description: 'Set up and preview your documentation locally'
---
-**Prerequisite**: Please install Node.js (version 19 or higher) before proceeding.
-
+## Before You Start
+**Prerequisites**:
+- Install Node.js version 19 or higher ([download here](https://nodejs.org/en))
+- Basic familiarity with command line/terminal
-**Step 1**: Install Mintlify:
-
-
+## Installation and Setup
- ```bash npm
- npm i -g mintlify
- ```
+
+
+ Choose any of the following package managers to install Mintlify globally on your machine:
- ```bash yarn
- yarn global add mintlify
- ```
+
- ```bash pnpm
- pnpm add -g mintlify
- ```
+ ```bash npm
+ npm i -g mintlify
+ ```
-
+ ```bash yarn
+ yarn global add mintlify
+ ```
-**Step 2**: Navigate to the docs directory (where the `mint.json` file is located) and execute the following command:
+ ```bash pnpm
+ pnpm add -g mintlify
+ ```
-```bash
-mintlify dev
-```
+
+
-Alternatively, if you do not want to install Mintlify globally you can use a run script available:
+
+ Navigate to your docs folder (where `mint.json` is located) and run:
-
- ```bash npm
- npx mintlify dev
- ```
+ ```bash
+ mintlify dev
+ ```
- ```bash yarn
- yarn dlx mintlify dev
- ```
+ The preview will be available at `http://localhost:3000`.
- ```bash pnpm
- pnpm dlx mintlify dev
- ```
+
+ Don't want to install Mintlify globally? You can run it directly:
+
+ ```bash npm
+ npx mintlify dev
+ ```
-
+ ```bash yarn
+ yarn dlx mintlify dev # Requires yarn >2
+ ```
-
- Yarn's "dlx" run script requires yarn version >2. See [here](https://yarnpkg.com/cli/dlx) for more information.
-
+ ```bash pnpm
+ pnpm dlx mintlify dev
+ ```
+
+
+
+
-A local preview of your documentation will be available at `http://localhost:3000`.
+## Common Configuration Options
-### Custom Ports
+### Change Preview Port
-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:
+By default, Mintlify runs on port 3000. You can use a different port by adding 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:
-
-```md
+If the specified port is in use, Mintlify will automatically try the next available port:
+```bash
Port 3000 is already in use. Trying 3001 instead.
```
-## Mintlify Versions
+### Check for Broken Links
+
+Keep your documentation reliable by checking for broken links:
+
+```bash
+mintlify broken-links
+```
+
+## 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:
+Each CLI release corresponds to a specific version of Mintlify. To ensure you have the latest features and fixes, update regularly:
@@ -90,42 +105,57 @@ Please note that each CLI release is associated with a specific version of Mintl
-## Validating Links
+## Editor Setup
-The CLI can assist with validating reference links made in your documentation. To identify any broken links, use the following command:
+For the best development experience, we recommend:
-```bash
-mintlify broken-links
-```
-
-## Deployment
-
-If the deployment is successful, you should see the following:
-
-
- 
-
-
-## Code Formatting
+1. Install the [MDX VSCode extension](https://marketplace.visualstudio.com/items?itemName=unifiedjs.vscode-mdx) for syntax highlighting
+2. Install [Prettier](https://marketplace.visualstudio.com/items?itemName=esbenp.prettier-vscode) for 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.
-
-## Troubleshooting
+## Troubleshooting Guide
-
+
+ If you see `Error: Could not load the "sharp" module using the darwin-arm64 runtime`, follow these steps:
+
+ 1. Remove current Mintlify installation:
+ ```bash
+ npm remove -g mintlify
+ ```
+
+ 2. Upgrade Node.js to v19 or higher
+ 3. Reinstall Mintlify:
+ ```bash
+ 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 errors:
+ 1. Delete the Mintlify cache folder:
+ ```bash
+ rm -rf ~/.mintlify
+ ```
+
+ 2. Restart the development server:
+ ```bash
+ mintlify dev
+ ```
-
-
- Solution: Go to the root of your device and delete the \~/.mintlify folder. Afterwards, run `mintlify dev` again.
+
+ When your deployment succeeds, you should see green checkmarks in your deployment status:
+
+
+
+
+
+
+ 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..b5a2aa812 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"
]
},
{
diff --git a/quickstart.mdx b/quickstart.mdx
index fd4ba0858..28beba5d9 100644
--- a/quickstart.mdx
+++ b/quickstart.mdx
@@ -1,6 +1,6 @@
---
title: "Quickstart"
-description: "Start building modern documentation in under five minutes"
+description: "Start building modern documentation in five minutes or less"
icon: "rocket"
---
@@ -15,172 +15,156 @@ icon: "rocket"
/>
-## Getting Started
+## Let's Get Started!
-Welcome! Follow the instructions below to learn how to deploy, update and
-supercharge your documentation with Mintlify.
+Welcome to Mintlify! This guide will help you create beautiful documentation in just a few minutes. Follow these simple steps to get your docs up and running.
-### Creating the Repository
+### Step 1: Create Your Documentation 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.
+
+
+ You have two options:
+ 1. **Recommended**: Sign up and create a new project through our [dashboard](https://dashboard.mintlify.com)
+ 2. Alternatively: Clone our [starter template](https://github.com/mintlify/starter) from GitHub
+
-
-
-
-
- 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.
+
+ Add the Mintlify GitHub app to automatically deploy your changes:
+ 1. Go to your [dashboard settings](https://dashboard.mintlify.com/settings)
+ 2. Click the "Install GitHub App" button
+ 3. Select your 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.
-
-
-
-
- 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:
-
+
+
+
+### Step 2: Update Your Documentation
+
+Choose your preferred editing method:
+
+
+
+ Use our [Web Editor](/web-editor) for a visual, no-installation-required experience
+ - Perfect for writers and non-developers
+ - See changes in real-time
+ - No setup needed
+
+
+ Use your favorite code editor and preview changes locally:
+ 1. Install the CLI: `npm i -g mintlify`
+ 2. Preview changes: `mintlify dev`
+
+ [Learn more about local development](/development)
+
+
+
+### Step 3: Customize Your Docs
+
+
+
+ Add your company details and branding 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).
-
-
-
-
-
- Add content with simple MDX files. Initiate your pages with this template:
-
+
+ Create new pages using MDX files with this simple format:
```md
---
title: "Page Title"
- sidebarTitle: "Sidebar title (optional - if different from page title)"
- description: "Subtitle (optional)"
+ description: "A brief 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).
+ Your content goes here
+ ```
+
-
+
+ 1. Review your changes
+ 2. Commit and push to your repository
+ 3. Mintlify will automatically deploy your updates
+
+
-
+
+ Need help? We're here for you!
+ - Join our [community](https://mintlify.com/community)
+ - Email us at [support@mintlify.com](mailto:support@mintlify.com)
+
- 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).
-
-
- 
-
+### Advanced Features
+
+
+ If you want your docs to live alongside your code:
+ 1. Move your docs content to your monorepo
+ 2. Update your docs path in the [dashboard settings](https://dashboard.mintlify.com/settings/deployment/git-settings)
+
+
+
+
+
-
-
- 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.
+
+ Generate API reference docs from your OpenAPI/Swagger file:
+ 1. Add your OpenAPI file to your repository or specify a URL:
```json
- "openapi": "link-to-your-openapi-file"
+ "openapi": "path-or-url-to-your-openapi-file"
```
- 2. Use our [scraper](/api-playground/openapi/setup#autogenerate-files-recommended) to autogenerate your OpenAPI endpoints files as:
-
+ 2. Generate endpoint files:
```bash
- npx @mintlify/scraping@latest openapi-file
+ 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).
-
+ [Learn more about API documentation](/api-playground/overview)
-
-
- 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).
-
+
+ Monitor your docs performance:
+ - Access built-in analytics in your [dashboard](https://dashboard.mintlify.com/analytics)
+ - Or integrate with [popular analytics providers](/integrations/analytics/overview)
-
- 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
-
-
+### Final Step: Add Your Domain
-Integrate your docs into your website by hosting them on a custom domain. This is included in the free plan.
+Want to host docs at your own domain? You can set this up in just a few clicks:
-Navigate to your [dashboard settings](https://www.dashboard.mintlify.com/settings) to add a custom domain.
+1. Go to your [dashboard settings](https://www.dashboard.mintlify.com/settings)
+2. Add your custom domain
+3. Update your DNS settings
-
-
-
+
+ 
+
-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).
+
+ **Did you know?** Enterprise customers get access to our white-glove migration service.
+ [Contact us](mailto:sales@mintlify.com) to learn more.
+
\ No newline at end of file
diff --git a/settings/global.mdx b/settings/global.mdx
index 350cb3c18..1db5dde16 100644
--- a/settings/global.mdx
+++ b/settings/global.mdx
@@ -1,808 +1,302 @@
---
title: "Global Settings"
-description: "Customize your documentation using the mint.json file"
+description: "Essential configurations for your Mintlify documentation site"
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)
+## Getting Started with mint.json
-## Properties
+Every Mintlify site needs a `mint.json` file to configure your documentation. This file controls site-wide settings like:
-### Styling
+- Basic branding (name, logo, colors)
+- Navigation structure
+- Layout and appearance
+- API settings (if applicable)
-
- 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
-
-
-
-
-
-
+Let's go through each important setting category.
-
- 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)
-
+## Essential Settings
-
- The global layout style of the documentation.
-
-
-
- Set a decorative background.
+These are the most important settings to get your documentation site up and running.
-
-
- The style of the decorative background.
-
-
-
+### Site Identity
-
- Set a custom background image to be displayed behind every page.
+
+ The name of your company or project that appears in the site title.
-
- Custom fonts. Apply globally or set different fonts for headings and the body
- text.
+
+ Your site's logo in SVG format (recommended). You can set different logos for light and dark modes.
Example:
-
```json
-"font": {
- "headings": {
- "family": "Roboto"
- },
- "body": {
- "family": "Oswald"
+{
+ "logo": {
+ "light": "/logo/light.svg",
+ "dark": "/logo/dark.svg",
+ "href": "https://yoursite.com" // Optional: where the 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.
-
-
-
-
-
- The location options for the search bar.
-
-
-
- The location of the search bar.
-
-
-
-
-
- The style of the rounded edges.
+
+ The icon shown in browser tabs. Example: `/favicon.svg`
-
- The style of the code block.
+### Colors and Branding
-
-
- `auto` will automatically switch between light and dark mode based on the
- user's system preferences.
-
-
+
+ Set your brand colors to customize the site's appearance.
+
+```json Basic Example
+{
+ "colors": {
+ "primary": "#16A34A",
+ "light": "#4ADE80",
+ "dark": "#166534"
+ }
+}
+```
-### Structure
+### Basic Navigation
- 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
+ Define the structure of your documentation with groups and pages.
-
-
- 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
-
-
-
+```json Example Navigation
+{
+ "navigation": [
+ {
+ "group": "Getting Started",
+ "pages": ["introduction", "quickstart"]
+ },
+ {
+ "group": "Guides",
+ "pages": ["guides/installation", "guides/configuration"]
+ }
+ ]
+}
+```
-
- 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 and Appearance
-
- 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.
-
+Control how your documentation looks and feels.
-For more information, please refer to our
-[versioning & localization documentation](/settings/versioning).
+
+ The overall layout style of your documentation.
-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"
-
+
+ Configure light/dark mode behavior.
-
+```json Example
+{
+ "modeToggle": {
+ "default": "dark",
+ "isHidden": false
+ }
+}
+```
-
- 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.
-
+
+Show More Appearance Settings
-
- One of: "brands", "duotone", "light", "sharp-solid", "solid", or "thin"
-
-
-
+
+ Pre-configured themes that change the overall look and feel:
+ - [Venus Demo](https://starter-venus.mintlify.app)
+ - [Quill Demo](https://starter-quill.mintlify.app)
+ - [Prism Demo](https://starter-prism.mintlify.app)
-
- An array of navigational tabs.
+
+ Customize fonts for headings and body text. Supports Google Fonts and custom fonts.
-Example:
-
-```json
-"tabs": [
- {
- "name": "Writing Content",
- "url": "content"
- },
- {
- "name": "API References",
- "url": "api-playground"
+```json Example
+{
+ "font": {
+ "headings": { "family": "Roboto" },
+ "body": { "family": "Open Sans" }
}
-]
+}
```
+
-
-
- 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.
-
+## Navigation Elements
-
- Pass `true` if you want to hide the tab until you directly link someone to docs inside it.
-
+Customize how users navigate your documentation.
-
-
+### Top Navigation
-
- An object to configure the footer with socials and links.
- Example:
+
+ Add links to the top navigation bar.
-```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" }
- ]
- },
+```json Example
+{
+ "topbarLinks": [
{
- "title": "Column 2",
- "links": [
- { "label": "Column 2 Link 1", "url": "https://mintlify.com" },
- { "label": "Column 2 Link 2", "url": "https://mintlify.com" }
- ]
+ "name": "Contact Us",
+ "url": "mailto:support@example.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.
-
- 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
-
- `"none"` - every expandable component is closed (default behavior)
-
-
-
+
+ Add a prominent call-to-action button.
-
+```json Example
+{
+ "topbarCtaButton": {
+ "name": "Get Started",
+ "url": "https://example.com/start"
+ }
+}
+```
-
- 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"
- ```
+
+Show More Navigation Options
- ```json Relative
- "openapi": "/openapi.json"
- ```
-
- ```json Multiple
- "openapi": ["https://example.com/openapi1.json", "/openapi2.json", "/openapi3.json"]
- ```
+
+ Create visual section anchors in the navigation.
-
+```json Example
+{
+ "anchors": [
+ {
+ "name": "API Reference",
+ "icon": "code",
+ "url": "api-reference"
+ }
+ ]
+}
+```
-### 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.
-
-
-
-
+
+ Enable user feedback features.
-
- Configurations to add third-party analytics integrations. See full list of
- supported analytics [here](/integrations/analytics/overview).
+```json Example
+{
+ "feedback": {
+ "thumbsRating": true,
+ "suggestEdit": true
+ }
+}
+```
-### Redirects
+
-
- An array of paths you want to configure to permanently redirect to another path
+## Advanced Features
-Example:
+
+If you're documenting an API, you can configure authentication, playground settings, and more.
```json
-"redirects": [
- {
- "source": "/source/path",
- "destination": "/destination/path"
+{
+ "api": {
+ "baseUrl": "https://api.example.com",
+ "auth": {
+ "method": "bearer"
+ },
+ "playground": {
+ "mode": "show"
+ }
}
-]
+}
```
+
-
-
- The path that you want to redirect from.
-
- Example: `/source`
-
-
-
- The path that you want to redirect to.
-
- Example: `/destination`
-
-
-
-
-
-### Search Engine Optimization
-
-
- Settings for Search Engine Optimization.
-
-Example:
+
+Add analytics tracking or customer support widgets.
```json
-"seo": {
- "indexHiddenPages": true
+{
+ "analytics": {
+ "ga4": {
+ "measurementId": "G-XXXXXXXX"
+ }
+ },
+ "integrations": {
+ "intercom": "YOUR_APP_ID"
+ }
}
```
+
-
-
- Enables indexing pages not included in `navigation`.
-
-
-
+
+Configure search engine optimization and URL redirects.
-## Example `mint.json`
+```json
+{
+ "seo": {
+ "indexHiddenPages": true
+ },
+ "redirects": [
+ {
+ "source": "/old-page",
+ "destination": "/new-page"
+ }
+ ]
+}
+```
+
-Click on the following dropdown to view a sample configuration file
+## Complete Example
-
- ```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": "My Project",
+ "logo": {
+ "light": "/logo/light.svg",
+ "dark": "/logo/dark.svg"
+ },
+ "favicon": "/favicon.svg",
+ "colors": {
+ "primary": "#16A34A",
+ "light": "#4ADE80",
+ "dark": "#166534"
+ },
+ "topbarLinks": [
+ {
+ "name": "Contact",
+ "url": "mailto:support@example.com"
+ }
+ ],
+ "topbarCtaButton": {
+ "name": "Get Started",
+ "url": "https://example.com/start"
+ },
+ "navigation": [
+ {
+ "group": "Getting Started",
+ "pages": ["introduction", "quickstart"]
}
+ ],
+ "footerSocials": {
+ "github": "https://github.com/example",
+ "twitter": "https://twitter.com/example"
}
- ```
+}
+```
-## More Customization
+## Need Help?
-Learn more about how to further customize your docs with custom CSS and JS in
-[Custom Scripts](https://mintlify.com/docs/advanced/custom/).
+- Check our [troubleshooting guide](/development#troubleshooting)
+- Join our [community](https://mintlify.com/community) for support
+- Contact us at [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..a72b39bf9
--- /dev/null
+++ b/snippets/getting-started.mdx
@@ -0,0 +1,113 @@
+## What is Mintlify?
+
+Mintlify helps you create beautiful documentation that your users will love. Think of it like building a website, but specifically designed for documentation with pre-built components and features that developers need.
+
+## Common Use Cases
+
+
+
+ Document your API endpoints with interactive examples and code snippets
+
+
+ Create user guides and tutorials for your product features
+
+
+ Build a central hub for all your technical documentation
+
+
+ Maintain private documentation for your team
+
+
+
+## Quick Setup Guide
+
+
+
+ Start by creating a new repository using our [starter template](https://github.com/mintlify/starter). This gives you a pre-configured setup with example pages.
+
+ ```bash
+ git clone https://github.com/mintlify/starter.git my-docs
+ ```
+
+
+
+ Replace the content in the starter template with your own documentation:
+
+ 1. Update `mint.json` with your site name and navigation
+ 2. Replace the MDX files in the starter with your own content
+ 3. Add your logo and favicon to the `/public` folder
+
+
+ Keep the example pages around until you're comfortable with how everything works. They're great reference material!
+
+
+
+
+ Install our CLI to preview your docs as you work:
+
+ ```bash
+ npm i -g mintlify
+ mintlify dev
+ ```
+
+ Your docs will be available at `http://localhost:3000`
+
+
+
+ Once you're ready, push your changes to GitHub and connect your repository in our [dashboard](https://dashboard.mintlify.com). We'll automatically build and deploy your docs.
+
+
+
+## Frequently Asked Questions
+
+
+
+ No! While being familiar with Markdown is helpful, you don't need any coding experience. Our visual editor lets you make changes without touching any code.
+
+
+
+ Yes! You can use any domain you own. We provide instructions for setting up custom domains in our [domains guide](/settings/custom-domain).
+
+
+
+ Start with broad categories and break them down into smaller topics. Use our [navigation guide](/settings/navigation) to structure your docs in a way that makes sense for your users.
+
+
+
+ Documentation sites are optimized for:
+ - Search and navigation
+ - Code examples and API references
+ - Version control and collaboration
+ - Technical content organization
+
+
+
+## Need Help?
+
+
+
+ Get help from other developers and share your questions
+
+
+ Reach out to our team directly if you need assistance
+
+
+
+## Next Steps
+
+Once you've got the basics down, explore these features:
+
+
+
+ Create interactive API documentation
+
+
+ Match your brand's look and feel
+
+
+ Use our pre-built MDX components
+
+
+ Track how users interact with your docs
+
+
\ No newline at end of file