### Enabling the contextual menu
Add the `contextual` field to your `docs.json` and specify which options you want to include in your menu.
```json
{
"contextual": {
"options": [
"copy",
"view",
"chatgpt",
"claude"
]
}
}
```
## /llms.txt
The [/llms.txt file](https://llmstxt.org) is an industry standard that helps general-purpose LLMs index more efficiently, similar to how a sitemap helps search engines.
Every documentation site automatically hosts an `/llms.txt` file at the root that lists all available pages in your documentation. AI tools can use this file to understand your documentation structure and find relevant content to user prompts.
The playground is automatically generated from your OpenAPI specification or AsyncAPI schema so any updates to your API are automatically reflected in the playground. You can also manually create API reference pages after defining a base URL and authentication method in your `docs.json`.
We recommend generating your API playground from an OpenAPI specification. See [OpenAPI Setup](/api-playground/openapi-setup) for more information on creating your OpenAPI document.
## Getting started
## Admin API key
The Admin API key is used for the majority of the API. It is used to trigger updates via the [Update endpoint](/api-reference/update/trigger).
## Assistant API key
The Assistant API allows you to embed the AI assistant experience grounded in your docs and continually kept up to date into any application of your choosing.
Responses include citations so you can point your users to the right places they need to get help.
## Captions
You can add additional context to an image using the optional `caption` prop.
## Props
```
```mdx Frame with Captions
```
## Changelog
You can add anything here, like a screenshot, a code snippet, or a list of changes.
#### Features
* Responsive design
* Sticky section for each changelog
## Introduction
The web editor is a visual interface for creating, editing, and reviewing documentation directly in your browser.
The web editor offers a **What-You-See-Is-What-You-Get (WYSIWYG)** experience while maintaining synchronization with your Git repository, which lets you see updates in real time and collaborate with your team on documentation changes.
### Web editor vs. CLI
The web editor lets you write and edit your documentation in your browser without requiring local development tools or using the command line. You should use the web editor if you want to maintain your documentation in one place with one tool.
The CLI is a command line tool that allows you to create and manage your documentation locally using the IDE of your choice. You should use the CLI if you want to integrate documentation into your existing development workflow.
Both the web editor and CLI are fully integrated with your Git repository, so you can use them interchangeably and different members of your team can use either tool based on their preferences.
## Editor Modes
The web editor offers two modes to accommodate different editing preferences and needs.
You can switch between natural modes at any time using the toggle in the top right corner of the editor toolbar.
### Visual Mode
Visual mode provides a WYSIWYG experience where the changes that you make in the editor are the changes that will be published to your documentation site. This mode is ideal for when you want to see how your changes will look in real-time.
#### Component Menu
You can add content blocks and other components to your documentation in visual mode using the dropdown component menu.
1. Press the `/` key to open the component menu.
2. Select a component from the menu.
### Markdown Mode
Markdown mode provides direct access to the underlying MDX code of your documentation. This mode is preferable when you need precise control over component properties or when you prefer to write in Markdown/MDX syntax.
## Making Changes
1. **Browse files**: Use the sidebar file explorer to navigate through your documentation.
2. **Open a file**: Click on the file that you want to edit to open it in the editor.
3. **Make changes**: Edit the content using visual or Markdown mode. Changes are automatically saved as drafts.
4. **Preview changes**: See how your changes will appear in visual mode.
## Publishing
The **Publish** button works differently depending on your branch:
* **Deployment branch**: Updates your live site immediately. This is usually the `main` branch.
* **Other branches**: Creates a pull request for review.
## Branches
Branches allow you to safely work on changes without affecting your live documentation. When your changes are ready, you can merge them into your deployment branch with a pull request.
### Reviewing Pull Requests
You can review pull requests in your Git platform (GitHub, GitLab).
After you create a pull request, you can see a preview deployment of the changes.
After a reviewer approves a pull request, you can merge it to deploy the changes to your live documentation site.
## Git Synchronization
The web editor integrates with your Git repository, ensuring that all changes are properly versioned and tracked.
### How Git Sync Works
* **Authentication**: The web editor connects to your Git repository through our [GitHub App](/settings/github) or [GitLab integration](/settings/gitlab).
* **Automatic fetching**: When you open the editor, it automatically fetches the latest content from your repository's deployment branch.
* **Change tracking**: As you make edits, the web editor tracks changes and can commit them to your repository.
* **Branching**: You can make changes directly to your deployment branch or to a separate branch, depending on your workflow preferences.
* **Pull requests**: For collaborative workflows, you can create pull requests from the web editor.
## Git Terminology
Understanding the following terms can help you work more effectively with the web editor and the Git workflow.
#### Tooltips and updates
## Image
Images are the most common way to add visual content to your documentation.
### Basics
The [markdown syntax](https://www.markdownguide.org/basic-syntax/#images) lets you add images using the following code
```mdx
```
```
### Disable Image Zoom
To disable the default zoom on click for images, add the `noZoom` property to image embeds.
```html
```
### Linking Images
To link an image, for example to create a button on your docs, encompass the image in a link with the `noZoom` property. Images in `a` tags will automatically have a pointer cursor.
```html
```
### Dark Mode
To use separate images for light and dark mode, use Tailwind CSS to hide and show images.
```html
```
### Related
For more information, we recommend the following sections:
{title}
{description} ; };
Documentation
Meet the next generation of documentation. AI-native, beautiful out-of-the-box, and built for developers.
## Installing the CLI
docs.json.}>
In your `docs.json` file, add the URL from Stainless to the `openapi` field. See [OpenAPI Setup](/api-playground/openapi-setup) for more information.
### Select MCP Clients
After authentication, you'll choose which MCP clients to enable for your server:
Once configured, your MCP server is ready to use with the command provided in the terminal.
## Configuring Your MCP Server
Now let's take a look at how to configure your MCP server.
### Default Functionality
All MCP servers include the `search` tool by default, allowing users to query information across your entire documentation.
### Adding API Functions
If you have an OpenAPI specification, you can expose specific endpoints as MCP tools by using the `x-mcp` extension at either the file or endpoint level.
#### File-Level Configuration
Enable MCP for all endpoints in a specification file:
```json
{
"openapi": "3.1.0",
"x-mcp": {
"enabled": true
},
// Other OpenAPI content
}
```
#### Endpoint-Level Configuration
Enable MCP for specific endpoints only:
```json
{
"paths": {
"/api/v1/users": {
"x-mcp": {
"enabled": true
},
// Endpoint configuration
}
}
}
```
### Authentication Handling
If your OpenAPI spec defines authentication using securitySchemes, these authentication methods will be automatically applied to your MCP server.
### Monitoring Your MCP Server
After publishing your changes, you can view all available MCP tools in the **Available Tools** section on the MCP server page in your dashboard.
## Distribution
### User Installation
Your users can install and use your MCP server with:
```bash
npx mint-mcp add 
Pages is an array where each entry must be a reference to the path of a [page file](pages).
```json
{
"navigation": {
"pages": [
"overview",
"quickstart",
"advanced/components",
"advanced/integrations"
]
}
}
```
***
## Groups
Use groups to organize your navigation into sections. Groups can be nested within each other, labeled with tags, and styled with icons.
```json
{
"navigation": {
"groups": [
{
"group": "Getting Started",
"icon": "play",
"pages": [
"quickstart",
{
"group": "Editing",
"icon": "pencil",
"pages": [
"installation",
"editor",
{
"group": "Nested group",
"icon": "code",
"pages": [
"navigation",
"code"
]
}
]
}
]
},
{
"group": "Writing Content",
"icon": "notebook-text",
"tag": "NEW",
"pages": ["writing-content/page", "writing-content/text"]
}
]
}
}
```
## Tabs
Tabs help distinguish between different topics or sections of your
documentation.
```json
"navigation": {
"tabs": [
{
"tab": "API References",
"pages": [
"api-reference/get",
"api-reference/post",
"api-reference/delete"
]
},
{
"tab": "SDKs",
"pages": [
"sdk/fetch",
"sdk/create",
"sdk/delete",
]
},
{
"tab": "Blog",
"href": "https://external-link.com/blog"
}
]
}
```
***
## Anchors
Anchors are another way to section your content. They show up on top of your side navigation.
The configuration is very similar to tabs.
While not required, we highly recommend that you set an `icon` field as well.
```json
"navigation": {
"anchors": [
{
"anchor": "Documentation",
"icon": "book-open",
"pages": [
"quickstart",
"development",
"navigation"
]
},
{
"anchor": "API References",
"icon": "square-terminal",
"pages": [
"api-reference/get",
"api-reference/post",
"api-reference/delete"
]
},
{
"anchor": "Blog",
"href": "https://external-link.com/blog"
}
]
}
```
***
Anchors that strictly contain external links can be achieved using the `global` keyword:
```json
"navigation": {
"global": {
"anchors": [
{
"anchor": "Community",
"icon": "house",
"href": "https://slack.com"
},
{
"anchor": "Blog",
"icon": "pencil",
"href": "https://mintlify.com/blog"
}
]
},
"tabs": /*...*/
}
```
## Dropdowns
Dropdowns show up in the same place as anchors, but are consolidated into a single dropdown.
While not required, we also recommend that you set an icon for each dropdown item.
```json
"navigation": {
"dropdowns": [
{
"dropdown": "Documentation",
"icon": "book-open",
"pages": [
"quickstart",
"development",
"navigation"
]
}
{
"dropdown": "API References",
"icon": "square-terminal",
"pages": [
"api-reference/get",
"api-reference/post",
"api-reference/delete"
]
}
{
"dropdown": "Blog",
"href": "https://external-link.com/blog"
}
]
}
```
***
## Versions
Versions can be leveraged to partition your navigation into different versions.
```json
{
"navigation": {
"versions": [
{
"version": "1.0.0",
"groups": [
{
"group": "Getting Started",
"pages": ["v1/overview", "v1/quickstart", "v1/development"]
}
]
},
{
"version": "2.0.0",
"groups": [
{
"group": "Getting Started",
"pages": ["v2/overview", "v2/quickstart", "v2/development"]
}
]
}
]
}
}
```
***
## Languages
Languages can be leveraged to partition your navigation into different languages.
We currently support the following languages:
This URL becomes available immediately and updates when you make changes to your documentation. Use this URL for testing and sharing with your team during development.
### Install the GitHub App
Mintlify provides a GitHub App that automates deployment when you push changes to your repository.
Install the GitHub App by following the instructions from the onboarding checklist or from your dashboard.
1. Navigate to **Settings** in your Mintlify dashboard.
2. Select **GitHub App** from the sidebar.
3. Select **Install GitHub App**. This opens a new tab to the GitHub App installation page.
4. Select the organization or user account where you want to install the app. Then select the repositories that you want to connect.
### Push the Changes
When you are ready to publish your changes, push the changes to your repository.
Mintlify automatically detects the changes, builds your documentation, and deploys the updates to your site. Monitor the deployment status in your GitHub repository commit history or the [dashboard](https://dashboard.mintlify.com).
After the deployment is complete, your latest update will be available at `
### Edit the Documentation
In the web editor, you can navigate through your documentation files in the sidebar. Let's update the introduction page:
Find and click on `introduction.mdx` in the file explorer.
Then, in the visual editor, update the title field to "Hello World".
Enter your domain (for example, `docs.yourcompany.com`) and follow the provided instructions to configure DNS (Domain Name System) settings with your domain provider.
{colors.map((color, idx) =>
copyToClipboard(color)} />)}
Base color: hsl({hue}, {saturation}%, {lightness}%)
{count}
Current count: {count}
{colors.map((color, idx) => (
copyToClipboard(color)}
/>
))}
Base color: hsl({hue}, {saturation}%, {lightness}%)
A `Warning` level check will never provide a failure status, even if there is an error or suggestions.
## Verification with Vercel
If Vercel happens to be your domain provider, you will have to add a verification `TXT` record. This information will show on your dashboard after submitting your custom domain, as well as be emailed to you.
## Configuring your DNS
1. Proceed to your domain's DNS settings on your domain provider's website.
2. Create a new DNS entry, inputting the following values:
```bash
CNAME | docs | cname.vercel-dns.com.
```
If you are using Cloudflare for your DNS provider, you'll need to have the “full strict” security option enabled for the https setting.
Please [contact support](mailto:sales@mintlify.com) if you don't see the custom domain set up after the above configuration.
# Custom Scripts
Source: https://mintlify.com/docs/settings/custom-scripts
Fully customize your documentation with custom CSS and JS
Add custom CSS and JavaScript to your documentation to fully customize the look and feel.
## Custom CSS
Add CSS files to your repository and their defined class names will be applied and available in all of your `MDX` files.
### Adding `style.css`
For example, you can add the following `style.css` file to customize the styling of the navbar and footer.
```css
#navbar {
background: "#fffff2";
padding: 1rem;
}
footer {
margin-top: 2rem;
}
```
### Using identifiers and selectors
Mintlify has a set of common identifiers and selectors to help you tag important elements of the UI.