├── LICENSE ├── README.md ├── ai-tools ├── claude-code.mdx ├── cursor.mdx └── windsurf.mdx ├── api-reference ├── endpoint │ ├── create.mdx │ ├── delete.mdx │ ├── get.mdx │ └── webhook.mdx ├── introduction.mdx └── openapi.json ├── development.mdx ├── docs.json ├── essentials ├── code.mdx ├── images.mdx ├── markdown.mdx ├── navigation.mdx ├── reusable-snippets.mdx └── settings.mdx ├── favicon.svg ├── images ├── checks-passed.png ├── hero-dark.png └── hero-light.png ├── index.mdx ├── logo ├── dark.svg └── light.svg ├── quickstart.mdx └── snippets └── snippet-intro.mdx /LICENSE: -------------------------------------------------------------------------------- 1 | MIT License 2 | 3 | Copyright (c) 2023 Mintlify 4 | 5 | Permission is hereby granted, free of charge, to any person obtaining a copy 6 | of this software and associated documentation files (the "Software"), to deal 7 | in the Software without restriction, including without limitation the rights 8 | to use, copy, modify, merge, publish, distribute, sublicense, and/or sell 9 | copies of the Software, and to permit persons to whom the Software is 10 | furnished to do so, subject to the following conditions: 11 | 12 | The above copyright notice and this permission notice shall be included in all 13 | copies or substantial portions of the Software. 14 | 15 | THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR 16 | IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, 17 | FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE 18 | AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER 19 | LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, 20 | OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE 21 | SOFTWARE. -------------------------------------------------------------------------------- /README.md: -------------------------------------------------------------------------------- 1 | # Mintlify Starter Kit 2 | 3 | Use the starter kit to get your docs deployed and ready to customize. 4 | 5 | Click the green **Use this template** button at the top of this repo to copy the Mintlify starter kit. The starter kit contains examples with 6 | 7 | - Guide pages 8 | - Navigation 9 | - Customizations 10 | - API reference pages 11 | - Use of popular components 12 | 13 | **[Follow the full quickstart guide](https://starter.mintlify.com/quickstart)** 14 | 15 | ## Development 16 | 17 | Install the [Mintlify CLI](https://www.npmjs.com/package/mint) to preview your documentation changes locally. To install, use the following command: 18 | 19 | ``` 20 | npm i -g mint 21 | ``` 22 | 23 | Run the following command at the root of your documentation, where your `docs.json` is located: 24 | 25 | ``` 26 | mint dev 27 | ``` 28 | 29 | View your local preview at `http://localhost:3000`. 30 | 31 | ## Publishing changes 32 | 33 | Install our GitHub app from your [dashboard](https://dashboard.mintlify.com/settings/organization/github-app) to propagate changes from your repo to your deployment. Changes are deployed to production automatically after pushing to the default branch. 34 | 35 | ## Need help? 36 | 37 | ### Troubleshooting 38 | 39 | - If your dev environment isn't running: Run `mint update` to ensure you have the most recent version of the CLI. 40 | - If a page loads as a 404: Make sure you are running in a folder with a valid `docs.json`. 41 | 42 | ### Resources 43 | - [Mintlify documentation](https://mintlify.com/docs) 44 | -------------------------------------------------------------------------------- /ai-tools/claude-code.mdx: -------------------------------------------------------------------------------- 1 | --- 2 | title: "Claude Code setup" 3 | description: "Configure Claude Code for your documentation workflow" 4 | icon: "asterisk" 5 | --- 6 | 7 | Claude Code is Anthropic's official CLI tool. This guide will help you set up Claude Code to help you write and maintain your documentation. 8 | 9 | ## Prerequisites 10 | 11 | - Active Claude subscription (Pro, Max, or API access) 12 | 13 | ## Setup 14 | 15 | 1. Install Claude Code globally: 16 | 17 | ```bash 18 | npm install -g @anthropic-ai/claude-code 19 | ``` 20 | 21 | 2. Navigate to your docs directory. 22 | 3. (Optional) Add the `CLAUDE.md` file below to your project. 23 | 4. Run `claude` to start. 24 | 25 | ## Create `CLAUDE.md` 26 | 27 | Create a `CLAUDE.md` file at the root of your documentation repository to train Claude Code on your specific documentation standards: 28 | 29 | ````markdown 30 | # Mintlify documentation 31 | 32 | ## Working relationship 33 | - You can push back on ideas-this can lead to better documentation. Cite sources and explain your reasoning when you do so 34 | - ALWAYS ask for clarification rather than making assumptions 35 | - NEVER lie, guess, or make up information 36 | 37 | ## Project context 38 | - Format: MDX files with YAML frontmatter 39 | - Config: docs.json for navigation, theme, settings 40 | - Components: Mintlify components 41 | 42 | ## Content strategy 43 | - Document just enough for user success - not too much, not too little 44 | - Prioritize accuracy and usability of information 45 | - Make content evergreen when possible 46 | - Search for existing information before adding new content. Avoid duplication unless it is done for a strategic reason 47 | - Check existing patterns for consistency 48 | - Start by making the smallest reasonable changes 49 | 50 | ## Frontmatter requirements for pages 51 | - title: Clear, descriptive page title 52 | - description: Concise summary for SEO/navigation 53 | 54 | ## Writing standards 55 | - Second-person voice ("you") 56 | - Prerequisites at start of procedural content 57 | - Test all code examples before publishing 58 | - Match style and formatting of existing pages 59 | - Include both basic and advanced use cases 60 | - Language tags on all code blocks 61 | - Alt text on all images 62 | - Relative paths for internal links 63 | 64 | ## Git workflow 65 | - NEVER use --no-verify when committing 66 | - Ask how to handle uncommitted changes before starting 67 | - Create a new branch when no clear branch exists for changes 68 | - Commit frequently throughout development 69 | - NEVER skip or disable pre-commit hooks 70 | 71 | ## Do not 72 | - Skip frontmatter on any MDX file 73 | - Use absolute URLs for internal links 74 | - Include untested code examples 75 | - Make assumptions - always ask for clarification 76 | ```` 77 | -------------------------------------------------------------------------------- /ai-tools/cursor.mdx: -------------------------------------------------------------------------------- 1 | --- 2 | title: "Cursor setup" 3 | description: "Configure Cursor for your documentation workflow" 4 | icon: "arrow-pointer" 5 | --- 6 | 7 | Use Cursor to help write and maintain your documentation. This guide shows how to configure Cursor for better results on technical writing tasks and using Mintlify components. 8 | 9 | ## Prerequisites 10 | 11 | - Cursor editor installed 12 | - Access to your documentation repository 13 | 14 | ## Project rules 15 | 16 | Create project rules that all team members can use. In your documentation repository root: 17 | 18 | ```bash 19 | mkdir -p .cursor 20 | ``` 21 | 22 | Create `.cursor/rules.md`: 23 | 24 | ````markdown 25 | # Mintlify technical writing rule 26 | 27 | You are an AI writing assistant specialized in creating exceptional technical documentation using Mintlify components and following industry-leading technical writing practices. 28 | 29 | ## Core writing principles 30 | 31 | ### Language and style requirements 32 | 33 | - Use clear, direct language appropriate for technical audiences 34 | - Write in second person ("you") for instructions and procedures 35 | - Use active voice over passive voice 36 | - Employ present tense for current states, future tense for outcomes 37 | - Avoid jargon unless necessary and define terms when first used 38 | - Maintain consistent terminology throughout all documentation 39 | - Keep sentences concise while providing necessary context 40 | - Use parallel structure in lists, headings, and procedures 41 | 42 | ### Content organization standards 43 | 44 | - Lead with the most important information (inverted pyramid structure) 45 | - Use progressive disclosure: basic concepts before advanced ones 46 | - Break complex procedures into numbered steps 47 | - Include prerequisites and context before instructions 48 | - Provide expected outcomes for each major step 49 | - Use descriptive, keyword-rich headings for navigation and SEO 50 | - Group related information logically with clear section breaks 51 | 52 | ### User-centered approach 53 | 54 | - Focus on user goals and outcomes rather than system features 55 | - Anticipate common questions and address them proactively 56 | - Include troubleshooting for likely failure points 57 | - Write for scannability with clear headings, lists, and white space 58 | - Include verification steps to confirm success 59 | 60 | ## Mintlify component reference 61 | 62 | ### Callout components 63 | 64 | #### Note - Additional helpful information 65 | 66 | 67 | Supplementary information that supports the main content without interrupting flow 68 | 69 | 70 | #### Tip - Best practices and pro tips 71 | 72 | 73 | Expert advice, shortcuts, or best practices that enhance user success 74 | 75 | 76 | #### Warning - Important cautions 77 | 78 | 79 | Critical information about potential issues, breaking changes, or destructive actions 80 | 81 | 82 | #### Info - Neutral contextual information 83 | 84 | 85 | Background information, context, or neutral announcements 86 | 87 | 88 | #### Check - Success confirmations 89 | 90 | 91 | Positive confirmations, successful completions, or achievement indicators 92 | 93 | 94 | ### Code components 95 | 96 | #### Single code block 97 | 98 | Example of a single code block: 99 | 100 | ```javascript config.js 101 | const apiConfig = { 102 | baseURL: 'https://api.example.com', 103 | timeout: 5000, 104 | headers: { 105 | 'Authorization': `Bearer ${process.env.API_TOKEN}` 106 | } 107 | }; 108 | ``` 109 | 110 | #### Code group with multiple languages 111 | 112 | Example of a code group: 113 | 114 | 115 | ```javascript Node.js 116 | const response = await fetch('/api/endpoint', { 117 | headers: { Authorization: `Bearer ${apiKey}` } 118 | }); 119 | ``` 120 | 121 | ```python Python 122 | import requests 123 | response = requests.get('/api/endpoint', 124 | headers={'Authorization': f'Bearer {api_key}'}) 125 | ``` 126 | 127 | ```curl cURL 128 | curl -X GET '/api/endpoint' \ 129 | -H 'Authorization: Bearer YOUR_API_KEY' 130 | ``` 131 | 132 | 133 | #### Request/response examples 134 | 135 | Example of request/response documentation: 136 | 137 | 138 | ```bash cURL 139 | curl -X POST 'https://api.example.com/users' \ 140 | -H 'Content-Type: application/json' \ 141 | -d '{"name": "John Doe", "email": "john@example.com"}' 142 | ``` 143 | 144 | 145 | 146 | ```json Success 147 | { 148 | "id": "user_123", 149 | "name": "John Doe", 150 | "email": "john@example.com", 151 | "created_at": "2024-01-15T10:30:00Z" 152 | } 153 | ``` 154 | 155 | 156 | ### Structural components 157 | 158 | #### Steps for procedures 159 | 160 | Example of step-by-step instructions: 161 | 162 | 163 | 164 | Run `npm install` to install required packages. 165 | 166 | 167 | Verify installation by running `npm list`. 168 | 169 | 170 | 171 | 172 | Create a `.env` file with your API credentials. 173 | 174 | ```bash 175 | API_KEY=your_api_key_here 176 | ``` 177 | 178 | 179 | Never commit API keys to version control. 180 | 181 | 182 | 183 | 184 | #### Tabs for alternative content 185 | 186 | Example of tabbed content: 187 | 188 | 189 | 190 | ```bash 191 | brew install node 192 | npm install -g package-name 193 | ``` 194 | 195 | 196 | 197 | ```powershell 198 | choco install nodejs 199 | npm install -g package-name 200 | ``` 201 | 202 | 203 | 204 | ```bash 205 | sudo apt install nodejs npm 206 | npm install -g package-name 207 | ``` 208 | 209 | 210 | 211 | #### Accordions for collapsible content 212 | 213 | Example of accordion groups: 214 | 215 | 216 | 217 | - **Firewall blocking**: Ensure ports 80 and 443 are open 218 | - **Proxy configuration**: Set HTTP_PROXY environment variable 219 | - **DNS resolution**: Try using 8.8.8.8 as DNS server 220 | 221 | 222 | 223 | ```javascript 224 | const config = { 225 | performance: { cache: true, timeout: 30000 }, 226 | security: { encryption: 'AES-256' } 227 | }; 228 | ``` 229 | 230 | 231 | 232 | ### Cards and columns for emphasizing information 233 | 234 | Example of cards and card groups: 235 | 236 | 237 | Complete walkthrough from installation to your first API call in under 10 minutes. 238 | 239 | 240 | 241 | 242 | Learn how to authenticate requests using API keys or JWT tokens. 243 | 244 | 245 | 246 | Understand rate limits and best practices for high-volume usage. 247 | 248 | 249 | 250 | ### API documentation components 251 | 252 | #### Parameter fields 253 | 254 | Example of parameter documentation: 255 | 256 | 257 | Unique identifier for the user. Must be a valid UUID v4 format. 258 | 259 | 260 | 261 | User's email address. Must be valid and unique within the system. 262 | 263 | 264 | 265 | Maximum number of results to return. Range: 1-100. 266 | 267 | 268 | 269 | Bearer token for API authentication. Format: `Bearer YOUR_API_KEY` 270 | 271 | 272 | #### Response fields 273 | 274 | Example of response field documentation: 275 | 276 | 277 | Unique identifier assigned to the newly created user. 278 | 279 | 280 | 281 | ISO 8601 formatted timestamp of when the user was created. 282 | 283 | 284 | 285 | List of permission strings assigned to this user. 286 | 287 | 288 | #### Expandable nested fields 289 | 290 | Example of nested field documentation: 291 | 292 | 293 | Complete user object with all associated data. 294 | 295 | 296 | 297 | User profile information including personal details. 298 | 299 | 300 | 301 | User's first name as entered during registration. 302 | 303 | 304 | 305 | URL to user's profile picture. Returns null if no avatar is set. 306 | 307 | 308 | 309 | 310 | 311 | 312 | ### Media and advanced components 313 | 314 | #### Frames for images 315 | 316 | Wrap all images in frames: 317 | 318 | 319 | Main dashboard showing analytics overview 320 | 321 | 322 | 323 | Analytics dashboard with charts 324 | 325 | 326 | #### Videos 327 | 328 | Use the HTML video element for self-hosted video content: 329 | 330 | 335 | 336 | Embed YouTube videos using iframe elements: 337 | 338 | 346 | 347 | #### Tooltips 348 | 349 | Example of tooltip usage: 350 | 351 | 352 | API 353 | 354 | 355 | #### Updates 356 | 357 | Use updates for changelogs: 358 | 359 | 360 | ## New features 361 | - Added bulk user import functionality 362 | - Improved error messages with actionable suggestions 363 | 364 | ## Bug fixes 365 | - Fixed pagination issue with large datasets 366 | - Resolved authentication timeout problems 367 | 368 | 369 | ## Required page structure 370 | 371 | Every documentation page must begin with YAML frontmatter: 372 | 373 | ```yaml 374 | --- 375 | title: "Clear, specific, keyword-rich title" 376 | description: "Concise description explaining page purpose and value" 377 | --- 378 | ``` 379 | 380 | ## Content quality standards 381 | 382 | ### Code examples requirements 383 | 384 | - Always include complete, runnable examples that users can copy and execute 385 | - Show proper error handling and edge case management 386 | - Use realistic data instead of placeholder values 387 | - Include expected outputs and results for verification 388 | - Test all code examples thoroughly before publishing 389 | - Specify language and include filename when relevant 390 | - Add explanatory comments for complex logic 391 | - Never include real API keys or secrets in code examples 392 | 393 | ### API documentation requirements 394 | 395 | - Document all parameters including optional ones with clear descriptions 396 | - Show both success and error response examples with realistic data 397 | - Include rate limiting information with specific limits 398 | - Provide authentication examples showing proper format 399 | - Explain all HTTP status codes and error handling 400 | - Cover complete request/response cycles 401 | 402 | ### Accessibility requirements 403 | 404 | - Include descriptive alt text for all images and diagrams 405 | - Use specific, actionable link text instead of "click here" 406 | - Ensure proper heading hierarchy starting with H2 407 | - Provide keyboard navigation considerations 408 | - Use sufficient color contrast in examples and visuals 409 | - Structure content for easy scanning with headers and lists 410 | 411 | ## Component selection logic 412 | 413 | - Use **Steps** for procedures and sequential instructions 414 | - Use **Tabs** for platform-specific content or alternative approaches 415 | - Use **CodeGroup** when showing the same concept in multiple programming languages 416 | - Use **Accordions** for progressive disclosure of information 417 | - Use **RequestExample/ResponseExample** specifically for API endpoint documentation 418 | - Use **ParamField** for API parameters, **ResponseField** for API responses 419 | - Use **Expandable** for nested object properties or hierarchical information 420 | ```` 421 | -------------------------------------------------------------------------------- /ai-tools/windsurf.mdx: -------------------------------------------------------------------------------- 1 | --- 2 | title: "Windsurf setup" 3 | description: "Configure Windsurf for your documentation workflow" 4 | icon: "water" 5 | --- 6 | 7 | Configure Windsurf's Cascade AI assistant to help you write and maintain documentation. This guide shows how to set up Windsurf specifically for your Mintlify documentation workflow. 8 | 9 | ## Prerequisites 10 | 11 | - Windsurf editor installed 12 | - Access to your documentation repository 13 | 14 | ## Workspace rules 15 | 16 | Create workspace rules that provide Windsurf with context about your documentation project and standards. 17 | 18 | Create `.windsurf/rules.md` in your project root: 19 | 20 | ````markdown 21 | # Mintlify technical writing rule 22 | 23 | ## Project context 24 | 25 | - This is a documentation project on the Mintlify platform 26 | - We use MDX files with YAML frontmatter 27 | - Navigation is configured in `docs.json` 28 | - We follow technical writing best practices 29 | 30 | ## Writing standards 31 | 32 | - Use second person ("you") for instructions 33 | - Write in active voice and present tense 34 | - Start procedures with prerequisites 35 | - Include expected outcomes for major steps 36 | - Use descriptive, keyword-rich headings 37 | - Keep sentences concise but informative 38 | 39 | ## Required page structure 40 | 41 | Every page must start with frontmatter: 42 | 43 | ```yaml 44 | --- 45 | title: "Clear, specific title" 46 | description: "Concise description for SEO and navigation" 47 | --- 48 | ``` 49 | 50 | ## Mintlify components 51 | 52 | ### Callouts 53 | 54 | - `` for helpful supplementary information 55 | - `` for important cautions and breaking changes 56 | - `` for best practices and expert advice 57 | - `` for neutral contextual information 58 | - `` for success confirmations 59 | 60 | ### Code examples 61 | 62 | - When appropriate, include complete, runnable examples 63 | - Use `` for multiple language examples 64 | - Specify language tags on all code blocks 65 | - Include realistic data, not placeholders 66 | - Use `` and `` for API docs 67 | 68 | ### Procedures 69 | 70 | - Use `` component for sequential instructions 71 | - Include verification steps with `` components when relevant 72 | - Break complex procedures into smaller steps 73 | 74 | ### Content organization 75 | 76 | - Use `` for platform-specific content 77 | - Use `` for progressive disclosure 78 | - Use `` and `` for highlighting content 79 | - Wrap images in `` components with descriptive alt text 80 | 81 | ## API documentation requirements 82 | 83 | - Document all parameters with `` 84 | - Show response structure with `` 85 | - Include both success and error examples 86 | - Use `` for nested object properties 87 | - Always include authentication examples 88 | 89 | ## Quality standards 90 | 91 | - Test all code examples before publishing 92 | - Use relative paths for internal links 93 | - Include alt text for all images 94 | - Ensure proper heading hierarchy (start with h2) 95 | - Check existing patterns for consistency 96 | ```` 97 | -------------------------------------------------------------------------------- /api-reference/endpoint/create.mdx: -------------------------------------------------------------------------------- 1 | --- 2 | title: 'Create Plant' 3 | openapi: 'POST /plants' 4 | --- 5 | -------------------------------------------------------------------------------- /api-reference/endpoint/delete.mdx: -------------------------------------------------------------------------------- 1 | --- 2 | title: 'Delete Plant' 3 | openapi: 'DELETE /plants/{id}' 4 | --- 5 | -------------------------------------------------------------------------------- /api-reference/endpoint/get.mdx: -------------------------------------------------------------------------------- 1 | --- 2 | title: 'Get Plants' 3 | openapi: 'GET /plants' 4 | --- 5 | -------------------------------------------------------------------------------- /api-reference/endpoint/webhook.mdx: -------------------------------------------------------------------------------- 1 | --- 2 | title: 'New Plant' 3 | openapi: 'WEBHOOK /plant/webhook' 4 | --- 5 | -------------------------------------------------------------------------------- /api-reference/introduction.mdx: -------------------------------------------------------------------------------- 1 | --- 2 | title: 'Introduction' 3 | description: 'Example section for showcasing API endpoints' 4 | --- 5 | 6 | 7 | If you're not looking to build API reference documentation, you can delete 8 | this section by removing the api-reference folder. 9 | 10 | 11 | ## Welcome 12 | 13 | There are two ways to build API documentation: [OpenAPI](https://mintlify.com/docs/api-playground/openapi/setup) and [MDX components](https://mintlify.com/docs/api-playground/mdx/configuration). For the starter kit, we are using the following OpenAPI specification. 14 | 15 | 20 | View the OpenAPI specification file 21 | 22 | 23 | ## Authentication 24 | 25 | All API endpoints are authenticated using Bearer tokens and picked up from the specification file. 26 | 27 | ```json 28 | "security": [ 29 | { 30 | "bearerAuth": [] 31 | } 32 | ] 33 | ``` 34 | -------------------------------------------------------------------------------- /api-reference/openapi.json: -------------------------------------------------------------------------------- 1 | { 2 | "openapi": "3.1.0", 3 | "info": { 4 | "title": "OpenAPI Plant Store", 5 | "description": "A sample API that uses a plant store as an example to demonstrate features in the OpenAPI specification", 6 | "license": { 7 | "name": "MIT" 8 | }, 9 | "version": "1.0.0" 10 | }, 11 | "servers": [ 12 | { 13 | "url": "http://sandbox.mintlify.com" 14 | } 15 | ], 16 | "security": [ 17 | { 18 | "bearerAuth": [] 19 | } 20 | ], 21 | "paths": { 22 | "/plants": { 23 | "get": { 24 | "description": "Returns all plants from the system that the user has access to", 25 | "parameters": [ 26 | { 27 | "name": "limit", 28 | "in": "query", 29 | "description": "The maximum number of results to return", 30 | "schema": { 31 | "type": "integer", 32 | "format": "int32" 33 | } 34 | } 35 | ], 36 | "responses": { 37 | "200": { 38 | "description": "Plant response", 39 | "content": { 40 | "application/json": { 41 | "schema": { 42 | "type": "array", 43 | "items": { 44 | "$ref": "#/components/schemas/Plant" 45 | } 46 | } 47 | } 48 | } 49 | }, 50 | "400": { 51 | "description": "Unexpected error", 52 | "content": { 53 | "application/json": { 54 | "schema": { 55 | "$ref": "#/components/schemas/Error" 56 | } 57 | } 58 | } 59 | } 60 | } 61 | }, 62 | "post": { 63 | "description": "Creates a new plant in the store", 64 | "requestBody": { 65 | "description": "Plant to add to the store", 66 | "content": { 67 | "application/json": { 68 | "schema": { 69 | "$ref": "#/components/schemas/NewPlant" 70 | } 71 | } 72 | }, 73 | "required": true 74 | }, 75 | "responses": { 76 | "200": { 77 | "description": "plant response", 78 | "content": { 79 | "application/json": { 80 | "schema": { 81 | "$ref": "#/components/schemas/Plant" 82 | } 83 | } 84 | } 85 | }, 86 | "400": { 87 | "description": "unexpected error", 88 | "content": { 89 | "application/json": { 90 | "schema": { 91 | "$ref": "#/components/schemas/Error" 92 | } 93 | } 94 | } 95 | } 96 | } 97 | } 98 | }, 99 | "/plants/{id}": { 100 | "delete": { 101 | "description": "Deletes a single plant based on the ID supplied", 102 | "parameters": [ 103 | { 104 | "name": "id", 105 | "in": "path", 106 | "description": "ID of plant to delete", 107 | "required": true, 108 | "schema": { 109 | "type": "integer", 110 | "format": "int64" 111 | } 112 | } 113 | ], 114 | "responses": { 115 | "204": { 116 | "description": "Plant deleted", 117 | "content": {} 118 | }, 119 | "400": { 120 | "description": "unexpected error", 121 | "content": { 122 | "application/json": { 123 | "schema": { 124 | "$ref": "#/components/schemas/Error" 125 | } 126 | } 127 | } 128 | } 129 | } 130 | } 131 | } 132 | }, 133 | "webhooks": { 134 | "/plant/webhook": { 135 | "post": { 136 | "description": "Information about a new plant added to the store", 137 | "requestBody": { 138 | "description": "Plant added to the store", 139 | "content": { 140 | "application/json": { 141 | "schema": { 142 | "$ref": "#/components/schemas/NewPlant" 143 | } 144 | } 145 | } 146 | }, 147 | "responses": { 148 | "200": { 149 | "description": "Return a 200 status to indicate that the data was received successfully" 150 | } 151 | } 152 | } 153 | } 154 | }, 155 | "components": { 156 | "schemas": { 157 | "Plant": { 158 | "required": [ 159 | "name" 160 | ], 161 | "type": "object", 162 | "properties": { 163 | "name": { 164 | "description": "The name of the plant", 165 | "type": "string" 166 | }, 167 | "tag": { 168 | "description": "Tag to specify the type", 169 | "type": "string" 170 | } 171 | } 172 | }, 173 | "NewPlant": { 174 | "allOf": [ 175 | { 176 | "$ref": "#/components/schemas/Plant" 177 | }, 178 | { 179 | "required": [ 180 | "id" 181 | ], 182 | "type": "object", 183 | "properties": { 184 | "id": { 185 | "description": "Identification number of the plant", 186 | "type": "integer", 187 | "format": "int64" 188 | } 189 | } 190 | } 191 | ] 192 | }, 193 | "Error": { 194 | "required": [ 195 | "error", 196 | "message" 197 | ], 198 | "type": "object", 199 | "properties": { 200 | "error": { 201 | "type": "integer", 202 | "format": "int32" 203 | }, 204 | "message": { 205 | "type": "string" 206 | } 207 | } 208 | } 209 | }, 210 | "securitySchemes": { 211 | "bearerAuth": { 212 | "type": "http", 213 | "scheme": "bearer" 214 | } 215 | } 216 | } 217 | } -------------------------------------------------------------------------------- /development.mdx: -------------------------------------------------------------------------------- 1 | --- 2 | title: 'Development' 3 | description: 'Preview changes locally to update your docs' 4 | --- 5 | 6 | 7 | **Prerequisites**: 8 | - Node.js version 19 or higher 9 | - A docs repository with a `docs.json` file 10 | 11 | 12 | Follow these steps to install and run Mintlify on your operating system. 13 | 14 | 15 | 16 | 17 | ```bash 18 | npm i -g mint 19 | ``` 20 | 21 | 22 | 23 | 24 | Navigate to your docs directory where your `docs.json` file is located, and run the following command: 25 | 26 | ```bash 27 | mint dev 28 | ``` 29 | 30 | A local preview of your documentation will be available at `http://localhost:3000`. 31 | 32 | 33 | 34 | 35 | ## Custom ports 36 | 37 | By default, Mintlify uses port 3000. You can customize the port Mintlify runs on by using the `--port` flag. For example, to run Mintlify on port 3333, use this command: 38 | 39 | ```bash 40 | mint dev --port 3333 41 | ``` 42 | 43 | If you attempt to run Mintlify on a port that's already in use, it will use the next available port: 44 | 45 | ```md 46 | Port 3000 is already in use. Trying 3001 instead. 47 | ``` 48 | 49 | ## Mintlify versions 50 | 51 | Please note that each CLI release is associated with a specific version of Mintlify. If your local preview does not align with the production version, please update the CLI: 52 | 53 | ```bash 54 | npm mint update 55 | ``` 56 | 57 | ## Validating links 58 | 59 | The CLI can assist with validating links in your documentation. To identify any broken links, use the following command: 60 | 61 | ```bash 62 | mint broken-links 63 | ``` 64 | 65 | ## Deployment 66 | 67 | If the deployment is successful, you should see the following: 68 | 69 | 70 | Screenshot of a deployment confirmation message that says All checks have passed. 71 | 72 | 73 | ## Code formatting 74 | 75 | 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. 76 | 77 | ## Troubleshooting 78 | 79 | 80 | 81 | 82 | This may be due to an outdated version of node. Try the following: 83 | 1. Remove the currently-installed version of the CLI: `npm remove -g mint` 84 | 2. Upgrade to Node v19 or higher. 85 | 3. Reinstall the CLI: `npm i -g mint` 86 | 87 | 88 | 89 | 90 | Solution: Go to the root of your device and delete the `~/.mintlify` folder. Then run `mint dev` again. 91 | 92 | 93 | 94 | Curious about what changed in the latest CLI version? Check out the [CLI changelog](https://www.npmjs.com/package/mintlify?activeTab=versions). 95 | -------------------------------------------------------------------------------- /docs.json: -------------------------------------------------------------------------------- 1 | { 2 | "$schema": "https://mintlify.com/docs.json", 3 | "theme": "mint", 4 | "name": "Mint Starter Kit", 5 | "colors": { 6 | "primary": "#16A34A", 7 | "light": "#07C983", 8 | "dark": "#15803D" 9 | }, 10 | "favicon": "/favicon.svg", 11 | "navigation": { 12 | "tabs": [ 13 | { 14 | "tab": "Guides", 15 | "groups": [ 16 | { 17 | "group": "Getting started", 18 | "pages": [ 19 | "index", 20 | "quickstart", 21 | "development" 22 | ] 23 | }, 24 | { 25 | "group": "Customization", 26 | "pages": [ 27 | "essentials/settings", 28 | "essentials/navigation" 29 | ] 30 | }, 31 | { 32 | "group": "Writing content", 33 | "pages": [ 34 | "essentials/markdown", 35 | "essentials/code", 36 | "essentials/images", 37 | "essentials/reusable-snippets" 38 | ] 39 | }, 40 | { 41 | "group": "AI tools", 42 | "pages": [ 43 | "ai-tools/cursor", 44 | "ai-tools/claude-code", 45 | "ai-tools/windsurf" 46 | ] 47 | } 48 | ] 49 | }, 50 | { 51 | "tab": "API reference", 52 | "groups": [ 53 | { 54 | "group": "API documentation", 55 | "pages": [ 56 | "api-reference/introduction" 57 | ] 58 | }, 59 | { 60 | "group": "Endpoint examples", 61 | "pages": [ 62 | "api-reference/endpoint/get", 63 | "api-reference/endpoint/create", 64 | "api-reference/endpoint/delete", 65 | "api-reference/endpoint/webhook" 66 | ] 67 | } 68 | ] 69 | } 70 | ], 71 | "global": { 72 | "anchors": [ 73 | { 74 | "anchor": "Documentation", 75 | "href": "https://mintlify.com/docs", 76 | "icon": "book-open-cover" 77 | }, 78 | { 79 | "anchor": "Blog", 80 | "href": "https://mintlify.com/blog", 81 | "icon": "newspaper" 82 | } 83 | ] 84 | } 85 | }, 86 | "logo": { 87 | "light": "/logo/light.svg", 88 | "dark": "/logo/dark.svg" 89 | }, 90 | "navbar": { 91 | "links": [ 92 | { 93 | "label": "Support", 94 | "href": "mailto:hi@mintlify.com" 95 | } 96 | ], 97 | "primary": { 98 | "type": "button", 99 | "label": "Dashboard", 100 | "href": "https://dashboard.mintlify.com" 101 | } 102 | }, 103 | "contextual": { 104 | "options": [ 105 | "copy", 106 | "view", 107 | "chatgpt", 108 | "claude", 109 | "perplexity", 110 | "mcp", 111 | "cursor", 112 | "vscode" 113 | ] 114 | }, 115 | "footer": { 116 | "socials": { 117 | "x": "https://x.com/mintlify", 118 | "github": "https://github.com/mintlify", 119 | "linkedin": "https://linkedin.com/company/mintlify" 120 | } 121 | } 122 | } 123 | -------------------------------------------------------------------------------- /essentials/code.mdx: -------------------------------------------------------------------------------- 1 | --- 2 | title: 'Code blocks' 3 | description: 'Display inline code and code blocks' 4 | icon: 'code' 5 | --- 6 | 7 | ## Inline code 8 | 9 | To denote a `word` or `phrase` as code, enclose it in backticks (`). 10 | 11 | ``` 12 | To denote a `word` or `phrase` as code, enclose it in backticks (`). 13 | ``` 14 | 15 | ## Code blocks 16 | 17 | Use [fenced code blocks](https://www.markdownguide.org/extended-syntax/#fenced-code-blocks) by enclosing code in three backticks and follow the leading ticks with the programming language of your snippet to get syntax highlighting. Optionally, you can also write the name of your code after the programming language. 18 | 19 | ```java HelloWorld.java 20 | class HelloWorld { 21 | public static void main(String[] args) { 22 | System.out.println("Hello, World!"); 23 | } 24 | } 25 | ``` 26 | 27 | ````md 28 | ```java HelloWorld.java 29 | class HelloWorld { 30 | public static void main(String[] args) { 31 | System.out.println("Hello, World!"); 32 | } 33 | } 34 | ``` 35 | ```` 36 | -------------------------------------------------------------------------------- /essentials/images.mdx: -------------------------------------------------------------------------------- 1 | --- 2 | title: 'Images and embeds' 3 | description: 'Add image, video, and other HTML elements' 4 | icon: 'image' 5 | --- 6 | 7 | 11 | 12 | ## Image 13 | 14 | ### Using Markdown 15 | 16 | The [markdown syntax](https://www.markdownguide.org/basic-syntax/#images) lets you add images using the following code 17 | 18 | ```md 19 | ![title](/path/image.jpg) 20 | ``` 21 | 22 | Note that the image file size must be less than 5MB. Otherwise, we recommend hosting on a service like [Cloudinary](https://cloudinary.com/) or [S3](https://aws.amazon.com/s3/). You can then use that URL and embed. 23 | 24 | ### Using embeds 25 | 26 | To get more customizability with images, you can also use [embeds](/writing-content/embed) to add images 27 | 28 | ```html 29 | 30 | ``` 31 | 32 | ## Embeds and HTML elements 33 | 34 | 44 | 45 |
46 | 47 | 48 | 49 | Mintlify supports [HTML tags in Markdown](https://www.markdownguide.org/basic-syntax/#html). This is helpful if you prefer HTML tags to Markdown syntax, and lets you create documentation with infinite flexibility. 50 | 51 | 52 | 53 | ### iFrames 54 | 55 | Loads another HTML page within the document. Most commonly used for embedding videos. 56 | 57 | ```html 58 | 59 | ``` 60 | -------------------------------------------------------------------------------- /essentials/markdown.mdx: -------------------------------------------------------------------------------- 1 | --- 2 | title: 'Markdown syntax' 3 | description: 'Text, title, and styling in standard markdown' 4 | icon: 'text-size' 5 | --- 6 | 7 | ## Titles 8 | 9 | Best used for section headers. 10 | 11 | ```md 12 | ## Titles 13 | ``` 14 | 15 | ### Subtitles 16 | 17 | Best used for subsection headers. 18 | 19 | ```md 20 | ### Subtitles 21 | ``` 22 | 23 | 24 | 25 | Each **title** and **subtitle** creates an anchor and also shows up on the table of contents on the right. 26 | 27 | 28 | 29 | ## Text formatting 30 | 31 | We support most markdown formatting. Simply add `**`, `_`, or `~` around text to format it. 32 | 33 | | Style | How to write it | Result | 34 | | ------------- | ----------------- | --------------- | 35 | | Bold | `**bold**` | **bold** | 36 | | Italic | `_italic_` | _italic_ | 37 | | Strikethrough | `~strikethrough~` | ~strikethrough~ | 38 | 39 | You can combine these. For example, write `**_bold and italic_**` to get **_bold and italic_** text. 40 | 41 | You need to use HTML to write superscript and subscript text. That is, add `` or `` around your text. 42 | 43 | | Text Size | How to write it | Result | 44 | | ----------- | ------------------------ | ---------------------- | 45 | | Superscript | `superscript` | superscript | 46 | | Subscript | `subscript` | subscript | 47 | 48 | ## Linking to pages 49 | 50 | You can add a link by wrapping text in `[]()`. You would write `[link to google](https://google.com)` to [link to google](https://google.com). 51 | 52 | Links to pages in your docs need to be root-relative. Basically, you should include the entire folder path. For example, `[link to text](/writing-content/text)` links to the page "Text" in our components section. 53 | 54 | Relative links like `[link to text](../text)` will open slower because we cannot optimize them as easily. 55 | 56 | ## Blockquotes 57 | 58 | ### Singleline 59 | 60 | To create a blockquote, add a `>` in front of a paragraph. 61 | 62 | > Dorothy followed her through many of the beautiful rooms in her castle. 63 | 64 | ```md 65 | > Dorothy followed her through many of the beautiful rooms in her castle. 66 | ``` 67 | 68 | ### Multiline 69 | 70 | > Dorothy followed her through many of the beautiful rooms in her castle. 71 | > 72 | > The Witch bade her clean the pots and kettles and sweep the floor and keep the fire fed with wood. 73 | 74 | ```md 75 | > Dorothy followed her through many of the beautiful rooms in her castle. 76 | > 77 | > The Witch bade her clean the pots and kettles and sweep the floor and keep the fire fed with wood. 78 | ``` 79 | 80 | ### LaTeX 81 | 82 | Mintlify supports [LaTeX](https://www.latex-project.org) through the Latex component. 83 | 84 | 8 x (vk x H1 - H2) = (0,1) 85 | 86 | ```md 87 | 8 x (vk x H1 - H2) = (0,1) 88 | ``` 89 | -------------------------------------------------------------------------------- /essentials/navigation.mdx: -------------------------------------------------------------------------------- 1 | --- 2 | title: 'Navigation' 3 | description: 'The navigation field in docs.json defines the pages that go in the navigation menu' 4 | icon: 'map' 5 | --- 6 | 7 | The navigation menu is the list of links on every website. 8 | 9 | You will likely update `docs.json` every time you add a new page. Pages do not show up automatically. 10 | 11 | ## Navigation syntax 12 | 13 | Our navigation syntax is recursive which means you can make nested navigation groups. You don't need to include `.mdx` in page names. 14 | 15 | 16 | 17 | ```json Regular Navigation 18 | "navigation": { 19 | "tabs": [ 20 | { 21 | "tab": "Docs", 22 | "groups": [ 23 | { 24 | "group": "Getting Started", 25 | "pages": ["quickstart"] 26 | } 27 | ] 28 | } 29 | ] 30 | } 31 | ``` 32 | 33 | ```json Nested Navigation 34 | "navigation": { 35 | "tabs": [ 36 | { 37 | "tab": "Docs", 38 | "groups": [ 39 | { 40 | "group": "Getting Started", 41 | "pages": [ 42 | "quickstart", 43 | { 44 | "group": "Nested Reference Pages", 45 | "pages": ["nested-reference-page"] 46 | } 47 | ] 48 | } 49 | ] 50 | } 51 | ] 52 | } 53 | ``` 54 | 55 | 56 | 57 | ## Folders 58 | 59 | Simply put your MDX files in folders and update the paths in `docs.json`. 60 | 61 | For example, to have a page at `https://yoursite.com/your-folder/your-page` you would make a folder called `your-folder` containing an MDX file called `your-page.mdx`. 62 | 63 | 64 | 65 | You cannot use `api` for the name of a folder unless you nest it inside another folder. Mintlify uses Next.js which reserves the top-level `api` folder for internal server calls. A folder name such as `api-reference` would be accepted. 66 | 67 | 68 | 69 | ```json Navigation With Folder 70 | "navigation": { 71 | "tabs": [ 72 | { 73 | "tab": "Docs", 74 | "groups": [ 75 | { 76 | "group": "Group Name", 77 | "pages": ["your-folder/your-page"] 78 | } 79 | ] 80 | } 81 | ] 82 | } 83 | ``` 84 | 85 | ## Hidden pages 86 | 87 | MDX files not included in `docs.json` will not show up in the sidebar but are accessible through the search bar and by linking directly to them. 88 | -------------------------------------------------------------------------------- /essentials/reusable-snippets.mdx: -------------------------------------------------------------------------------- 1 | --- 2 | title: "Reusable snippets" 3 | description: "Reusable, custom snippets to keep content in sync" 4 | icon: "recycle" 5 | --- 6 | 7 | import SnippetIntro from '/snippets/snippet-intro.mdx'; 8 | 9 | 10 | 11 | ## Creating a custom snippet 12 | 13 | **Pre-condition**: You must create your snippet file in the `snippets` directory. 14 | 15 | 16 | Any page in the `snippets` directory will be treated as a snippet and will not 17 | be rendered into a standalone page. If you want to create a standalone page 18 | from the snippet, import the snippet into another file and call it as a 19 | component. 20 | 21 | 22 | ### Default export 23 | 24 | 1. Add content to your snippet file that you want to re-use across multiple 25 | locations. Optionally, you can add variables that can be filled in via props 26 | when you import the snippet. 27 | 28 | ```mdx snippets/my-snippet.mdx 29 | Hello world! This is my content I want to reuse across pages. My keyword of the 30 | day is {word}. 31 | ``` 32 | 33 | 34 | The content that you want to reuse must be inside the `snippets` directory in 35 | order for the import to work. 36 | 37 | 38 | 2. Import the snippet into your destination file. 39 | 40 | ```mdx destination-file.mdx 41 | --- 42 | title: My title 43 | description: My Description 44 | --- 45 | 46 | import MySnippet from '/snippets/path/to/my-snippet.mdx'; 47 | 48 | ## Header 49 | 50 | Lorem impsum dolor sit amet. 51 | 52 | 53 | ``` 54 | 55 | ### Reusable variables 56 | 57 | 1. Export a variable from your snippet file: 58 | 59 | ```mdx snippets/path/to/custom-variables.mdx 60 | export const myName = 'my name'; 61 | 62 | export const myObject = { fruit: 'strawberries' }; 63 | ``` 64 | 65 | 2. Import the snippet from your destination file and use the variable: 66 | 67 | ```mdx destination-file.mdx 68 | --- 69 | title: My title 70 | description: My Description 71 | --- 72 | 73 | import { myName, myObject } from '/snippets/path/to/custom-variables.mdx'; 74 | 75 | Hello, my name is {myName} and I like {myObject.fruit}. 76 | ``` 77 | 78 | ### Reusable components 79 | 80 | 1. Inside your snippet file, create a component that takes in props by exporting 81 | your component in the form of an arrow function. 82 | 83 | ```mdx snippets/custom-component.mdx 84 | export const MyComponent = ({ title }) => ( 85 |
86 |

{title}

87 |

... snippet content ...

88 |
89 | ); 90 | ``` 91 | 92 | 93 | MDX does not compile inside the body of an arrow function. Stick to HTML 94 | syntax when you can or use a default export if you need to use MDX. 95 | 96 | 97 | 2. Import the snippet into your destination file and pass in the props 98 | 99 | ```mdx destination-file.mdx 100 | --- 101 | title: My title 102 | description: My Description 103 | --- 104 | 105 | import { MyComponent } from '/snippets/custom-component.mdx'; 106 | 107 | Lorem ipsum dolor sit amet. 108 | 109 | 110 | ``` 111 | -------------------------------------------------------------------------------- /essentials/settings.mdx: -------------------------------------------------------------------------------- 1 | --- 2 | title: 'Global Settings' 3 | description: 'Mintlify gives you complete control over the look and feel of your documentation using the docs.json file' 4 | icon: 'gear' 5 | --- 6 | 7 | Every Mintlify site needs a `docs.json` file with the core configuration settings. Learn more about the [properties](#properties) below. 8 | 9 | ## Properties 10 | 11 | 12 | Name of your project. Used for the global title. 13 | 14 | Example: `mintlify` 15 | 16 | 17 | 18 | 19 | An array of groups with all the pages within that group 20 | 21 | 22 | The name of the group. 23 | 24 | Example: `Settings` 25 | 26 | 27 | 28 | The relative paths to the markdown files that will serve as pages. 29 | 30 | Example: `["customization", "page"]` 31 | 32 | 33 | 34 | 35 | 36 | 37 | 38 | Path to logo image or object with path to "light" and "dark" mode logo images 39 | 40 | 41 | Path to the logo in light mode 42 | 43 | 44 | Path to the logo in dark mode 45 | 46 | 47 | Where clicking on the logo links you to 48 | 49 | 50 | 51 | 52 | 53 | Path to the favicon image 54 | 55 | 56 | 57 | Hex color codes for your global theme 58 | 59 | 60 | The primary color. Used for most often for highlighted content, section 61 | headers, accents, in light mode 62 | 63 | 64 | The primary color for dark mode. Used for most often for highlighted 65 | content, section headers, accents, in dark mode 66 | 67 | 68 | The primary color for important buttons 69 | 70 | 71 | The color of the background in both light and dark mode 72 | 73 | 74 | The hex color code of the background in light mode 75 | 76 | 77 | The hex color code of the background in dark mode 78 | 79 | 80 | 81 | 82 | 83 | 84 | 85 | Array of `name`s and `url`s of links you want to include in the topbar 86 | 87 | 88 | The name of the button. 89 | 90 | Example: `Contact us` 91 | 92 | 93 | The url once you click on the button. Example: `https://mintlify.com/docs` 94 | 95 | 96 | 97 | 98 | 99 | 100 | 101 | 102 | Link shows a button. GitHub shows the repo information at the url provided including the number of GitHub stars. 103 | 104 | 105 | If `link`: What the button links to. 106 | 107 | If `github`: Link to the repository to load GitHub information from. 108 | 109 | 110 | Text inside the button. Only required if `type` is a `link`. 111 | 112 | 113 | 114 | 115 | 116 | 117 | Array of version names. Only use this if you want to show different versions 118 | of docs with a dropdown in the navigation bar. 119 | 120 | 121 | 122 | An array of the anchors, includes the `icon`, `color`, and `url`. 123 | 124 | 125 | The [Font Awesome](https://fontawesome.com/search?q=heart) icon used to feature the anchor. 126 | 127 | Example: `comments` 128 | 129 | 130 | The name of the anchor label. 131 | 132 | Example: `Community` 133 | 134 | 135 | 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. 136 | 137 | 138 | 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. 139 | 140 | 141 | Used if you want to hide an anchor until the correct docs version is selected. 142 | 143 | 144 | Pass `true` if you want to hide the anchor until you directly link someone to docs inside it. 145 | 146 | 147 | One of: "brands", "duotone", "light", "sharp-solid", "solid", or "thin" 148 | 149 | 150 | 151 | 152 | 153 | 154 | Override the default configurations for the top-most anchor. 155 | 156 | 157 | The name of the top-most anchor 158 | 159 | 160 | Font Awesome icon. 161 | 162 | 163 | One of: "brands", "duotone", "light", "sharp-solid", "solid", or "thin" 164 | 165 | 166 | 167 | 168 | 169 | An array of navigational tabs. 170 | 171 | 172 | The name of the tab label. 173 | 174 | 175 | The start of the URL that marks what pages go in the tab. Generally, this 176 | is the name of the folder you put your pages in. 177 | 178 | 179 | 180 | 181 | 182 | Configuration for API settings. Learn more about API pages at [API Components](/api-playground/demo). 183 | 184 | 185 | The base url for all API endpoints. If `baseUrl` is an array, it will enable for multiple base url 186 | options that the user can toggle. 187 | 188 | 189 | 190 | 191 | 192 | The authentication strategy used for all API endpoints. 193 | 194 | 195 | The name of the authentication parameter used in the API playground. 196 | 197 | If method is `basic`, the format should be `[usernameName]:[passwordName]` 198 | 199 | 200 | The default value that's designed to be a prefix for the authentication input field. 201 | 202 | E.g. If an `inputPrefix` of `AuthKey` would inherit the default input result of the authentication field as `AuthKey`. 203 | 204 | 205 | 206 | 207 | 208 | Configurations for the API playground 209 | 210 | 211 | 212 | Whether the playground is showing, hidden, or only displaying the endpoint with no added user interactivity `simple` 213 | 214 | Learn more at the [playground guides](/api-playground/demo) 215 | 216 | 217 | 218 | 219 | 220 | Enabling this flag ensures that key ordering in OpenAPI pages matches the key ordering defined in the OpenAPI file. 221 | 222 | This behavior will soon be enabled by default, at which point this field will be deprecated. 223 | 224 | 225 | 226 | 227 | 228 | 229 | A string or an array of strings of URL(s) or relative path(s) pointing to your 230 | OpenAPI file. 231 | 232 | Examples: 233 | 234 | ```json Absolute 235 | "openapi": "https://example.com/openapi.json" 236 | ``` 237 | ```json Relative 238 | "openapi": "/openapi.json" 239 | ``` 240 | ```json Multiple 241 | "openapi": ["https://example.com/openapi1.json", "/openapi2.json", "/openapi3.json"] 242 | ``` 243 | 244 | 245 | 246 | 247 | 248 | An object of social media accounts where the key:property pair represents the social media platform and the account url. 249 | 250 | Example: 251 | ```json 252 | { 253 | "x": "https://x.com/mintlify", 254 | "website": "https://mintlify.com" 255 | } 256 | ``` 257 | 258 | 259 | One of the following values `website`, `facebook`, `x`, `discord`, `slack`, `github`, `linkedin`, `instagram`, `hacker-news` 260 | 261 | Example: `x` 262 | 263 | 264 | The URL to the social platform. 265 | 266 | Example: `https://x.com/mintlify` 267 | 268 | 269 | 270 | 271 | 272 | Configurations to enable feedback buttons 273 | 274 | 275 | 276 | Enables a button to allow users to suggest edits via pull requests 277 | 278 | 279 | Enables a button to allow users to raise an issue about the documentation 280 | 281 | 282 | 283 | 284 | 285 | Customize the dark mode toggle. 286 | 287 | 288 | Set if you always want to show light or dark mode for new users. When not 289 | set, we default to the same mode as the user's operating system. 290 | 291 | 292 | 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: 293 | 294 | 295 | ```json Only Dark Mode 296 | "modeToggle": { 297 | "default": "dark", 298 | "isHidden": true 299 | } 300 | ``` 301 | 302 | ```json Only Light Mode 303 | "modeToggle": { 304 | "default": "light", 305 | "isHidden": true 306 | } 307 | ``` 308 | 309 | 310 | 311 | 312 | 313 | 314 | 315 | 316 | A background image to be displayed behind every page. See example with 317 | [Infisical](https://infisical.com/docs) and [FRPC](https://frpc.io). 318 | 319 | -------------------------------------------------------------------------------- /favicon.svg: -------------------------------------------------------------------------------- 1 | 2 | 3 | 4 | 5 | 6 | 7 | 8 | 9 | 10 | 11 | 12 | 13 | 14 | 15 | 16 | 17 | 18 | 19 | 20 | -------------------------------------------------------------------------------- /images/checks-passed.png: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/mintlify/starter/4aea7bd70ef5f744315a5a18e209718a9d9877c5/images/checks-passed.png -------------------------------------------------------------------------------- /images/hero-dark.png: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/mintlify/starter/4aea7bd70ef5f744315a5a18e209718a9d9877c5/images/hero-dark.png -------------------------------------------------------------------------------- /images/hero-light.png: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/mintlify/starter/4aea7bd70ef5f744315a5a18e209718a9d9877c5/images/hero-light.png -------------------------------------------------------------------------------- /index.mdx: -------------------------------------------------------------------------------- 1 | --- 2 | title: "Introduction" 3 | description: "Welcome to the new home for your documentation" 4 | --- 5 | 6 | ## Setting up 7 | 8 | Get your documentation site up and running in minutes. 9 | 10 | 16 | Follow our three step quickstart guide. 17 | 18 | 19 | ## Make it yours 20 | 21 | Design a docs site that looks great and empowers your users. 22 | 23 | 24 | 29 | Edit your docs locally and preview them in real time. 30 | 31 | 36 | Customize the design and colors of your site to match your brand. 37 | 38 | 43 | Organize your docs to help users find what they need and succeed with your product. 44 | 45 | 50 | Auto-generate API documentation from OpenAPI specifications. 51 | 52 | 53 | 54 | ## Create beautiful pages 55 | 56 | Everything you need to create world-class documentation. 57 | 58 | 59 | 64 | Use MDX to style your docs pages. 65 | 66 | 71 | Add sample code to demonstrate how to use your product. 72 | 73 | 78 | Display images and other media. 79 | 80 | 85 | Write once and reuse across your docs. 86 | 87 | 88 | 89 | ## Need inspiration? 90 | 91 | 96 | Browse our showcase of exceptional documentation sites. 97 | 98 | -------------------------------------------------------------------------------- /logo/dark.svg: -------------------------------------------------------------------------------- 1 | 2 | 3 | 4 | 5 | 6 | 7 | 8 | 9 | 10 | 11 | 12 | 13 | 14 | 15 | 16 | 17 | 18 | 19 | 20 | 21 | 22 | -------------------------------------------------------------------------------- /logo/light.svg: -------------------------------------------------------------------------------- 1 | 2 | 3 | 4 | 5 | 6 | 7 | 8 | 9 | 10 | 11 | 12 | 13 | 14 | 15 | 16 | 17 | 18 | 19 | 20 | 21 | 22 | -------------------------------------------------------------------------------- /quickstart.mdx: -------------------------------------------------------------------------------- 1 | --- 2 | title: "Quickstart" 3 | description: "Start building awesome documentation in minutes" 4 | --- 5 | 6 | ## Get started in three steps 7 | 8 | Get your documentation site running locally and make your first customization. 9 | 10 | ### Step 1: Set up your local environment 11 | 12 | 13 | 14 | During the onboarding process, you created a GitHub repository with your docs content if you didn't already have one. You can find a link to this repository in your [dashboard](https://dashboard.mintlify.com). 15 | 16 | To clone the repository locally so that you can make and preview changes to your docs, follow the [Cloning a repository](https://docs.github.com/en/repositories/creating-and-managing-repositories/cloning-a-repository) guide in the GitHub docs. 17 | 18 | 19 | 1. Install the Mintlify CLI: `npm i -g mint` 20 | 2. Navigate to your docs directory and run: `mint dev` 21 | 3. Open `http://localhost:3000` to see your docs live! 22 | 23 | Your preview updates automatically as you edit files. 24 | 25 | 26 | 27 | ### Step 2: Deploy your changes 28 | 29 | 30 | 31 | Install the Mintlify GitHub app from your [dashboard](https://dashboard.mintlify.com/settings/organization/github-app). 32 | 33 | Our GitHub app automatically deploys your changes to your docs site, so you don't need to manage deployments yourself. 34 | 35 | 36 | For a first change, let's update the name and colors of your docs site. 37 | 38 | 1. Open `docs.json` in your editor. 39 | 2. Change the `"name"` field to your project name. 40 | 3. Update the `"colors"` to match your brand. 41 | 4. Save and see your changes instantly at `http://localhost:3000`. 42 | 43 | Try changing the primary color to see an immediate difference! 44 | 45 | 46 | 47 | ### Step 3: Go live 48 | 49 | 50 | 1. Commit and push your changes. 51 | 2. Your docs will update and be live in moments! 52 | 53 | 54 | ## Next steps 55 | 56 | Now that you have your docs running, explore these key features: 57 | 58 | 59 | 60 | 61 | Learn MDX syntax and start writing your documentation. 62 | 63 | 64 | 65 | Make your docs match your brand perfectly. 66 | 67 | 68 | 69 | Include syntax-highlighted code blocks. 70 | 71 | 72 | 73 | Auto-generate API docs from OpenAPI specs. 74 | 75 | 76 | 77 | 78 | 79 | **Need help?** See our [full documentation](https://mintlify.com/docs) or join our [community](https://mintlify.com/community). 80 | 81 | -------------------------------------------------------------------------------- /snippets/snippet-intro.mdx: -------------------------------------------------------------------------------- 1 | One of the core principles of software development is DRY (Don't Repeat 2 | Yourself). This is a principle that applies to documentation as 3 | well. If you find yourself repeating the same content in multiple places, you 4 | should consider creating a custom snippet to keep your content in sync. 5 | --------------------------------------------------------------------------------