diff --git a/advanced/features-guide.mdx b/advanced/features-guide.mdx new file mode 100644 index 00000000..60457311 --- /dev/null +++ b/advanced/features-guide.mdx @@ -0,0 +1,576 @@ +# Advanced Mintlify Features Guide + +Welcome to the comprehensive guide for advanced Mintlify features. This guide is designed for developers who want to maximize their documentation implementation and create exceptional user experiences. + +## Advanced API Playground Features + +### Complex Data Types + +The API Playground supports sophisticated data structures beyond simple strings and numbers: + +```json +{ + "user": { + "profile": { + "name": "John Doe", + "preferences": { + "theme": "dark", + "notifications": ["email", "push"], + "settings": { + "autoSave": true, + "timeout": 30000 + } + } + }, + "metadata": { + "tags": ["premium", "beta-tester"], + "customFields": { + "department": "Engineering", + "level": "senior" + } + } + } +} +``` + +### SDK Code Examples + +Generate SDK examples in multiple languages automatically: + +```yaml +api: + playground: + mode: "simple" + sdkExamples: + - language: "javascript" + label: "Node.js" + - language: "python" + label: "Python" + - language: "curl" + label: "cURL" + - language: "go" + label: "Go" +``` + +### Multiple Response Examples + +Showcase different response scenarios: + +```mdx + +```json Success Response +{ + "status": "success", + "data": { + "id": "user_123", + "created": "2024-01-15T10:30:00Z" + } +} +``` + +```json Error Response +{ + "status": "error", + "code": "VALIDATION_ERROR", + "message": "Invalid email format", + "details": { + "field": "email", + "value": "invalid-email" + } +} +``` + +``` + +### Custom Authentication + +Configure advanced authentication methods: + +```yaml +api: + auth: + method: "oauth2" + flows: + authorizationCode: + authorizationUrl: "https://api.example.com/oauth/authorize" + tokenUrl: "https://api.example.com/oauth/token" + scopes: + read: "Read access" + write: "Write access" + admin: "Administrative access" +``` + +## Content Customization + +### React Components + +Integrate custom React components for enhanced interactivity: + +```mdx +import { CustomChart } from '/components/CustomChart'; +import { InteractiveDemo } from '/components/InteractiveDemo'; + + + + +``` + +### Reusable Snippets + +Create reusable content blocks: + +```mdx + + + +``` + +Create snippet files in your `snippets/` directory: + +```mdx + +## Authentication Setup + +To authenticate your requests, include your API key in the header: + +```bash +curl -H "Authorization: Bearer YOUR_API_KEY" \ + https://api.example.com/v1/endpoint +``` +``` + +### Custom Scripts and Styling + +Add custom functionality with scripts and CSS: + +```yaml +# mint.json +customization: + scripts: + - src: "/scripts/analytics.js" + async: true + - src: "/scripts/custom-widgets.js" + defer: true + css: + - "/styles/custom.css" + - "/styles/dark-theme.css" +``` + +## Advanced Navigation + +### Tab Groups + +Organize related content with tabs: + +```mdx + + + ```javascript + const client = new APIClient({ + apiKey: 'your-api-key', + baseURL: 'https://api.example.com' + }); + ``` + + + + ```python + client = APIClient( + api_key='your-api-key', + base_url='https://api.example.com' + ) + ``` + + + + ```go + client := &APIClient{ + APIKey: "your-api-key", + BaseURL: "https://api.example.com", + } + ``` + + +``` + +### Anchor Navigation + +Create smooth navigation with anchors: + +```yaml +# mint.json +anchors: + - name: "API Reference" + icon: "code" + url: "/api-reference" + - name: "SDKs" + icon: "puzzle-piece" + url: "/sdks" + - name: "Changelog" + icon: "list" + url: "/changelog" + - name: "Community" + icon: "discord" + url: "https://discord.gg/your-server" +``` + +### Dropdown Menus + +Organize complex navigation structures: + +```yaml +navigation: + - group: "Getting Started" + pages: + - "quickstart" + - "authentication" + - group: "API Reference" + pages: + - group: "Users" + pages: + - "api-reference/users/create" + - "api-reference/users/get" + - "api-reference/users/update" + - "api-reference/users/delete" + - group: "Organizations" + pages: + - "api-reference/orgs/create" + - "api-reference/orgs/list" +``` + +### Version Management + +Handle multiple API versions: + +```yaml +versions: + - "v2.0" + - "v1.0" + +navigation: + - group: "API Reference (v2.0)" + version: "v2.0" + pages: + - "api-reference/v2/users" + - "api-reference/v2/organizations" + - group: "API Reference (v1.0)" + version: "v1.0" + pages: + - "api-reference/v1/users" + - "api-reference/v1/organizations" +``` + +### Multi-language Support + +Configure multiple language versions: + +```yaml +# mint.json +languages: + - "en" + - "es" + - "fr" + - "de" + +navigation: + - group: "Getting Started" + pages: + - "quickstart" + - "authentication" + translations: + es: "Comenzando" + fr: "Pour Commencer" + de: "Erste Schritte" +``` + +## Authentication and Personalization Features + +### User Authentication Integration + +```yaml +# mint.json +auth: + enabled: true + providers: + - name: "github" + clientId: "your-github-client-id" + - name: "google" + clientId: "your-google-client-id" + redirects: + signIn: "/dashboard" + signOut: "/" +``` + +### Personalized Content + +Show different content based on user authentication: + +```mdx + + + Welcome back! Here's your personalized dashboard. + + + + + + + + Please sign in to access personalized features. + + +``` + +### Role-based Content + +Display content based on user roles: + +```mdx + + ## Admin Features + + This section is only visible to administrators and editors. + + + +``` + +## Advanced Integrations + +### Analytics Integration + +Track user engagement and documentation performance: + +```yaml +# mint.json +integrations: + analytics: + googleAnalytics: "GA_MEASUREMENT_ID" + mixpanel: "MIXPANEL_TOKEN" + amplitude: "AMPLITUDE_API_KEY" + posthog: + apiKey: "POSTHOG_API_KEY" + host: "https://app.posthog.com" +``` + +### Custom Analytics Events + +```javascript +// Track custom events +mintlify.track('api_playground_used', { + endpoint: '/api/v1/users', + method: 'POST', + success: true +}); + +mintlify.track('documentation_search', { + query: 'authentication', + results_count: 12, + clicked_result: 'authentication-guide' +}); +``` + +### SDK Generation + +Automatically generate and maintain SDKs: + +```yaml +# mint.json +sdks: + - language: "typescript" + repository: "https://github.com/your-org/typescript-sdk" + package: "@your-org/api-client" + - language: "python" + repository: "https://github.com/your-org/python-sdk" + package: "your-org-api" + - language: "go" + repository: "https://github.com/your-org/go-sdk" + package: "github.com/your-org/go-api-client" +``` + +### Support Widget Integration + +Add support widgets and feedback systems: + +```yaml +# mint.json +integrations: + support: + intercom: + appId: "your-intercom-app-id" + hideDefaultLauncher: false + zendesk: + subdomain: "your-subdomain" + widgetKey: "your-widget-key" + crisp: + websiteId: "your-website-id" +``` + +### Custom Feedback Collection + +```mdx + +``` + +## Recently Added Features + +### AI Content Ingestion + +Leverage AI to automatically generate and update documentation: + +```yaml +# mint.json +ai: + ingestion: + enabled: true + sources: + - type: "codebase" + path: "./src" + languages: ["typescript", "python"] + - type: "openapi" + spec: "./openapi.yaml" + - type: "postman" + collection: "./postman-collection.json" + schedule: "daily" + autoUpdate: true +``` + +### Model Context Protocol (MCP) Servers + +Integrate with MCP servers for enhanced AI capabilities: + +```yaml +# mint.json +mcp: + servers: + - name: "documentation-assistant" + transport: "stdio" + command: "node" + args: ["./mcp-server.js"] + capabilities: + - "resources" + - "tools" + - "prompts" +``` + +### Advanced Translation Features + +Automated translation with human review workflow: + +```yaml +# mint.json +translations: + enabled: true + provider: "deepl" # or "google", "azure" + apiKey: "your-translation-api-key" + workflow: + autoTranslate: true + humanReview: true + reviewers: + es: ["reviewer@example.com"] + fr: ["reviewer-fr@example.com"] + excludePatterns: + - "code" + - "api-reference/**" +``` + +### Custom Themes and Branding + +Create unique visual experiences: + +```yaml +# mint.json +theme: + custom: true + primary: "#6366f1" + secondary: "#8b5cf6" + accent: "#06b6d4" + background: { + light: "#ffffff", + dark: "#0f172a" + } + typography: + headings: "Inter" + body: "Inter" + code: "JetBrains Mono" + components: + button: + borderRadius: "8px" + shadow: "lg" + card: + borderRadius: "12px" + border: "subtle" +``` + +### Advanced Search Features + +Enhanced search with filters and facets: + +```yaml +# mint.json +search: + enhanced: true + features: + - "faceted" + - "autocomplete" + - "typo-tolerance" + - "semantic" + filters: + - name: "content-type" + values: ["guide", "api-reference", "tutorial"] + - name: "difficulty" + values: ["beginner", "intermediate", "advanced"] + indexing: + customFields: + - "author" + - "lastUpdated" + - "tags" +``` + +## Best Practices and Tips + +### Performance Optimization + +- Use lazy loading for heavy components +- Optimize images and media files +- Implement proper caching strategies +- Monitor Core Web Vitals + +### Content Strategy + +- Maintain consistent voice and tone +- Use progressive disclosure for complex topics +- Include interactive examples where possible +- Regular content audits and updates + +### User Experience + +- Implement clear navigation hierarchies +- Provide multiple ways to find information +- Use consistent design patterns +- Test across different devices and browsers + +## Getting Help + +For detailed implementation guidance: + +- [Mintlify Documentation](https://mintlify.com/docs) +- [Community Discord](https://discord.gg/mintlify) +- [GitHub Issues](https://github.com/mintlify/mint/issues) +- [Support Email](mailto:support@mintlify.com) + +--- + +*This guide covers advanced features available in Mintlify. Some features may require specific pricing plans or beta access. Check the [pricing page](https://mintlify.com/pricing) for current feature availability.* \ No newline at end of file diff --git a/docs.json b/docs.json index c726773d..5af7b9d7 100644 --- a/docs.json +++ b/docs.json @@ -91,14 +91,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", @@ -130,6 +130,7 @@ "advanced/subpath/vercel" ] }, + "advanced/features-guide", { "group": "Dashboard Access", "icon": "gauge", @@ -137,7 +138,6 @@ "advanced/dashboard/sso", "advanced/dashboard/permissions", "advanced/dashboard/roles" - ] }, "contact-support" @@ -197,7 +197,7 @@ { "group": "Version Control and CI/CD", "pages": [ - "settings/github", + "settings/github", "settings/gitlab", "settings/ci", "settings/preview-deployments"