Skip to content

Simplify and streamline documentation content across multiple pages #447

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Closed
wants to merge 1 commit into from
Closed

Simplify and streamline documentation content across multiple pages #447

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
1 commit
Select commit
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
135 changes: 59 additions & 76 deletions advanced/widget/chat.mdx
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -1,23 +1,24 @@
---
title: "Chat Widget"
description: "Integrate the Mintlify widget into your products to offer users quick access to AI-powered chat with your docs content as the knowledge base."
description: "Add an AI-powered chat widget to your product that uses your docs as a knowledge base."
---

<Frame>
![widget](https://mintlify-assets.b-cdn.net/widget/hero.webp)
</Frame>

## Getting started
## Setup

First, generate an API key in [the Mintlify dashboard](https://dashboard.mintlify.com/chat/widget-auth).
1. Get your API key from the [Mintlify dashboard](https://dashboard.mintlify.com/chat/widget-auth)

<Frame>
![widget](https://mintlify-assets.b-cdn.net/widget/key.webp)
</Frame>

## Installation
2. Add the widget to your site:

Add the widget by adding these script tags into your site's `<head>...<head/>` tag.
### Option 1: HTML
Add to your site's `<head>` tag:

```html
<script>
Expand All @@ -40,7 +41,8 @@ Add the widget by adding these script tags into your site's `<head>...<head/>` t
</script>
```

To use the widget in React and Next.js apps, use the React component from the `@mintlify/widget-react` [package](https://www.npmjs.com/package/@mintlify/widget-react). Here is a basic example of how to use the component in your React application:
### Option 2: React
Install and use our React component:

```jsx
<MintlifyWidget
Expand All @@ -50,73 +52,54 @@ To use the widget in React and Next.js apps, use the React component from the `@
/>
```

## Usage

In the first script tag or the React component props, you can customize the appearance and other settings of the widget. `mintlifyWidgetSettings` accepts the following props:

| Prop | Type | Description |
| ------------ | ------------------------------------------------------------------- | ---------------------------------------------------------- |
| `connection` | [MintlifyWidgetConnectionProps](#mintlifywidgetconnectionProps) | Information needed to connect to our API. Required. |
| `display?` | [MintlifyWidgetDisplayProps](#mintlifywidgetdisplayProps) | Configurations for the widget appearance and interactions. |
| `tracking?` | [MintlifyWidgetTrackingFunctions](#mintlifywidgettrackingfunctions) | Callback functions for tracking analytics. |

### MintlifyWidgetConnectionProps

| Prop | Type | Description |
| -------- | -------- | ----------------------------------------------------------- |
| `apiKey` | `string` | Widget API key generated from Mintlify dashboard. Required. |
| `url?` | `string` | Used for internal testing only |

### MintlifyWidgetDisplayProps

| Prop | Type | Description |
| ------------- | ----------------------------------------------------------------------- | ----------------------------------------------------------- |
| `trigger?` | [MintlifyWidgetDisplayTriggerProps](#mintlifywidgetdisplaytriggerprops) | Appearance of the trigger. |
| `colors?` | [MintlifyWidgetDisplayColorsProps](#mintlifywidgetdisplaycolorsprops) | Colors used across the widget. |
| `chat?` | [MintlifyWidgetDisplayChatProps](#mintlifywidgetdisplaychatprops) | Configs specific to AI chat. |
| `isDarkMode?` | `boolean` | Controlled dark mode appearance. Defaults to OS preference. |

#### MintlifyWidgetDisplayTriggerProps

| Prop | Type | Description |
| ------------- | ------------------------------------ | -------------------------------------------------------------------------------------------------------------------------- |
| `type?` | `'button'`\|`'input'` | Type of the trigger to display. Defaults to `button`. |
| `label?` | `string` | Label displayed in the trigger. Defaults to `Get help` for the button trigger and `Ask anything...` for the input trigger. |
| `buttonIcon?` | `'chat'`\|`'sparkles'`\|`'mintlify'` | Icon used in the trigger. Only available for the `button` trigger. Defaults to `chat`. |
| `iconOnly?` | `boolean` | Only show icon in the trigger or not. Defaults to `false`. |

Here is an overview of what the trigger looks like with different configurations.

| `type='input'` | |
| -------------- | ------------------------------------------------------------ |
| | <img style={{height:'80px'}} src="https://mintlify-assets.b-cdn.net/widget/input.png"/> |

| `type='button'` | `'chat'` | `'sparkles'` | `'mintlify'` |
| ---------------- | --------------------------------------------------------------------------- | ------------------------------------------------------------------------------- | ------------------------------------------------------------------------------- |
| `iconOnly=false` | <img style={{height:'80px'}} src="https://mintlify-assets.b-cdn.net/widget/button-chat.png"/> | <img style={{height:'80px'}} src="https://mintlify-assets.b-cdn.net/widget/button-sparkles.png"/> | <img style={{height:'80px'}} src="https://mintlify-assets.b-cdn.net/widget/button-mintlify.png"/> |
| `iconOnly=true` | <img style={{height:'80px'}} src="https://mintlify-assets.b-cdn.net/widget/button-chat-iconOnly.png"/> | <img style={{height:'80px'}} src="https://mintlify-assets.b-cdn.net/widget/button-sparkles-iconOnly.png"/> | <img style={{height:'80px'}} src="https://mintlify-assets.b-cdn.net/widget/button-mintlify-iconOnly.png"/> |

#### MintlifyWidgetDisplayColorsProps

| Prop | Type | Description |
| --------------- | -------- | -------------------------------------------------------- |
| `primary?` | `string` | Primary color used in the widget. Defaults to `#0D9373`. |
| `primaryLight?` | `string` | Primary color in dark mode. Defaults to `#55D799`. |

#### MintlifyWidgetDisplayChatProps

| Prop | Type | Description |
| ------------------------ | ---------- | ------------------------------------------------------------------ |
| `openCitationInSameTab?` | `boolean` | Open the citation url in the same tab or not. Defaults to `false`. |
| `exampleQueries?` | `string[]` | Example queries to prompt the user to ask. Defaults to `[]`. |

### MintlifyWidgetTrackingFunctions

| Prop | Type | Description |
| --------------------- | ------------------------------------------ | -------------------------------------------------- |
| `trackChatEnter` | `()=> void` | Triggered when the user opens the chat widget. |
| `trackCitationClick` | `(title: string, url: string)=> void` | Triggered when the user clicks on a citation. |
| `trackChatThumbsUp` | `(query: string, response: string)=> void` | Triggered when the user thumbs up on a response. |
| `trackChatThumbsDown` | `(query: string, response: string)=> void` | Triggered when the user thumbs down on a response. |
| `trackChatFollowup` | `(query: string)=> void` | Triggered when the user asks a question. |
| `trackChatClose` | `(queriesCount: number)=> void` | Triggered when the user exits the chat widget. |
## Configuration

The widget can be customized through these main props:

| Prop | Type | Description |
|------|------|-------------|
| `connection` | Object | Required. API connection settings. |
| `display` | Object | Optional. Widget appearance settings. |
| `tracking` | Object | Optional. Analytics callback functions. |

### Connection Props

| Prop | Type | Required | Description |
|------|------|----------|-------------|
| `apiKey` | string | Yes | Your Mintlify widget API key |
| `url` | string | No | Internal testing only |

### Display Props

Customize the widget's appearance:

| Prop | Type | Description |
|------|------|-------------|
| `trigger` | Object | Button/input trigger styling |
| `colors` | Object | Widget color scheme |
| `chat` | Object | Chat interface settings |
| `isDarkMode` | boolean | Force dark/light mode |

#### Trigger Types

<table>
<tr>
<th>Input Style</th>
<td><img style={{height:'80px'}} src="https://mintlify-assets.b-cdn.net/widget/input.png"/></td>
</tr>
<tr>
<th>Button Style</th>
<td><img style={{height:'80px'}} src="https://mintlify-assets.b-cdn.net/widget/button-chat.png"/></td>
</tr>
</table>

### Tracking Functions

| Function | Triggered When |
|----------|---------------|
| `trackChatEnter` | Widget opens |
| `trackCitationClick` | Citation clicked |
| `trackChatThumbsUp` | Response liked |
| `trackChatThumbsDown` | Response disliked |
| `trackChatFollowup` | Question asked |
| `trackChatClose` | Widget closed |
30 changes: 13 additions & 17 deletions api-playground/mdx/configuration.mdx
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -3,24 +3,24 @@ title: 'MDX Setup'
description: 'Generate docs pages for your API endpoints using MDX'
---

Mintlify allows you to define your API endpoints using a combination of `mint.json` configuration, MDX metadata fields, and the `<ParamFields />` component. From the defined endpoints, we generate an API playground, request examples, and response examples.
Learn how to set up API documentation with MDX. This will create an API playground, request examples, and response examples.

<Steps>
<Step title="Configure your API">
In your `mint.json` file, define your base URL and auth method:
Add your API settings in `mint.json`:

```json
{
"api": {
"baseUrl": "https://mintlify.com/api", // string array for multiple base URLs
"baseUrl": "https://mintlify.com/api",
"auth": {
"method": "bearer" // options: bearer, basic, key.
"method": "bearer"
}
}
}
```

If you would not like to show an API playground, you don't need to include auth types. Hide the playground with the following field:
To hide the API playground, use:

```json
{
Expand All @@ -32,12 +32,11 @@ Mintlify allows you to define your API endpoints using a combination of `mint.js
}
```

Find a full list of API configurations [here](/settings/global#api-configurations).
See all API settings [here](/settings/global#api-configurations).
</Step>

<Step title="Create your endpoint pages">

Each API endpoint page should have a corresponding MDX file. At the top of each file, define:
<Step title="Create endpoint pages">
Create an MDX file for each endpoint. Add this header:

```md
---
Expand All @@ -46,20 +45,17 @@ Mintlify allows you to define your API endpoints using a combination of `mint.js
---
```

You can specify path parameters by adding the parameter name to the path, wrapped with `{}`:

For paths with parameters, use `{}`:
```bash
https://api.example.com/v1/endpoint/{userId}
```

<Note>

If you have `baseUrl` configured in [mint.json](/settings/global), you can use relative paths like `/v1/endpoint`.

With `baseUrl` set in mint.json, you can use relative paths like `/v1/endpoint`
</Note>
</Step>

<Step title="Add your endpoints to your docs">
Add your endpoint pages to the sidebar by adding the paths to the `navigation` field in your `mint.json`. Learn more about structuring your docs [here](/settings/navigation).
<Step title="Add to navigation">
Add your endpoint pages to `mint.json` under the `navigation` field. Learn more about navigation [here](/settings/navigation).
</Step>
</Steps>
</Steps>
Loading
Loading