diff --git a/docs.json b/docs.json
index ef20fc512..0578a75c2 100644
--- a/docs.json
+++ b/docs.json
@@ -25,7 +25,8 @@
"quickstart",
"installation",
"editor",
- "support"
+ "support",
+ "getting-started/faq"
]
},
{
@@ -97,7 +98,7 @@
"api-playground/troubleshooting"
]
},
- {
+ {
"group": "Authentication and Personalization",
"pages": [
"settings/authentication-personalization/authentication",
@@ -155,7 +156,6 @@
"advanced/dashboard/sso",
"advanced/dashboard/permissions",
"advanced/dashboard/roles"
-
]
}
]
@@ -214,7 +214,7 @@
{
"group": "Version Control and CI/CD",
"pages": [
- "settings/github",
+ "settings/github",
"settings/gitlab",
"settings/ci",
"settings/preview-deployments"
diff --git a/getting-started/faq.mdx b/getting-started/faq.mdx
new file mode 100644
index 000000000..6eb9c2c53
--- /dev/null
+++ b/getting-started/faq.mdx
@@ -0,0 +1,198 @@
+---
+title: "Frequently Asked Questions"
+description: "Common questions and answers about Mintlify documentation platform"
+---
+
+# Frequently Asked Questions
+
+Find answers to the most commonly asked questions about Mintlify. If you can't find what you're looking for, feel free to reach out to our support team.
+
+## Getting Started
+
+
+ Mintlify is a modern documentation platform that helps developers create beautiful, interactive documentation websites. It transforms your markdown files into polished documentation sites with features like API references, interactive components, and seamless deployment.
+
+
+
+ Getting started is simple:
+ 1. Install the Mintlify CLI: `npm i -g mintlify`
+ 2. Initialize your project: `mintlify init`
+ 3. Configure your `mint.json` file
+ 4. Add your content in markdown files
+ 5. Preview locally with `mintlify dev`
+ 6. Deploy your documentation
+
+
+
+ While basic knowledge of markdown is helpful, you don't need extensive coding experience. Mintlify is designed to be developer-friendly while remaining accessible to technical writers and product managers who work with documentation.
+
+
+
+ Yes! Mintlify supports migration from various documentation platforms. Most markdown-based documentation can be migrated with minimal changes. We provide migration guides for popular platforms like GitBook, Notion, and custom documentation sites.
+
+
+## Setup and Configuration
+
+
+ The essential files for a Mintlify project are:
+ - `mint.json` - Configuration file for your documentation
+ - `introduction.mdx` - Your homepage content
+ - Additional `.mdx` or `.md` files for your documentation pages
+ - Optional: `favicon.svg`, custom CSS files, and images
+
+
+
+ Navigation is configured in the `mint.json` file using the `navigation` property. You can organize pages into groups, create nested navigation, and control the order of pages. Each navigation item should reference the path to your markdown files.
+
+
+
+ Yes! Mintlify offers extensive customization options:
+ - Custom colors and branding in `mint.json`
+ - Custom CSS files
+ - Logo and favicon customization
+ - Font selections
+ - Light and dark mode themes
+
+
+
+ Mintlify supports OpenAPI specifications for automatic API documentation generation. You can:
+ - Reference your OpenAPI spec in `mint.json`
+ - Use the `` component in your markdown files
+ - Manually create API documentation using Mintlify's API components
+
+
+## Features and Functionality
+
+
+ Mintlify provides a rich set of components including:
+ - `` for collapsible content
+ - `` and `` for organized layouts
+ - `` for tabbed content
+ - `` for code examples
+ - ``, ``, `` callout boxes
+ - `` for images and screenshots
+ - API components for endpoint documentation
+
+
+
+ Yes! Mintlify supports syntax highlighting for over 100 programming languages. Simply specify the language in your code blocks, and Mintlify will automatically apply appropriate syntax highlighting.
+
+
+
+ Absolutely! Mintlify supports:
+ - Interactive API playground
+ - Embedded videos and images
+ - Collapsible sections with Accordion
+ - Tabbed content organization
+ - Custom React components (on higher plans)
+
+
+
+ Yes, Mintlify includes built-in search functionality that indexes all your content automatically. Users can search through your documentation using the search bar, which supports fuzzy matching and instant results.
+
+
+## Deployment and Hosting
+
+
+ You can deploy your documentation in several ways:
+ - Connect your GitHub repository to Mintlify for automatic deployments
+ - Use the Mintlify CLI to deploy manually
+ - Deploy to your own hosting platform
+ - Use Mintlify's hosting service for hassle-free deployment
+
+
+
+ Yes! Mintlify supports custom domains. You can configure your custom domain in your project settings and update your DNS records to point to Mintlify's servers. SSL certificates are automatically provisioned.
+
+
+
+ Mintlify offers authentication features on paid plans, allowing you to:
+ - Protect your documentation with login requirements
+ - Integrate with SSO providers
+ - Control access to specific pages or sections
+ - Manage user permissions and groups
+
+
+## Pricing and Plans
+
+
+ Mintlify offers a free tier that includes core documentation features, basic customization, and community support. Paid plans provide additional features like custom domains, authentication, analytics, and priority support.
+
+
+
+ The main differences include:
+ - **Free**: Basic features, Mintlify subdomain, community support
+ - **Paid plans**: Custom domains, authentication, advanced analytics, priority support, white-label options, and additional customization features
+
+
+
+ Yes, you can change your plan at any time. Upgrades take effect immediately, while downgrades take effect at the end of your current billing cycle. Your documentation remains accessible during plan changes.
+
+
+## Troubleshooting
+
+
+ If your changes aren't appearing:
+ 1. Check that your files are properly saved
+ 2. Ensure your `mint.json` configuration is valid
+ 3. Clear your browser cache
+ 4. For deployed sites, check if your deployment completed successfully
+ 5. Verify that your file paths in navigation match your actual file structure
+
+
+
+ Common build issues and solutions:
+ - **Invalid JSON**: Validate your `mint.json` file syntax
+ - **Missing files**: Ensure all referenced files in navigation exist
+ - **Image issues**: Check that image paths are correct and files exist
+ - **Component errors**: Verify that all Mintlify components are properly formatted
+
+
+
+ To fix broken links:
+ 1. Use relative paths for internal links
+ 2. Ensure file extensions match your actual files (.mdx or .md)
+ 3. Check that referenced files exist in your project
+ 4. Use the correct case for file names (case-sensitive)
+ 5. Update navigation in `mint.json` to match your file structure
+
+
+
+ If custom styles aren't applying:
+ 1. Ensure your CSS file is properly referenced in `mint.json`
+ 2. Check CSS syntax and specificity
+ 3. Verify that custom CSS is supported on your plan
+ 4. Clear browser cache and hard refresh
+ 5. Use browser developer tools to debug styling issues
+
+
+## Support and Resources
+
+
+ Mintlify offers several support channels:
+ - **Documentation**: Comprehensive guides and tutorials
+ - **Community Discord**: Connect with other users and get community support
+ - **GitHub Issues**: Report bugs and request features
+ - **Email Support**: Direct support for paid plan users
+ - **Office Hours**: Regular community calls for questions and feedback
+
+
+
+ You can report bugs or request features through:
+ - GitHub Issues on the Mintlify repository
+ - Community Discord server
+ - Email support (for paid users)
+ - Feature request form on the Mintlify website
+
+
+
+ Yes! You can find examples and inspiration in:
+ - Mintlify's showcase page featuring customer documentation
+ - The Mintlify documentation itself (built with Mintlify)
+ - Community Discord where users share their projects
+ - GitHub repositories with open-source Mintlify projects
+
+
+---
+
+Still have questions? Join our [Discord community](https://discord.gg/mintlify) or check out our [documentation](/) for more detailed guides and tutorials.
\ No newline at end of file