### Step-by-Step Procedure Example
Source: https://github.com/browseros-ai/docs/blob/main/ai-tools/cursor.mdx
Illustrates a multi-step procedure with verification and warnings.
```markdown
Run `npm install` to install required packages.
Verify installation by running `npm list`.
Create a `.env` file with your API credentials.
```bash
API_KEY=your_api_key_here
```
Never commit API keys to version control.
```
--------------------------------
### Install Mintlify CLI
Source: https://github.com/browseros-ai/docs/blob/main/development.mdx
Installs the Mintlify CLI globally using npm. Ensure you have Node.js version 19 or higher.
```bash
npm i -g mint
```
--------------------------------
### JavaScript Configuration Example
Source: https://github.com/browseros-ai/docs/blob/main/ai-tools/cursor.mdx
Example of a single JavaScript code block for API configuration.
```javascript
const apiConfig = {
baseURL: 'https://api.example.com',
timeout: 5000,
headers: {
'Authorization': `Bearer ${process.env.API_TOKEN}`
}
};
```
--------------------------------
### Request Example using cURL
Source: https://github.com/browseros-ai/docs/blob/main/ai-tools/cursor.mdx
Example of a cURL command for making a POST request.
```bash
curl -X POST 'https://api.example.com/users' \
-H 'Content-Type: application/json' \
-d '{"name": "John Doe", "email": "john@example.com"}'
```
--------------------------------
### Run Mintlify Local Preview
Source: https://github.com/browseros-ai/docs/blob/main/development.mdx
Starts a local development server for previewing documentation. Navigate to your docs directory before running.
```bash
mint dev
```
--------------------------------
### Install Claude Code CLI
Source: https://github.com/browseros-ai/docs/blob/main/ai-tools/claude-code.mdx
Install the Claude Code CLI tool globally using npm. Ensure you have Node.js and npm installed.
```bash
npm install -g @anthropic-ai/claude-code
```
--------------------------------
### Tabbed Content Example
Source: https://github.com/browseros-ai/docs/blob/main/ai-tools/cursor.mdx
Shows how to use tabs to present alternative content for different operating systems.
```markdown
```bash
brew install node
npm install -g package-name
```
```powershell
choco install nodejs
npm install -g package-name
```
```bash
sudo apt install nodejs npm
npm install -g package-name
```
```
--------------------------------
### Response Example in JSON
Source: https://github.com/browseros-ai/docs/blob/main/ai-tools/cursor.mdx
Example of a JSON response structure.
```json
{
"id": "user_123",
"name": "John Doe",
"email": "john@example.com",
"created_at": "2024-01-15T10:30:00Z"
}
```
--------------------------------
### Run Mintlify on Custom Port
Source: https://github.com/browseros-ai/docs/blob/main/development.mdx
Starts the local development server on a specified port. If the port is in use, Mintlify will attempt to use the next available port.
```bash
mint dev --port 3333
```
--------------------------------
### Mintlify Technical Writing Rule Example
Source: https://github.com/browseros-ai/docs/blob/main/ai-tools/cursor.mdx
This markdown content defines AI writing assistant rules for technical documentation using Mintlify components and best practices.
```markdown
# Mintlify technical writing rule
You are an AI writing assistant specialized in creating exceptional technical documentation using Mintlify components and following industry-leading technical writing practices.
## Core writing principles
### Language and style requirements
- Use clear, direct language appropriate for technical audiences
- Write in second person ("you") for instructions and procedures
- Use active voice over passive voice
- Employ present tense for current states, future tense for outcomes
- Avoid jargon unless necessary and define terms when first used
- Maintain consistent terminology throughout all documentation
- Keep sentences concise while providing necessary context
- Use parallel structure in lists, headings, and procedures
### Content organization standards
- Lead with the most important information (inverted pyramid structure)
- Use progressive disclosure: basic concepts before advanced ones
- Break complex procedures into numbered steps
- Include prerequisites and context before instructions
- Provide expected outcomes for each major step
- Use descriptive, keyword-rich headings for navigation and SEO
- Group related information logically with clear section breaks
### User-centered approach
- Focus on user goals and outcomes rather than system features
- Anticipate common questions and address them proactively
- Include troubleshooting for likely failure points
- Write for scannability with clear headings, lists, and white space
- Include verification steps to confirm success
## Mintlify component reference
### Callout components
#### Note - Additional helpful information
Supplementary information that supports the main content without interrupting flow
#### Tip - Best practices and pro tips
Expert advice, shortcuts, or best practices that enhance user success
#### Warning - Important cautions
Critical information about potential issues, breaking changes, or destructive actions
#### Info - Neutral contextual information
Background information, context, or neutral announcements
#### Check - Success confirmations
Positive confirmations, successful completions, or achievement indicators
### Code components
#### Single code block
Example of a single code block:
```javascript config.js
const apiConfig = {
baseURL: 'https://api.example.com',
timeout: 5000,
headers: {
'Authorization': `Bearer ${process.env.API_TOKEN}`
}
};
```
#### Code group with multiple languages
Example of a code group:
```javascript Node.js
const response = await fetch('/api/endpoint', {
headers: { Authorization: `Bearer ${apiKey}` }
});
```
```python Python
import requests
response = requests.get('/api/endpoint',
headers={'Authorization': f'Bearer {api_key}'})
```
```curl cURL
curl -X GET '/api/endpoint' \
-H 'Authorization: Bearer YOUR_API_KEY'
```
#### Request/response examples
Example of request/response documentation:
```bash cURL
curl -X POST 'https://api.example.com/users' \
-H 'Content-Type: application/json' \
-d '{"name": "John Doe", "email": "john@example.com"}'
```
```json Success
{
"id": "user_123",
"name": "John Doe",
"email": "john@example.com",
"created_at": "2024-01-15T10:30:00Z"
}
```
### Structural components
#### Steps for procedures
Example of step-by-step instructions:
Run `npm install` to install required packages.
Verify installation by running `npm list`.
Create a `.env` file with your API credentials.
```bash
API_KEY=your_api_key_here
```
Never commit API keys to version control.
#### Tabs for alternative content
Example of tabbed content:
```bash
brew install node
npm install -g package-name
```
```powershell
choco install nodejs
npm install -g package-name
```
```bash
sudo apt install nodejs npm
npm install -g package-name
```
#### Accordions for collapsible content
Example of accordion groups:
```
--------------------------------
### Advanced Configuration Object
Source: https://github.com/browseros-ai/docs/blob/main/ai-tools/cursor.mdx
An example of an advanced configuration object in JavaScript, specifying performance and security settings.
```javascript
const config = {
performance: { cache: true, timeout: 30000 },
security: { encryption: 'AES-256' }
};
```
--------------------------------
### Code Group with Multiple Languages
Source: https://github.com/browseros-ai/docs/blob/main/ai-tools/cursor.mdx
Demonstrates a code group with examples in JavaScript, Python, and cURL.
```javascript
const response = await fetch('/api/endpoint', {
headers: { Authorization: `Bearer ${apiKey}` }
});
```
```python
import requests
response = requests.get('/api/endpoint',
headers={'Authorization': f'Bearer {api_key}'})
```
```curl
curl -X GET '/api/endpoint' \
-H 'Authorization: Bearer YOUR_API_KEY'
```
--------------------------------
### Claude Code Training Configuration
Source: https://github.com/browseros-ai/docs/blob/main/ai-tools/claude-code.mdx
Create a CLAUDE.md file to define documentation standards and project context for Claude Code. This file guides the AI's behavior and ensures consistency.
```markdown
# Mintlify documentation
## Working relationship
- You can push back on ideas-this can lead to better documentation. Cite sources and explain your reasoning when you do so
- ALWAYS ask for clarification rather than making assumptions
- NEVER lie, guess, or make up information
## Project context
- Format: MDX files with YAML frontmatter
- Config: docs.json for navigation, theme, settings
- Components: Mintlify components
## Content strategy
- Document just enough for user success - not too much, not too little
- Prioritize accuracy and usability of information
- Make content evergreen when possible
- Search for existing information before adding new content. Avoid duplication unless it is done for a strategic reason
- Check existing patterns for consistency
- Start by making the smallest reasonable changes
## Frontmatter requirements for pages
- title: Clear, descriptive page title
- description: Concise summary for SEO/navigation
## Writing standards
- Second-person voice ("you")
- Prerequisites at start of procedural content
- Test all code examples before publishing
- Match style and formatting of existing pages
- Include both basic and advanced use cases
- Language tags on all code blocks
- Alt text on all images
- Relative paths for internal links
## Git workflow
- NEVER use --no-verify when committing
- Ask how to handle uncommitted changes before starting
- Create a new branch when no clear branch exists for changes
- Commit frequently throughout development
- NEVER skip or disable pre-commit hooks
## Do not
- Skip frontmatter on any MDX file
- Use absolute URLs for internal links
- Include untested code examples
- Make assumptions - always ask for clarification
```
--------------------------------
### Update Mintlify CLI
Source: https://github.com/browseros-ai/docs/blob/main/README.md
Ensure you have the most recent version of the Mintlify CLI installed. This command is useful for troubleshooting and resolving issues with the dev environment.
```bash
mint update
```
--------------------------------
### Create Cursor Project Rules Directory
Source: https://github.com/browseros-ai/docs/blob/main/ai-tools/cursor.mdx
Use this command to create the necessary directory for Cursor project rules.
```bash
mkdir -p .cursor
```
--------------------------------
### Navigation with Folder Structure
Source: https://github.com/browseros-ai/docs/blob/main/essentials/navigation.mdx
Shows how to include pages located within folders in the navigation. The path in `docs.json` should reflect the folder structure.
```json
"navigation": {
"tabs": [
{
"tab": "Docs",
"groups": [
{
"group": "Group Name",
"pages": ["your-folder/your-page"]
}
]
}
]
}
```
--------------------------------
### YAML Frontmatter for Page Structure
Source: https://github.com/browseros-ai/docs/blob/main/ai-tools/cursor.mdx
Demonstrates the required YAML frontmatter for documentation pages, including title and description.
```yaml
---
title: "Clear, specific, keyword-rich title"
description: "Concise description explaining page purpose and value"
---
```
--------------------------------
### Import and Use Default Snippet
Source: https://github.com/browseros-ai/docs/blob/main/essentials/reusable-snippets.mdx
Import a defined snippet into your destination file and use it as a component, passing any necessary props.
```mdx
---
title: My title
description: My Description
---
import MySnippet from '/snippets/path/to/my-snippet.mdx';
## Header
Lorem impsum dolor sit amet.
```
--------------------------------
### Validate Links with Mintlify CLI
Source: https://github.com/browseros-ai/docs/blob/main/development.mdx
Checks your documentation for broken links. Run this command in your docs directory.
```bash
mint broken-links
```
--------------------------------
### Import and Use Reusable Component
Source: https://github.com/browseros-ai/docs/blob/main/essentials/reusable-snippets.mdx
Import a custom component from a snippet file into your destination file and render it, passing any required props.
```mdx
---
title: My title
description: My Description
---
import { MyComponent } from '/snippets/custom-component.mdx';
Lorem ipsum dolor sit amet.
```
--------------------------------
### Mintlify Technical Writing Rules for Windsurf
Source: https://github.com/browseros-ai/docs/blob/main/ai-tools/windsurf.mdx
Define project context, writing standards, and component usage for Windsurf. This rule set ensures consistency and adherence to Mintlify's documentation best practices.
```markdown
# Mintlify technical writing rule
## Project context
- This is a documentation project on the Mintlify platform
- We use MDX files with YAML frontmatter
- Navigation is configured in `docs.json`
- We follow technical writing best practices
## Writing standards
- Use second person ("you") for instructions
- Write in active voice and present tense
- Start procedures with prerequisites
- Include expected outcomes for major steps
- Use descriptive, keyword-rich headings
- Keep sentences concise but informative
## Required page structure
Every page must start with frontmatter:
```yaml
---
title: "Clear, specific title"
description: "Concise description for SEO and navigation"
---
```
## Mintlify components
### Callouts
- `` for helpful supplementary information
- `` for important cautions and breaking changes
- `` for best practices and expert advice
- `` for neutral contextual information
- `` for success confirmations
### Code examples
- When appropriate, include complete, runnable examples
- Use `` for multiple language examples
- Specify language tags on all code blocks
- Include realistic data, not placeholders
- Use `` and `` for API docs
### Procedures
- Use `` component for sequential instructions
- Include verification steps with `` components when relevant
- Break complex procedures into smaller steps
### Content organization
- Use `` for platform-specific content
- Use `` for progressive disclosure
- Use `` and `` for highlighting content
- Wrap images in `` components with descriptive alt text
## API documentation requirements
- Document all parameters with ``
- Show response structure with ``
- Include both success and error examples
- Use `` for nested object properties
- Always include authentication examples
## Quality standards
- Test all code examples before publishing
- Use relative paths for internal links
- Include alt text for all images
- Ensure proper heading hierarchy (start with h2)
- Check existing patterns for consistency
```
--------------------------------
### Create Fenced Code Blocks with Syntax Highlighting
Source: https://github.com/browseros-ai/docs/blob/main/essentials/code.mdx
Enclose code in three backticks and specify the programming language for syntax highlighting. Optionally, include a filename after the language.
```java
class HelloWorld {
public static void main(String[] args) {
System.out.println("Hello, World!");
}
}
```
--------------------------------
### Enable Feedback Buttons
Source: https://github.com/browseros-ai/docs/blob/main/essentials/settings.mdx
Configure options to allow users to suggest edits or raise issues.
```json
{
"suggestEdit": true,
"raiseIssue": true
}
```
--------------------------------
### Markdown Link Syntax
Source: https://github.com/browseros-ai/docs/blob/main/essentials/markdown.mdx
Create links by wrapping text in square brackets and the URL in parentheses. Use root-relative paths for internal links.
```markdown
[link to google](https://google.com)
```
```markdown
[link to text](/writing-content/text)
```
```markdown
[link to text](../text)
```
--------------------------------
### Embed Image using Markdown
Source: https://github.com/browseros-ai/docs/blob/main/essentials/images.mdx
Use standard Markdown syntax to include images. Ensure image file sizes are under 5MB or host them externally.
```markdown

```
--------------------------------
### Update Mintlify CLI
Source: https://github.com/browseros-ai/docs/blob/main/development.mdx
Updates the Mintlify CLI to the latest version. This is recommended if your local preview differs from the production version.
```bash
npm mint update
```
--------------------------------
### docs.json Configuration
Source: https://github.com/browseros-ai/docs/blob/main/essentials/settings.mdx
The `docs.json` file is the core configuration for your Mintlify documentation site. It allows you to customize various aspects of its appearance and behavior.
```APIDOC
## Global Settings Configuration (`docs.json`)
### Description
This document outlines the structure and properties available within the `docs.json` file for configuring your Mintlify documentation site.
### Properties
- **name** (string, required): The name of your project, used for the global title.
Example: `"mintlify"`
- **navigation** (Navigation[], required): An array of navigation groups, each containing pages.
- **group** (string): The name of the navigation group.
Example: `"Settings"`
- **pages** (string[]): Relative paths to the markdown files for pages within the group.
Example: `["customization", "page"]`
- **logo** (string or object): Path to the logo image or an object for light/dark mode logos.
- **light** (string): Path to the logo in light mode.
- **dark** (string): Path to the logo in dark mode.
- **href** (string, default: `/`): The URL the logo links to.
- **favicon** (string): Path to the favicon image.
- **colors** (Colors): Hex color codes for the global theme.
- **primary** (string, required): Primary color for highlighted content, headers, and accents in light mode.
- **light** (string): Primary color for dark mode.
- **dark** (string): Primary color for important buttons.
- **background** (object): Background color for light and dark modes.
- **light** (string, required): Hex color code for the background in light mode.
- **dark** (string, required): Hex color code for the background in dark mode.
- **topbarLinks** (TopbarLink[]): An array of links for the topbar.
- **name** (string): The text displayed on the link button.
Example: `"Contact us"`
- **url** (string): The URL the link points to.
Example: `"https://mintlify.com/docs"`
- **topbarCtaButton** (Call to Action): Configuration for a Call to Action button in the topbar.
- **type** (string, default: `"link"`): Type of CTA button (`"link"` or `"github"`).
- **url** (string): URL for the CTA button (link destination or GitHub repository).
- **name** (string): Text for the button (required if `type` is `"link"`).
- **versions** (string[]): An array of version names to display in a dropdown.
- **anchors** (Anchor[]): An array of anchors with icon, color, and URL.
- **icon** (string): Font Awesome icon name for the anchor.
Example: `"comments"`
- **name** (string): The label for the anchor.
```
--------------------------------
### Troubleshoot Sharp Module Error
Source: https://github.com/browseros-ai/docs/blob/main/development.mdx
Steps to resolve the 'Could not load the "sharp" module' error. This involves removing and reinstalling the CLI after upgrading Node.js.
```bash
npm remove -g mint
```
```bash
npm i -g mint
```
--------------------------------
### Regular Navigation Structure
Source: https://github.com/browseros-ai/docs/blob/main/essentials/navigation.mdx
Defines a basic navigation structure with tabs and groups. Ensure page names do not include the `.mdx` extension.
```json
"navigation": {
"tabs": [
{
"tab": "Docs",
"groups": [
{
"group": "Getting Started",
"pages": ["quickstart"]
}
]
}
]
}
```
--------------------------------
### Response Fields
Source: https://github.com/browseros-ai/docs/blob/main/ai-tools/cursor.mdx
Illustrates how to document response fields, including basic fields, timestamps, arrays, and expandable nested objects.
```APIDOC
## Response Fields
Example of response field documentation:
Unique identifier assigned to the newly created user.
ISO 8601 formatted timestamp of when the user was created.
List of permission strings assigned to this user.
## Expandable nested fields
Example of nested field documentation:
Complete user object with all associated data.
User profile information including personal details.
User's first name as entered during registration.
URL to user's profile picture. Returns null if no avatar is set.
```
--------------------------------
### Configure OpenAPI File Path
Source: https://github.com/browseros-ai/docs/blob/main/essentials/settings.mdx
Specify the URL or relative path to your OpenAPI file. This can be a single file or an array of multiple files.
```json
"openapi": "https://example.com/openapi.json"
```
```json
"openapi": "/openapi.json"
```
```json
"openapi": ["https://example.com/openapi1.json", "/openapi2.json", "/openapi3.json"]
```
--------------------------------
### Import and Use Exported Variables
Source: https://github.com/browseros-ai/docs/blob/main/essentials/reusable-snippets.mdx
Import variables from a snippet file into your destination file and use them within your content.
```mdx
---
title: My title
description: My Description
---
import { myName, myObject } from '/snippets/path/to/custom-variables.mdx';
Hello, my name is {myName} and I like {myObject.fruit}.
```
--------------------------------
### Nested Navigation Structure
Source: https://github.com/browseros-ai/docs/blob/main/essentials/navigation.mdx
Illustrates how to create nested navigation groups within the `pages` array. This allows for hierarchical organization of reference pages.
```json
"navigation": {
"tabs": [
{
"tab": "Docs",
"groups": [
{
"group": "Getting Started",
"pages": [
"quickstart",
{
"group": "Nested Reference Pages",
"pages": ["nested-reference-page"]
}
]
}
]
}
]
}
```
--------------------------------
### Define Default Snippet Content
Source: https://github.com/browseros-ai/docs/blob/main/essentials/reusable-snippets.mdx
Add content to your snippet file that you want to reuse across multiple locations. You can optionally include variables to be filled in via props.
```mdx
Hello world! This is my content I want to reuse across pages. My keyword of the day is {word}.
```
--------------------------------
### Create Reusable Component Snippet
Source: https://github.com/browseros-ai/docs/blob/main/essentials/reusable-snippets.mdx
Define a reusable component within a snippet file by exporting an arrow function. This component can accept props.
```mdx
export const MyComponent = ({ title }) => (
{title}
... snippet content ...
);
```
--------------------------------
### LaTeX Component Syntax
Source: https://github.com/browseros-ai/docs/blob/main/essentials/markdown.mdx
Embed LaTeX expressions using the `` component for mathematical formulas.
```markdown
8 x (vk x H1 - H2) = (0,1)
```
--------------------------------
### HTML for Superscript and Subscript Text
Source: https://github.com/browseros-ai/docs/blob/main/essentials/markdown.mdx
Use HTML `` and `` tags for superscript and subscript text, as markdown does not natively support these.
```html
superscript
```
```html
subscript
```
--------------------------------
### Embed Image using HTML
Source: https://github.com/browseros-ai/docs/blob/main/essentials/images.mdx
Utilize the HTML `
` tag for more control over image display, such as setting dimensions.
```html
```
--------------------------------
### Embed YouTube Video using HTML
Source: https://github.com/browseros-ai/docs/blob/main/essentials/images.mdx
Embed external videos, commonly YouTube, using the `