diff --git a/docs.json b/docs.json
index 553f79930..e1fb239c1 100644
--- a/docs.json
+++ b/docs.json
@@ -24,7 +24,8 @@
"index",
"quickstart",
"installation",
- "editor"
+ "editor",
+ "quickstart/beginners-guide"
]
},
{
@@ -91,14 +92,14 @@
"group": "MDX",
"icon": "markdown",
"pages": [
- "api-playground/mdx/configuration",
- "api-playground/mdx/authentication"
+ "api-playground/mdx/configuration",
+ "api-playground/mdx/authentication"
]
},
"api-playground/troubleshooting"
]
},
- {
+ {
"group": "Authentication and personalization",
"pages": [
"authentication-personalization/overview",
@@ -138,7 +139,6 @@
"advanced/dashboard/sso",
"advanced/dashboard/permissions",
"advanced/dashboard/roles"
-
]
},
"guides/deployments",
@@ -199,7 +199,7 @@
{
"group": "Version control and CI/CD",
"pages": [
- "settings/github",
+ "settings/github",
"settings/gitlab",
"settings/ci",
"settings/preview-deployments"
diff --git a/quickstart/beginners-guide.mdx b/quickstart/beginners-guide.mdx
new file mode 100644
index 000000000..468cf864c
--- /dev/null
+++ b/quickstart/beginners-guide.mdx
@@ -0,0 +1,190 @@
+---
+title: "Beginner's Guide to Mintlify"
+description: "A recommended path for learning Mintlify from the ground up"
+icon: "route"
+---
+
+Welcome to Mintlify! This comprehensive guide will take you through everything you need to know to build beautiful documentation sites, from the basics to advanced features. Whether you're new to documentation tools or transitioning from another platform, this guide provides a structured learning path to help you master Mintlify.
+
+## Why Choose Mintlify?
+
+Mintlify makes it easy to create professional documentation that your users will love. With built-in components, customizable themes, and powerful features like API documentation generation, you can focus on writing great content while Mintlify handles the presentation.
+
+
+Take your time with each step in this guide. It's better to understand each concept thoroughly before moving to the next one.
+
+
+## Learning Path
+
+
+
+ Begin with the fundamentals of setting up your Mintlify documentation site.
+
+ **What you'll learn:**
+ - Installing and initializing Mintlify
+ - Understanding the project structure
+ - Creating your first documentation page
+ - Running the development server
+
+ **Key files to understand:**
+ - `mint.json` - Your main configuration file
+ - `introduction.mdx` - Your homepage content
+
+
+ Make sure you have Node.js installed before starting. Mintlify requires Node.js 18 or higher.
+
+
+
+
+ Learn how to create and organize your documentation pages effectively.
+
+ **What you'll learn:**
+ - Creating new MDX pages
+ - Understanding frontmatter properties
+ - Using markdown syntax effectively
+ - Organizing content with headers and sections
+ - Adding images and media
+
+ **Best practices:**
+ - Use descriptive filenames
+ - Keep pages focused on single topics
+ - Structure content with clear headings
+
+
+
+ Master the art of creating intuitive navigation for your documentation.
+
+ **What you'll learn:**
+ - Configuring the navigation in `mint.json`
+ - Creating page groups and sections
+ - Setting up sidebar navigation
+ - Adding external links
+ - Implementing breadcrumbs
+
+
+ Plan your navigation structure before adding many pages. A well-organized navigation improves user experience significantly.
+
+
+
+
+ Customize the look and feel of your documentation to match your brand.
+
+ **What you'll learn:**
+ - Choosing and configuring themes
+ - Customizing colors and branding
+ - Adding your logo and favicon
+ - Setting up custom fonts
+ - Configuring dark/light mode
+
+ **Customization options:**
+ - Primary and accent colors
+ - Background colors
+ - Custom CSS (advanced)
+
+
+
+ Enhance your documentation with Mintlify's built-in components.
+
+ **What you'll learn:**
+ - Using callout components (Tip, Warning, Info, Note)
+ - Creating expandable sections with Accordion
+ - Adding code blocks with syntax highlighting
+ - Implementing tabs for multiple examples
+ - Using cards for feature highlights
+
+ **Popular components to master:**
+ - `` and ``
+ - `` and ``
+ - `` and ``
+ - `` (like this guide!)
+
+
+
+ Learn to create comprehensive API documentation that developers love.
+
+ **What you'll learn:**
+ - Setting up API endpoint documentation
+ - Using OpenAPI/Swagger specifications
+ - Creating interactive API examples
+ - Adding authentication guides
+ - Implementing code samples in multiple languages
+
+
+ API documentation is one of Mintlify's strongest features. Take time to explore all the available options.
+
+
+
+
+ Explore powerful features that make your documentation stand out.
+
+ **What you'll learn:**
+ - Setting up search functionality
+ - Implementing analytics
+ - Adding custom domains
+ - Using integrations (GitHub, Slack, etc.)
+ - Performance optimization
+ - SEO best practices
+
+ **Advanced topics:**
+ - Custom components with React
+ - Advanced configuration options
+ - Deployment strategies
+
+
+
+## Essential Tips for Success
+
+
+
+ Focus on creating valuable content before worrying about design. Good information well-structured is more important than perfect styling.
+
+
+
+ Regularly test your documentation with real users. What makes sense to you might not be clear to others.
+
+
+
+ Documentation is only valuable if it's current. Set up processes to keep your content fresh and accurate.
+
+
+
+ Many users access documentation on mobile devices. Always check how your content looks on different screen sizes.
+
+
+
+## Common Pitfalls to Avoid
+
+
+**Don't skip the planning phase.** Rushing into creating pages without a clear structure often leads to confusing navigation and poor user experience.
+
+
+
+**Avoid overwhelming users.** Don't put too much information on a single page. Break complex topics into digestible sections.
+
+
+
+**Don't forget about maintenance.** Set up a process for regularly reviewing and updating your documentation as your product evolves.
+
+
+## Next Steps
+
+Congratulations on completing the beginner's guide! Here's what you should do next:
+
+1. **Practice**: Create a small documentation project to practice what you've learned
+2. **Explore examples**: Look at well-designed documentation sites for inspiration
+3. **Join the community**: Connect with other Mintlify users for tips and support
+4. **Advanced learning**: Dive deeper into specific areas that interest you most
+
+## Additional Resources
+
+- **Official Documentation**: Comprehensive guides for every Mintlify feature
+- **Component Library**: Complete reference for all available components
+- **Community Examples**: Real-world documentation sites built with Mintlify
+- **Video Tutorials**: Step-by-step video guides for visual learners
+- **Support Channels**: Get help when you're stuck
+
+
+Remember, great documentation is an iterative process. Start simple, gather feedback, and continuously improve. Your users will appreciate the effort you put into making their experience better.
+
+
+Ready to build amazing documentation? Start with the basics and work your way through each step. You've got this!
\ No newline at end of file