diff --git a/api-playground/overview.mdx b/api-playground/overview.mdx
index c222ffedf..0a09d2d68 100644
--- a/api-playground/overview.mdx
+++ b/api-playground/overview.mdx
@@ -1,15 +1,97 @@
---
-title: 'Interactive Playground'
-description: 'Enable users to interact with your API'
+title: 'Interactive API Playground'
+description: 'Enable users to interact with your API endpoints and test requests directly in your documentation'
openapi: 'GET /plants/{id}'
hideApiMarker: true
icon: 'play'
---
-The API playground is an interactive environment to make requests and preview an API endpoint.
+## Overview
+The API playground provides an interactive environment where users can test API endpoints directly within your documentation. It allows users to:
+- Make live API requests
+- Test different parameters and configurations
+- See real responses from your API
+- Copy generated code snippets in multiple languages
+
+## Features
+
+### Interactive Request Testing
+Users can modify request parameters, headers, and body content to test different API scenarios. The playground provides immediate feedback with actual API responses.
+
+### Code Generation
+The playground automatically generates code snippets in multiple programming languages based on the configured request, making it easy for developers to implement API calls in their preferred language.
+
+### Authentication Support
+Built-in support for various authentication methods including:
+- API Keys
+- Bearer Tokens
+- Basic Auth
+- OAuth 2.0
+
+## Implementation Options
+
+### OpenAPI Integration
- Autogenerating API pages with OpenAPI will automatically generate API
- playground. Read more about using OpenAPI with Mintlify
- [here](/api-playground/openapi).
+ When you use OpenAPI to define your endpoints, Mintlify automatically generates API playgrounds for each endpoint. This ensures consistency between your API specification and interactive documentation. Learn more about OpenAPI integration [here](/api-playground/openapi).
+
+### Manual Configuration
+For cases where you prefer manual configuration, you can specify endpoint details directly in your MDX files. This gives you full control over the playground's appearance and behavior.
+
+## Example Setup
+
+Here's a basic example of how to set up an API playground for an endpoint:
+
+```markdown
+---
+title: 'Get User'
+api: 'GET /api/users/{id}'
+---
+```
+
+### Parameters Configuration
+Use the ParamField component to define endpoint parameters:
+
+```jsx
+
+ The unique identifier of the user
+
+```
+
+## Customization
+
+The API playground supports several customization options:
+
+### Response Display
+Control how responses are displayed:
+- Pretty-printed JSON
+- Raw response
+- Status code highlighting
+
+### Code Examples
+Configure which programming languages are shown in code examples:
+- Choose default language
+- Customize language order
+- Add or remove supported languages
+
+## Best Practices
+
+To create effective API playgrounds:
+
+1. Provide clear parameter descriptions
+2. Include example values
+3. Document expected responses
+4. Add error handling examples
+5. Use realistic sample data
+
+## Related Resources
+
+
+
+ Learn how to automatically generate API playgrounds from your OpenAPI spec
+
+
+ Configure authentication for your API playground
+
+
\ No newline at end of file
diff --git a/changelog/overview.mdx b/changelog/overview.mdx
index ad2c56f93..69a377929 100644
--- a/changelog/overview.mdx
+++ b/changelog/overview.mdx
@@ -3,344 +3,236 @@ title: "Product Updates"
description: "New updates and improvements"
mode: "center"
---
+
- ## Authentication
-
- 
-
- Make docs private by setting up authentication via JWT, OAuth, or a universal password. With this privacy, you can create an internal knowledge base or prevent competitors from seeing your docs.
+## New Authentication System
+
+
+
+We've launched a comprehensive authentication system enabling:
+- Private documentation access via JWT, OAuth, or universal password
+- Internal knowledge base creation capabilities
+- Competitor access control
+- Enhanced security features
+This update helps teams better manage access to their documentation while maintaining security and privacy.
-
- ## AI Assistant
-
-
- 
-
-
- You can now ask AI to make changes to your docs, with the context of all existing documentation. Type in a prompt and the assistant will propose changes by generating a pull request.
-
- ## GitLab Integration Upgrade
-
- We've improved our support for syncing with GitLab, such as enabling automated updates and preview deployments. Check out our [docs on GitLab](/settings/gitlab) to get started.
-
- ## Web Editor
-
-
- 
-
-
- We've revamped our web editor so that you can now update docs with a fully WYSIWYG experience, while syncing with markdown.
-
- Check out our [docs on getting started with Web Editor](/web-editor).
-
- ## /llms.txt support
-
-
- 
-
-
- All docs instances are now automatically hosted at /llms.txt and /llms-full.txt so that LLMs can easily ingest your documentation. For more information, read the [docs on the new llms.txt standard.](https://llmstxt.org)
-
- ## Localization
-
- You can now localize your docs which operates similarly to versioning. Add a `locale` to a version and fixed content in Mintlify like "Was this page helpful?" will also match the locale.
-
- ### Quality Improvements
-
- * Return chat & search results based on the current version that the user is reading
-
- * Authenticate users with OAuth, in addition to JWT or Shared Session tokens.
+## Major Platform Updates
+
+### AI Assistant Integration
+
+
+
+
+Our new AI Assistant enables automated documentation improvements:
+- Context-aware content suggestions
+- Pull request generation for proposed changes
+- Intelligent content editing capabilities
+
+### Enhanced GitLab Integration
+We've strengthened our GitLab support with:
+- Automated update functionality
+- Preview deployment capabilities
+- Improved sync processes
+
+Learn more in our [GitLab documentation](/settings/gitlab).
+
+### Revamped Web Editor
+
+
+
+
+The new web editor features:
+- Full WYSIWYG editing experience
+- Markdown synchronization
+- Real-time preview capabilities
+
+Explore the features in our [Web Editor guide](/web-editor).
+
+### LLM Documentation Support
+
+
+
+
+New LLM-friendly documentation features:
+- Automatic /llms.txt and /llms-full.txt endpoints
+- Enhanced documentation ingestion
+- Improved ML accessibility
+
+Read more about the [llms.txt standard](https://llmstxt.org).
+
+### Enhanced Localization
+New localization capabilities with:
+- Version-based localization support
+- Automatic UI translation
+- Locale-specific content management
+
+### Platform Improvements
+- Version-aware search and chat results
+- Enhanced OAuth user authentication
+- Improved JWT and Session Token support
- ## Changelogs
-
- Launched a new [Update component](/content/components/update) to make it easier to display and report updates (like this one) to your users.
-
-
- 
-
-
- ## Code Line Highlighting
-
- You can now highlight lines of code in your docs to emphasize and bring attention to important parts by adding a special comment after the language identifier. Use curly braces `{}` and specify line numbers or ranges separated by commas.
-
- ```javascript Line Highlighting Example {1,3-5}
- const greeting = "Hello, World!";
- function sayHello() {
- console.log(greeting);
- }
- sayHello();
- ```
-
- ````md
- ```javascript Line Highlighting Example {1,3-5}
- const greeting = "Hello, World!";
- function sayHello() {
- console.log(greeting);
- }
- sayHello();
- ```
- ````
-
- ## Light mode code blocks
-
- Code blocks now have a light mode variant which can be enabled by adding the following to your `mint.json`:
-
- ```json
- "codeBlock": {
- "mode": "auto"
- }
- ```
-
- ## Advanced Footer
-
-
- 
-
-
- You can now add more links to the standard footer. This upgrade
- provides more consistency between landing pages and docs, or greater customization
- if you want to spotlight specific pages like socials or status logs.
-
- ## Filter search based on the current user
-
- When personalization is enabled, search results are now filtered based on the current logged in user so that they only see the relevant content.
-
- ## Custom Prompts for AI Chat
-
- You can now customize the prompts for the AI chat. Please reach out to [support](mailto:sales@mintlify.com) if you'd like to customize the prompts.
-
- ## Dashboard Improvements
-
- * Added ability to change custom domain to be /docs directly through dashboard settings.
-
- * Consolidated the login and signup pages to decrease friction and confusion.
-
- * Implemented the discovery login flow so that users that are members of multiple organizations can now switch between them.
-
- * Added login with Google OAuth
-
- * Added ability to add new deployment through dashboard settings.
-
- ## Bug Fixes
-
- * Can now use leading slashes in navigation.
-
- * Can now edit CSS & JS files in the web editor.
-
- * Fixed `suggestEdit` not showing up even when enabled.
-
- * Fixed keyboard navigation for Search and Chat such that you can now use the up and down arrow keys to navigate the results.
-
- * Don't allow search engines to crawl user-auth protected pages.
-
- * Revalidate the cache when an org is deleted.
-
- * We now use the Scalar OpenAPI parser to parse OpenAPI definitions which improves the performance, fixes parsing issues, and surfaces better error messages.
-
- * Top-level descriptions are now supported in API reference pages autogenerated from OpenAPI definitions.
-
- * Add in-line-style support for icons
-
- * Fixed the pop-in of custom CSS in docs.
-
- * Properly show in-line code styling in conjunction with links.
-
- * Maintain scroll position when you click the back button in a browser.
+## Platform Enhancements
+
+### New Update Component
+
+
+
+
+Launched the [Update component](/content/components/update) for improved changelog management and update reporting.
+
+### Code Improvements
+
+#### Line Highlighting
+Added code line highlighting functionality:
+```javascript Line Highlighting Example {1,3-5}
+const greeting = "Hello, World!";
+function sayHello() {
+ console.log(greeting);
+}
+sayHello();
+```
+
+#### Light Mode Support
+Added light mode variant for code blocks via mint.json:
+```json
+"codeBlock": {
+ "mode": "auto"
+}
+```
+
+### Advanced Footer Features
+
+
+
+
+Enhanced footer customization with:
+- Expanded link support
+- Improved landing page consistency
+- Custom social and status page integration
+
+### User Experience Improvements
+- Personalized search filtering
+- Custom AI chat prompts
+- Enhanced documentation visibility
+
+### Dashboard Enhancements
+- Custom domain management for /docs
+- Streamlined login/signup process
+- Multi-organization support
+- Google OAuth integration
+- New deployment management tools
+
+### Technical Improvements
+- Navigation with leading slashes
+- Web editor CSS/JS file support
+- Fixed suggestEdit functionality
+- Enhanced keyboard navigation
+- Improved search engine handling
+- Cache validation updates
+- OpenAPI parsing optimization
+- Inline styling improvements
+- Browser navigation fixes
- ## Custom Fonts
-
-
- 
-
-
- Personalize the font of your docs to your own font hosted on a CDN or by choosing from Google fonts to match your docs with your brand.
-
- ## Images in Card components
-
- Add an `img` property to a card to display an image on the top of the card. Learn more about it [here](/content/components/cards#image-card).
-
- ## Update Speed Performances
-
-
- 
-
-
- For large projects (\~3,000 files), the download step for docs updates is now
- \~440x faster - a 99.8% time reduction. Across the board, file downloads during
- updates are now \~5.5x faster - an 81.8% time reduction.
-
- ## SEO improvements
-
-
- 
-
-
- We've fixed both the mobile and desktop layout of our docs so that they are more SEO-friendly - including adding proper aria tags to navbar and toggle elements.
-
- ## Dashboard Improvements
-
- * App router migration in the dashboard.
-
- * Search analytics are now available in the dashboard.
-
- * Delete an org functionality has been added to the dashboard.
-
- * Shipped GitLab connection UI.
-
- * Fix incorrect analytics data.
-
- * Add-on's can now be directly purchased through the dashboard.
-
- ## Bug Fixes
-
- * Fixed a bug where the top bar would not stretch to the width of the screen when it's in custom mode and the sidebar layout is `sidenav`.
-
- * Fix relative positioning of the AI widget.
-
- ## More
-
- * **Troubleshooting for API pages**: API pages could be complicated so we listed
- common issues to help you sort them out quickly —
- [Read the docs](/api-playground/troubleshooting)
-
-
-
- ## OpenAPI Reference Pages
-
- * Endpoints defined by OpenAPI that are complex and recursive are now 98%
- smaller.
-
- * We now show
- [additionalProperties](https://swagger.io/docs/specification/data-models/dictionaries/)
- in OpenAPI pages.
-
- ## File Uploads in API Playground
-
- By default, API playground requests are proxied by Mintlify. Now you can use
- `disableProxy` to disable this behavior and support request types like file
- uploads.
-
- * [Learn more about API configurations](/settings/global#api-configurations)
-
- ## Mobile SEO improvements
-
- We've fixed the mobile layout of our docs so that they are more SEO-friendly -
- including adding proper aria tags to elements.
-
- ## Support Form
-
- We added a more detailed support form to the Mintlify dashboard. You can now
- submit a form to get in touch with us.
-
- ## Bug Fixes
-
- * Fixed a bug for the Segment integration functionality.
-
- * We now raise more granular error messages for GitHub permissions when
- interacting with the editor.
-
- * Fixed bugs where the navigation would not properly expand when a direct link
- was used.
+## Feature Releases
+
+### Custom Font Integration
+
+
+
+
+New font customization options:
+- CDN-hosted custom font support
+- Google Fonts integration
+- Brand-matching typography options
+
+### Enhanced Card Components
+Added image support in Card components - learn more about the [new Card features](/content/components/cards#image-card).
+
+### Performance Optimization
+
+
+
+
+Significant performance improvements:
+- 99.8% faster downloads for large projects
+- 81.8% improvement in file download speed
+- Enhanced update processing
+
+### SEO Enhancement
+
+
+
+
+Comprehensive SEO improvements:
+- Mobile-optimized layouts
+- Enhanced desktop accessibility
+- Improved ARIA tag implementation
+
+### Platform Updates
+- Dashboard app router migration
+- New analytics dashboard
+- Organization management tools
+- Improved GitLab integration
+- Analytics accuracy improvements
+- Add-on purchasing capabilities
+
+### Documentation
+Added comprehensive [API troubleshooting guide](/api-playground/troubleshooting).
-
- ## AI Widget
-
-
- 
-
-
- For `Pro` users, we introduced Mintlify Widget, an extension of your docs to
- answer your users' questions when and where they asked. You can add this
- AI-powered chatbot to any web page: your landing page, inside your product, or
- on your existing documentation pages.
-
- * [Read the blog announcement](https://mintlify.com/blog/widget)
-
- * [Learn how to install the Widget](/advanced/widget/chat#getting-started)
-
- ## Pro Plan
-
- We also updated our pricing plans for better customizability and scale.
-
- * [Read the blog announcement](https://mintlify.com/blog/pro-plan)
-
- ## API Playground Code Example Sync
-
- When you browse API docs, the selected code example now syncs across your pages.
-
- ## Insights
-
- Currently in beta, this feature summarizes common user questions and patterns
- into easy-to-digest reports with AI-powered suggestions on how to improve your
- product.
-
-
-
-
-## Launch Week Highlights
-* Themes: Customize your styling with pre-configured themes. Just add the theme Quill, Prism, or Venus to your `mint.json` file and it'll update your docs styling.
-* Search V2: directly query OpenAPI endpoint descriptions and titles to reach API Reference pages, remove hidden pages from search, and enjoy our updated searchbar UI.
-* Web Editor branching: create branches in our web editor without an IDE.
-* User Personalization: authenticate users with Shared Session or JWT so that you can show them customized content, such as pre-filling API keys or showing specific content for customers.
-* OepenAPI Automation Upgrades: to auto-populate API Playground pages, you can add an `openapi` field to an object in tabs or anchors arrays in the mint.json.
-
-
-
-
-
-## Okta SSO
-We now support sign-on via Okta SAML and OIDC.
-
-## Mintlify REST API
-Programmatically rigger updates to your documentation.
-
-
-
-
-
-## Custom mode
-Add a configuration to the metadata to remove all elements except for the top bar.
-Example use cases:
-* Create a custom global landing page setup with custom components
-* Add full-screen videos or image galleries
-* Embed custom iFrame demo elements to add intractability to your docs
-
-Check out our [Custom Mode docs](/page#custom-mode).
-
-
-
-
-## Mintlify MDX for VSCode
-Call snippets of our pre-built components an dcallouts without leaving VSCode. [Install the extension here](https://marketplace.visualstudio.com/items?itemName=mintlify.mintlify-snippets).
-
-
-
-
-
-## Quality Improvements
-* Dashboard upgrades: view update logs to see what's changed and status of an update, toggle between Mintlify projects to manage deployments
-* Versioning with tabs fully supported
-* Wildcard redirects now supported
-* CLI Error Detection: we now show the position of invalid frontmatter when there are parsing issues during local development
-
-
-
-
-
-## Launch Week Highlights
-* Preview Deployments: When you create a pull request, we'll generate a unique link that shows a live preview of what your docs look like in prod. You can share this link with teammates.
-* Snippets V2: We now support fully reusable components and variables for snippets.
-* Open-source MDX Engine: We've exposed two APIs—getCompiledMdx and MDXComponent—so you can access Mintlify markdown and code syntax highlighting. [Contributions to the project](https://github.com/mintlify/mdx) are welcome.
-* AI Chat Insights: Segment chat history by date and increase AI Chat quota from the dashboard, and see how often a specific query appears.
-
-
+
+## Key Releases
+
+### August 2024
+- OpenAPI reference optimization
+- API playground file upload support
+- Mobile SEO improvements
+- Enhanced support system
+
+### July 2024
+- AI Widget launch for Pro users
+- Updated pricing structure
+- API playground improvements
+- Insights beta release
+
+### June 2024
+- New customizable themes
+- Search V2 implementation
+- Web editor branching
+- User personalization features
+- OpenAPI automation upgrades
+
+### May 2024
+- Okta SSO integration
+- Mintlify REST API release
+
+### April 2024
+- Custom mode introduction
+- Enhanced component support
+- Improved documentation interactivity
+
+### March 2024
+- VSCode extension release
+- Enhanced MDX support
+
+### February 2024
+- Dashboard upgrades
+- Versioning improvements
+- Enhanced redirect support
+- Improved CLI error detection
+
+### January 2024
+- Preview deployment feature
+- Snippets V2 release
+- Open-source MDX Engine
+- Enhanced AI Chat analytics
+
\ No newline at end of file
diff --git a/mint.json b/mint.json
index 65c9d33d9..011525af1 100644
--- a/mint.json
+++ b/mint.json
@@ -65,12 +65,15 @@
"icon": "pen-paintbrush",
"pages": [
"development",
+ "web-editor",
"web-editor"
]
},
"settings/global",
"settings/navigation",
- "migration"
+ "migration",
+ "quickstart",
+ "settings/authentication"
]
},
{
@@ -105,7 +108,8 @@
"api-playground/mdx/authentication"
]
},
- "api-playground/troubleshooting"
+ "api-playground/troubleshooting",
+ "api-playground/overview"
]
},
{
@@ -272,6 +276,7 @@
{
"group": "Changelog",
"pages": [
+ "changelog/overview",
"changelog/overview"
]
}
diff --git a/quickstart.mdx b/quickstart.mdx
index fd4ba0858..d3fb1d13e 100644
--- a/quickstart.mdx
+++ b/quickstart.mdx
@@ -15,172 +15,200 @@ icon: "rocket"
/>
-## Getting Started
+## Introduction
-Welcome! Follow the instructions below to learn how to deploy, update and
-supercharge your documentation with Mintlify.
+Welcome to Mintlify! This quickstart guide will walk you through the process of setting up your documentation site. You'll learn how to deploy your docs, make updates, and enhance them with advanced features.
-### Creating the Repository
+## Setting Up Your Repository
-Mintlify docs are rendered from MDX files and configurations defined in our
-[starter kit](https://github.com/mintlify/starter). We use GitHub to integrate
-your docs with your code, and make source control effortless. Onboard through the [dashboard](https://dashboard.mintlify.com) or clone our [starter kit](https://github.com/mintlify/starter) to get started.
+Before you can start building your documentation, you'll need to set up your repository. Mintlify renders documentation from MDX files and configurations defined in our starter kit.
-
+### Choose Your Setup Method
+
+You have two main options to get started:
+1. Create a new repository through our [dashboard](https://dashboard.mintlify.com)
+2. Clone our [starter kit](https://github.com/mintlify/starter) directly
+
+### Configure GitHub Integration
-
-
- 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.
+To enable automatic deployments, you'll need to set up our GitHub integration:
+
+
+ Navigate to your [dashboard settings](https://dashboard.mintlify.com/settings) and locate the GitHub app installation section.
+
+
+ Follow the installation prompts to give Mintlify access to your documentation repository.
+
+
+ Once installed successfully, you'll see a check mark next to your repository's commit hash.
- 
+ 
+
+
-
+### Monorepo Configuration
-
- 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)
-
- 
- 
-
-
+If you're using a monorepo structure to keep your docs alongside your code:
-
+
+
+ Relocate your documentation content into your monorepo structure.
+
+
+ Specify your docs location in the [dashboard settings](https://dashboard.mintlify.com/settings/deployment/git-settings).
+
+
+
+
+
+
-### Updating the Content
+## Making Updates
-Mintlify enables you to easily customize the style, structure, and content of
-your docs.
+Mintlify offers multiple ways to update your documentation. Here's an overview of the available methods and customization options:
-
-
- 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).
-
+
+ For developers who prefer working in their own environment:
+
+
+
+ Download and install [Git](https://git-scm.com/book/en/v2/Getting-Started-Installing-Git) if you haven't already.
+
+
+ Clone your docs using `git clone `. We recommend setting up [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) first.
+
+
+ Open the repository in your preferred IDE.
+
+
+ Run `npm i -g mintlify` to install our preview tool.
+
+
+
+ For more details, check our [local development guide](/development).
-
-
- Learn more about how to use the web editor on our [guide](/web-editor).
-
+
+ Our web editor provides a user-friendly interface for making documentation changes. Learn more in our detailed [web editor guide](/web-editor).
-
-
- Easily customize colors, logos and buttons among other configurations in our `mint.json` file. Start with these basic configurations:
+
+ Customize your documentation's appearance through the `mint.json` configuration file:
```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",
+ "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).
-
+ Explore all configuration options in our [global settings](/settings/global) guide.
-
-
- Add content with simple MDX files. Initiate your pages with this template:
+
+ Creating new documentation pages is straightforward with our MDX template:
```md
---
title: "Page Title"
- sidebarTitle: "Sidebar title (optional - if different from page title)"
- description: "Subtitle (optional)"
+ sidebarTitle: "Sidebar title (optional)"
+ description: "Page description (optional)"
---
```
- Learn more about adding images, tables, lists, and more using the [MDX syntax](/text). We also offer a [wide array of components](/content/components).
-
+ Learn about our [MDX syntax](/text) and explore our [component library](/content/components).
-
+
+ Deploy your changes by committing and pushing to your repository. If you encounter any issues:
- 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).
-
-
- 
-
+ 1. Review the [GitHub push guide](https://docs.github.com/en/get-started/using-git/pushing-commits-to-a-remote-repository#about-git-push)
+ 2. Use manual updates through our [dashboard](https://dashboard.mintlify.com) if needed
+
+ 
+
-
-
- 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.
-
- ```json
- "openapi": "link-to-your-openapi-file"
- ```
-
- 2. Use our [scraper](/api-playground/openapi/setup#autogenerate-files-recommended) to autogenerate your OpenAPI endpoints files as:
-
- ```bash
- npx @mintlify/scraping@latest openapi-file
- ```
-
- 3. Finally, include the generated endpoint MDX files to your `mint.json` under `navigation`.
-
- For a complete guide on using Mintlify with OpenAPI, check out [this guide](/api-playground/openapi/setup). [This guide](/api-playground/openapi/writing-openapi) explains how to configure your API authentication methods. For manual API references definition, explore [our syntax](/api-playground/overview).
-
+
+ Create comprehensive API documentation using OpenAPI:
+
+
+
+ Include your OpenAPI file in your repository or add the URL to `mint.json`:
+ ```json
+ {
+ "openapi": "link-to-your-openapi-file"
+ }
+ ```
+
+
+ Run our endpoint generator:
+ ```bash
+ npx @mintlify/scraping@latest openapi-file
+ ```
+
+
+ Add the generated files to your `mint.json` navigation.
+
+
+
+ Read our complete guides on [OpenAPI setup](/api-playground/openapi/setup) and [authentication configuration](/api-playground/openapi/writing-openapi).
-
-
- Our in-house analytics give you insights into page views, search analytics, session recordings and more. Access these on your [dashboard](https://dashboard.mintlify.com/analytics).
-
- We also support integrations with a range of analytics providers. You can find the list of providers [here](/integrations/analytics/overview).
-
+
+ Track documentation usage with our built-in analytics:
+
+ - Access metrics through your [dashboard](https://dashboard.mintlify.com/analytics)
+ - Integrate with [third-party 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).
-
+## Next Steps
-### Publishing
+### Custom Domain Setup
-
+Make your documentation feel native to your product by hosting it on your domain:
-Integrate your docs into your website by hosting them on a custom domain. This is included in the free plan.
+
+
+ Open your [dashboard settings](https://www.dashboard.mintlify.com/settings)
+
+
+ Navigate to the custom domain section and enter your desired domain
+ 
+
+
-Navigate to your [dashboard settings](https://www.dashboard.mintlify.com/settings) to add a custom domain.
+### Enterprise Support
-
+
+ Need help migrating your existing documentation? Our Enterprise plan includes white-glove migration services. [Contact our team](mailto:sales@mintlify.com) to learn more.
+
-
+## Getting 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).
+We're here to support your documentation journey:
+- Join our [community](https://mintlify.com/community) for discussions and tips
+- Contact us at [support@mintlify.com](mailto:support@mintlify.com) for direct assistance
\ No newline at end of file
diff --git a/settings/authentication.mdx b/settings/authentication.mdx
index 35bb3eddc..df2d8b2bf 100644
--- a/settings/authentication.mdx
+++ b/settings/authentication.mdx
@@ -4,92 +4,151 @@ description: "Customize how your team can login to your Mintlify dashboard"
icon: 'user-unlock'
---
-Mintlify supports single sign-on to your dashboard via SAML and OIDC. If you use Okta or Google Workspace, we have provider-specific documentation for setting up SSO, but if you use another provider, please contact us!
+## Overview
+
+Mintlify provides enterprise-grade single sign-on (SSO) capabilities through both SAML and OpenID Connect (OIDC) protocols. We currently offer native integration with Okta and Google Workspace, with support for other identity providers available upon request.
SSO functionality is available on our Enterprise plan. [Contact
us](https://mintlify.com/enterprise) to learn more!
-## Okta
-
-
-
-
-
- Under `Applications`, click to create a new app integration using SAML 2.0.
-
-
- Enter the following:
- * Single sign-on URL (provided by Mintlify)
- * Audience URI (provided by Mintlify)
- * Name ID Format: `EmailAddress`
- * Attribute Statements:
- | Name | Name format | Value
- | ---- | ----------- | -----
- | `firstName` | Basic | `user.firstName` |
- | `lastName` | Basic | `user.lastName` |
-
-
- Once the application is set up, navigate to the sign-on tab and send us the metadata URL.
- We'll enable the connection from our side using this information.
-
-
-
-
-
-
- Under `Applications`, click to create a new app integration using OIDC.
- You should choose the `Web Application` application type.
-
-
- Select the authorization code grant type and enter the Redirect URI provided by Mintlify.
-
-
- Once the application is set up, navigate to the General tab and locate the client ID & client secret.
- Please securely provide us with these, along with your Okta instance URL (e.g. `.okta.com`). You can send these via a service like 1Password or SendSafely.
-
-
-
-
-
-## Google Workspace
-
-
-
-
-
- Under `Web and mobile apps`, select `Add custom SAML app` from the `Add app` dropdown.
-
- 
-
-
-
- Copy the provided SSO URL, Entity ID, and x509 certificate and send it to the Mintlify team.
-
- 
-
-
-
- On the Service provider details page, enter the following:
- * ACS URL (provided by Mintlify)
- * Entity ID (provided by Mintlify)
- * Name ID format: `EMAIL`
- * Name ID: `Basic Information > Primary email`
-
-
- 
-
-
- On the next page, enter the following attribute statements:
- | Google Directory Attribute | App Attribute |
- | -------------------------- | ------------- |
- | `First name` | `firstName` |
- | `Last name` | `lastName` |
-
- Once this step is complete and users are assigned to the application, let our team know and we'll enable SSO for your account!
-
-
-
-
-
+## Okta Integration
+
+Configure SSO with Okta using either SAML 2.0 or OpenID Connect (OIDC). Each protocol has its own setup process and requirements.
+
+### Okta SAML Setup
+
+Follow these steps to configure SAML SSO with Okta:
+
+
+
+ 1. Log in to your Okta admin dashboard
+ 2. Navigate to `Applications`
+ 3. Click to create a new app integration
+ 4. Select `SAML 2.0` as the sign-on method
+
+
+
+ Configure the following required fields:
+
+
+ Enter the URL provided by Mintlify
+
+
+
+ Enter the URI provided by Mintlify
+
+
+
+ Set to `EmailAddress`
+
+
+ Configure the following attribute statements:
+ | Name | Name format | Value |
+ | ---- | ----------- | ----- |
+ | `firstName` | Basic | `user.firstName` |
+ | `lastName` | Basic | `user.lastName` |
+
+
+
+ 1. Navigate to the sign-on tab
+ 2. Locate the metadata URL
+ 3. Send the metadata URL to Mintlify
+ 4. We will enable the connection from our side
+
+
+
+### Okta OIDC Setup
+
+Follow these steps to configure OIDC SSO with Okta:
+
+
+
+ 1. Log in to your Okta admin dashboard
+ 2. Navigate to `Applications`
+ 3. Click to create a new app integration
+ 4. Select `OIDC - OpenID Connect`
+ 5. Choose `Web Application` as the application type
+
+
+
+ 1. Select the authorization code grant type
+ 2. Enter the Redirect URI provided by Mintlify
+
+
+
+ Securely share the following credentials via 1Password or SendSafely:
+ - Client ID
+ - Client Secret
+ - Okta instance URL (e.g., `your-tenant-name.okta.com`)
+
+
+
+## Google Workspace Integration
+
+### Google Workspace SAML Setup
+
+Follow these steps to configure SAML SSO with Google Workspace:
+
+
+
+ 1. Access your Google Admin console
+ 2. Navigate to `Web and mobile apps`
+ 3. Click the `Add app` dropdown
+ 4. Select `Add custom SAML app`
+
+
+ 
+
+
+
+
+ Gather the following credentials to send to Mintlify:
+ - SSO URL
+ - Entity ID
+ - x509 certificate
+
+
+ 
+
+
+
+
+ Enter the following settings in the Service Provider Details page:
+
+
+ Enter the URL provided by Mintlify
+
+
+
+ Enter the ID provided by Mintlify
+
+
+
+ Set to `EMAIL`
+
+
+
+ Set to `Basic Information > Primary email`
+
+
+
+ 
+
+
+
+
+ Set up the following attribute mappings:
+ | Google Directory Attribute | App Attribute |
+ | -------------------------- | ------------- |
+ | `First name` | `firstName` |
+ | `Last name` | `lastName` |
+
+ Once you've completed the configuration and assigned users to the application, contact Mintlify support to enable the integration.
+
+
+
+## Additional Providers
+
+While we offer native support for Okta and Google Workspace, we can integrate with any identity provider that supports standard SAML 2.0 or OpenID Connect protocols. Contact our support team to discuss integrating with your preferred identity provider.
\ No newline at end of file
diff --git a/web-editor.mdx b/web-editor.mdx
index 0c945d94b..050e19206 100644
--- a/web-editor.mdx
+++ b/web-editor.mdx
@@ -3,111 +3,87 @@ title: 'Web Editor'
description: 'Edit your docs directly from the dashboard with live previews.'
---
-Web Editor is the preferred way to edit docs directly without having to open your IDE or run `mintlify dev`.
+## Introduction to Web Editor
-The editor includes a few key features to integrate directly into your existing git workflow,
-like creating branches, pull requests, commits, and diffs for your current changes.
+The Web Editor is a powerful tool that lets you edit your documentation directly through your browser, eliminating the need to open your IDE or run `mintlify dev` locally.
-It also includes a fully editable experience for changing and adding content directly,
-even with custom components.
+### Key Features
-If you understand git workflows and our integrations already, you can skip to [here](#editing-content).
+- Real-time preview of your changes as you type
+- Direct integration with your git workflow (branches, commits, PRs)
+- Visual and source code editing modes
+- Support for all Mintlify components and markdown features
-## Git and update workflows
+## Git Workflow Integration
-### Git basics
+### Understanding Git Basics
-While Web Editor means you don't need to go to GitHub or your command line to make
-changes, it's still helpful to know the basics of git.
+While the Web Editor simplifies the git workflow, it's helpful to understand these key concepts:
-Git terminology:
+- **Repository**: Your code's central storage location (local or remote)
+- **Commit**: A snapshot of your changes
+- **Branch**: A separate development line for safely making changes
+- **Pull Request**: A request to merge changes from one branch to another
-- **Repository**: The folder in which your code lives. It can be local (on your computer) or remote (like GitHub).
-
-- **Commit**: A snapshot of changes made to files in the repository.
-
-- **Branch**: A separate line of development. It's a working copy of the code that allows you to work on changes without affecting the main version.
-
-- **Pull request:** A request to merge changes from a working branch into the main branch. This is used for reviewing content before making changes live.
-
-### Making updates
-
-In order to make updates to your docs, we include a few buttons specifically to
-integrate with your git workflow.
+### Required Setup
- If you haven't done so already, please install the Mintlify GitHub app to your GitHub account.
- You can find [documentation here](#1-deploying-your-docs-repository), or you can install
- the app in the [GitHub App page](https://dashboard.mintlify.com/settings/organization/github-app)
- page of the dashboard.
+ Before using the Web Editor, install the Mintlify GitHub app to your account. You can do this through the [GitHub App page](https://dashboard.mintlify.com/settings/organization/github-app) in your dashboard.
-
-
- In order to make changes to your docs, you might want to change from the main branch
- to avoid publishing directly to your main docs site.
+## Making Documentation Changes
- To do this, you can open the branches modal on the top left of the editor.
+Follow these steps to make and publish changes to your documentation:
+
+
+ Start by selecting or creating a new branch to work on:
+
+ 1. Open the branches modal in the top left
+ 2. Choose an existing branch or click "New Branch"
+ 3. Enter a descriptive name for your new branch
+
- From here, you can either switch to a different git branch than `main`, or you can
- create a new branch by clicking the **"New Branch"** button.
-
-
- 
- 
-
-
- After you create a new branch, you'll automatically be switched, and all changes
- you make will be made to this new branch until you change branches again or reload the page.
-
- By default, when you load the page again, you'll default to the main branch.
-
- As a best practice, you should always create a new branch to make changes so you can submit a pull request for review by other teammates. You also may not have permissions to make changes to the main branch, in which case we'll try to open a pull request for you.
+ Always create a new branch for changes to enable review through pull requests. This is especially important if you don't have direct write access to the main branch.
-
- In order to make a commit, you have two options, both of which appear on the top
- right of the editor:
+
+ How you save changes depends on your current branch:
-
- If you're on the main branch of your docs repository, you can push a commit
- directly to the repo by clicking the **"Publish"** button. You'll see your changes
- reflect in your git branch the next time you run `git pull`.
-
+
+ Use the **"Publish"** button to push changes directly:
+
-
- If you're not on the main branch, you can push a commit to your branch by clicking
- on the **"Save Changes"** button. If you're ready to publish a pull request to put your branch
- up for review, you can click the **"Publish Pull Request"** button.
-
+
+ You have two options:
+ 1. **"Save Changes"** - Commits to your current branch
+ 2. **"Publish Pull Request"** - Creates a PR for review
+
-
- This will create the pull request for you on GitHub using the branch you selected onto
- your main branch.
-
- If you do put your pull request up for review, you can edit the title and description
- of the PR, but a default Mintlify title will be provided for you if you leave it
- empty.
+
+ When creating a pull request:
+ 1. Enter a descriptive title (or use our auto-generated one)
+ 2. Add details about your changes in the description
+ 3. Submit for team review
@@ -116,31 +92,29 @@ integrate with your git workflow.
-## Editing content
+## Content Creation Tools
-### Slash commands
+### Using Slash Commands
-The easiest way to add content in the editor is by using **"Slash commands"**, which are
-commands you have access to after typing `/` in the **"Visual Editor"** mode:
+The slash command menu is your primary tool for adding content. Access it by typing `/` in Visual Editor mode.
-As you type, you'll see more options pop up:
+The menu filters as you type to help find specific components:
-
+
-#### Content blocks
-
-Here are the types of content blocks available to add in the **"Visual Editor"**:
+### Available Content Blocks
-
+
+ Basic building blocks for your documentation:
Paragraph
Headings
@@ -152,7 +126,8 @@ Here are the types of content blocks available to add in the **"Visual Editor"**
-
+
+ Enhanced documentation components:
Callouts
Accordions
@@ -169,113 +144,126 @@ Here are the types of content blocks available to add in the **"Visual Editor"**
-### Adding images
-
-You can add images to your page by typing `/image` and either clicking on the **"Image"**
-option or hitting ↓ + Enter on the **"Image"** option.
+## Working with Images
-This will open up the image modal where you have the option to either upload a new
-image or use an existing image from the repo.
+### Adding New Images
-
- 
- 
-
+
+
+ Type `/image` and select the Image option (or use ↓ + Enter)
+
+
+
+ The image modal offers two options:
+ 1. Upload a new image
+ 2. Select an existing image
-Uploading an image can be done through the modal:
+
+
+
+
+
-
- 
- 
-
+
+ For new images:
+
+
+
+
+
+
-And you can preview an existing image before you add it.
+
+ Review existing images before insertion:
+
+
+ 
+ 
+
+
+
-
-
-
-
+### Modifying Images
-### Editing images
+To edit an existing image:
-In order to edit images, you just have to hover over the image to see the **"Delete"**
-and **"Edit"** buttons on the top right of the image.
+1. Hover over the image to reveal controls
+2. Use the **"Delete"** or **"Edit"** buttons
-Clicking the **"Edit"** button lets you edit the attributes of the image.
+The edit form lets you modify image attributes:
-If you want to update the source of an image to be a new image that you haven't yet
-uploaded, you have to first delete the image you're changing, and then add a new one
-using the [instructions above](#adding-images).
+
+ To replace an image file, you'll need to delete the existing image and add a new one using the process above.
+
-## Editor modes
+## Editor View Modes
-In order to offer the most flexibility, the editor has three modes:
+The editor offers three distinct viewing modes to suit different editing needs:
-
+
-### Visual Editor
-
-The **"Visual Editor"** is the typical WYSIWYG mode you'd see in something like Notion.
-It offers you a view into your docs in a fully editable way that reflects what the final
-page would look like on your main docs site.
-
-### Source Editor
-
-The **"Source Editor"** offers you a way to edit your MDX files in code, the same way
-you'd do in your IDE. This offers less flexibility, in that our components aren't available
-for auto-complete, but it does have two unique advantages.
-
-1. It allows you to edit props of components (see our [limitations below](#current-limitations))
-which is currently not available in **"Visual Editor"** mode yet.
+### Visual Editor Mode
-2. It allows you to correct syntax errors which might've appeared in your repo that
-might not be compatible with **"Visual Editor"** mode until you've fixed them.
+A WYSIWYG (What You See Is What You Get) interface that shows your content exactly as it will appear on your docs site. Ideal for:
+- Writing and editing content
+- Adding components
+- Visualizing the final result
-### Diff View
+### Source Editor Mode
-The **"Diff View"** is a way to view the changes made to a specific document before
-committing it to your repository.
+A code-based interface for direct MDX editing. Best for:
+- Editing component properties
+- Fixing syntax issues
+- Advanced customization
-This will help you see changes you've made along with formatting changes made by
-the editor.
+### Diff View Mode
-## Current limitations
+Shows changes between your current version and the last saved version. Useful for:
+- Reviewing changes before committing
+- Understanding formatting updates
+- Catching unintended modifications
-We do have a few current limitations in the editor that we're working to resolve.
+## Current Limitations
-
- You currently cannot live-update your navigation based on added/edited files. You
- still have to manually edit renamed, added, and deleted files in your `mint.json`
+
+ The editor doesn't support live navigation tree updates. Manual `mint.json` edits are required for:
+ - Adding new files
+ - Renaming files
+ - Removing files
-
- We currently don't show any previews for custom snippets. This is on our roadmap to support
- as fully editable components.
+
+ Custom snippet preview functionality is in development. Will include:
+ - Live preview support
+ - Full component editing
-
- We currently don't show any previews for OpenAPI specs. This is on our roadmap to support
- as a read-only preview.
+
+ OpenAPI specification preview support is planned, featuring:
+ - Read-only preview mode
+ - Endpoint visualization
-## Feedback
+## Getting Help
-If you have any bug reports, feature requests, or other general feedback, we'd love to hear
-where we can improve.
+We value your feedback and are constantly improving the Web Editor. For:
+- Bug reports
+- Feature requests
+- General feedback
-Email us at [support@mintlify.com](mailto:support@mintlify.com)
\ No newline at end of file
+Contact us at [support@mintlify.com](mailto:support@mintlify.com)
\ No newline at end of file