Skip to content

Simplify quickstart page and streamline documentation #399

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
+483 −1,660
Closed

Simplify quickstart page and streamline documentation #399

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
30 changes: 9 additions & 21 deletions advanced/subpath/cloudflare.mdx
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -7,22 +7,16 @@ import SubpathGatingSnippet from "/snippets/custom-subpath-gating.mdx";

<SubpathGatingSnippet platform="Cloudflare" />

## Create Cloudflare Worker
## Setup Steps

Navigate to the `Workers & Pages > Create application > Create worker`. You
should be able to presented with the following screen where you can create a new
Cloudlfare worker.
1. Create a new Cloudflare Worker at `Workers & Pages > Create application > Create worker`

<Frame>
<img alt="Create a Cloudflare worker" src="/images/cloudflare/worker.png" />
</Frame>

### Add custom domain

Once the worker is created, click `Configure worker`. Navigate to the worker
`Settings > Triggers`. Click on `Add Custom Domain` to add your desired domain
into the list - we recommend you add both the version with and without `www.`
prepended to the domain.
2. Add your custom domain by going to `Settings > Triggers > Add Custom Domain`
- Add both `domain.com` and `www.domain.com` versions

<Frame>
<img
Expand All @@ -31,21 +25,14 @@ prepended to the domain.
/>
</Frame>

If you have trouble setting up a custom subdirectory,
[contact our support team](mailto:[email protected]) and we'll walk you through
upgrading your hosting with us.

### Edit Worker Script

Click on `Edit Code` and add the following script into the worker's code.
3. Click `Edit Code` and paste the following script:

<Frame>
<img alt="Cloudflare edit code" src="/images/cloudflare/edit-code.png" />
</Frame>

<Tip>
Edit `DOCS_URL` by replacing `[SUBDOMAIN]` with your unique subdomain and
`CUSTOM_URL` with your website's base URL.
Replace `[SUBDOMAIN]` and `[YOUR_DOMAIN]` in `DOCS_URL` and `CUSTOM_URL` with your values
</Tip>

```javascript
Expand Down Expand Up @@ -80,5 +67,6 @@ async function handleRequest(request) {
}
```

Click on `Deploy` and wait for the changes to propagate (it can take up to a few
hours).
4. Click `Deploy` (changes may take a few hours to propagate)

Need help? [Contact our support team](mailto:[email protected])
2 changes: 1 addition & 1 deletion advanced/subpath/route53-cloudfront.mdx
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -142,4 +142,4 @@ Click `Create records`.
You may need to remove the existing A record if one currently exists.
</Note>

And voila! You should be able to have your documentation served at `/docs` for your primary domain.
And voila! You should be able to have your documentation served at `/docs` for your primary domain.
56 changes: 27 additions & 29 deletions advanced/user-auth/oauth.mdx
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -1,41 +1,39 @@
---
title: 'OAuth 2.0'
description: 'Integrate with your OAuth server to enable user login via the PKCE flow'
description: 'Enable user login via OAuth PKCE flow'
---

If you have an existing OAuth server that supports the PKCE flow, you can integrate with Mintlify for a seamless login experience.
Mintlify supports authentication through OAuth 2.0 PKCE flow. Here's how to set it up:

## Implementation
## Setup Steps

<Steps>
<Step title="Create your Info API">
Create an API endpoint that can be accessed with an OAuth access token, and responds with a JSON payload following the [UserInfo](./sending-data) format. Take note of the scope or scopes required to access this endpoint.
<Step title="Create Info API">
Create an API endpoint accessible with an OAuth token that returns user data in the [UserInfo](./sending-data) format.
</Step>
<Step title="Configure your User Auth settings">
Go to your [Mintlify dashboard settings](https://dashboard.mintlify.com/mintlify/mintlify/settings/deployment/user-authentication), select the OAuth option, and fill out the required fields:

- **Authorization URL**: The base URL for the authorization request, to which we will add the appropriate query parameters.
- **Client ID**: An ID for the OAuth 2.0 client to be used.
- **Scopes**: An array of scopes that will be requested.
- **Token URL**: The base URL for the token exchange request.
- **Info API URL**: The endpoint that will be hit to retrieve user info.
<Step title="Configure OAuth">
In your [Mintlify dashboard](https://dashboard.mintlify.com/mintlify/mintlify/settings/deployment/user-authentication), select OAuth and provide:
- Authorization URL
- Client ID
- Required scopes
- Token URL
- Info API URL
</Step>
<Step title="Configure your OAuth client">
Copy the Redirect URL listed in the [Mintlify dashboard settings](https://dashboard.mintlify.com/mintlify/mintlify/settings/deployment/user-authentication) and add it as an authorized redirect URL for your OAuth server.
<Step title="Set Redirect URL">
Add the Redirect URL from your Mintlify dashboard to your OAuth server's authorized redirects.
</Step>
</Steps>

## Example

I have an existing OAuth server that supports the PKCE flow. I want to set up authentication for my docs hosted at `foo.com/docs`.

To set up authentication with Mintlify, I create an endpoint `api.foo.com/docs/user-info` which requires an OAuth access token with the `docs-user-info` scope, and responds with the user's custom data according to Mintlify’s specification.

I then go to the Mintlify dashboard settings, navigate to the User Auth settings, select OAuth, and enter the relevant values for the OAuth flow and Info API endpoint:
- **Authorization URL**: `https://auth.foo.com/authorization`
- **Client ID**: `ydybo4SD8PR73vzWWd6S0ObH`
- **Scopes**: `['docs-user-info']`
- **Token URL**: `https://auth.foo.com/exchange`
- **Info API URL**: `https://api.foo.com/docs/user-info`

Finally, I copy the Redirect URL displayed in the dashboard settings and add it as an authorized redirect URL in my OAuth client configuration settings.
## Example Configuration

```json
{
"Authorization URL": "https://auth.foo.com/authorization",
"Client ID": "ydybo4SD8PR73vzWWd6S0ObH",
"Scopes": ["docs-user-info"],
"Token URL": "https://auth.foo.com/exchange",
"Info API URL": "https://api.foo.com/docs/user-info"
}
```
</fileContent>
</invoke>
69 changes: 34 additions & 35 deletions advanced/user-auth/shared-session.mdx
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -1,50 +1,49 @@
---
title: 'Shared Session Auth'
description: 'Seamlessly share user sessions between your dashboard and your docs'
description: 'Share user sessions between your dashboard and docs'
---

This method utilizes the session authentication info already stored in your user’s browser to create a seamless documentation experience.
Shared Session Authentication lets you use existing session data from your user's browser to authenticate your documentation.

## Implementation
## Setup

<Steps>
<Step title="Create your Info API">
Create an API endpoint that uses session authentication to identify users, and responds with a JSON payload following the [UserInfo](./sending-data) format.

If the API domain does not *exactly match* the docs domain:
- Add the docs domain to your API's `Access-Control-Allow-Origin` header (must not be `*`)
- Ensure your API’s `Access-Control-Allow-Credentials` header is `true`
<Warning>
These CORS options only need to be enabled on the *single endpoint* responsible for returning user information. We do not recommend enabling these options on all dashboard endpoints.
</Warning>
<Step title="Create User Info API">
Create an API endpoint that:
- Uses your existing session authentication
- Returns user data in the [UserInfo](./sending-data) format
- Includes proper CORS headers if your API and docs domains differ:
```text
Access-Control-Allow-Origin: your-docs-domain.com
Access-Control-Allow-Credentials: true
```

<Warning>
Only enable these CORS settings on your user info endpoint, not across all API routes.
</Warning>
</Step>
<Step title="Configure your User Auth settings">
Go to your [Mintlify dashboard settings](https://dashboard.mintlify.com/mintlify/mintlify/settings/deployment/user-authentication) and add the API URL and your Login URL to your User Auth settings.
<Step title="Configure Settings">
Add your API URL and Login URL in your [Mintlify dashboard settings](https://dashboard.mintlify.com/mintlify/mintlify/settings/deployment/user-authentication).
</Step>
</Steps>

## Examples
## Example Setup

### Dashboard at subdomain, docs at subdomain
Your setup will depend on where your dashboard and docs are hosted:

I have a dashboard at `dash.foo.com`, which uses cookie-based session authentication. My dashboard API routes are hosted at `dash.foo.com/api`. I want to set up authentication for my docs hosted at `docs.foo.com`.
- **Different Subdomains**: For dashboard at `dash.example.com` and docs at `docs.example.com`
```text
API Endpoint: https://dash.example.com/api/docs/user-info
CORS Origin: https://docs.example.com
```

To set up authentication with Mintlify, I create another dashboard endpoint `dash.foo.com/api/docs/user-info` which identifies the user using session auth, and responds with their custom data according to Mintlify’s specification. I then add `https://docs.foo.com` to the `Access-Control-Allow-Origin` allow-list **for this route only**, and ensure my `Access-Control-Allow-Credentials` configuration is set to `true` **for this route only**.
- **Dashboard Subdomain, Docs at Root**: For dashboard at `dash.example.com` and docs at `example.com/docs`
```text
API Endpoint: https://dash.example.com/api/docs/user-info
CORS Origin: https://example.com
```

I then go to the Mintlify dashboard settings and enter `https://dash.foo.com/api/docs/user-info` for the API URL field.

### Dashboard at subdomain, docs at root

I have a dashboard at `dash.foo.com`, which uses cookie-based session authentication. My dashboard API routes are hosted at `dash.foo.com/api`. I want to set up authentication for my docs hosted at `foo.com/docs`.

To set up authentication with Mintlify, I create another dashboard endpoint `dash.foo.com/api/docs/user-info` which identifies the user using session auth, and responds with their custom data according to Mintlify’s specification. I then add `https://foo.com` to the `Access-Control-Allow-Origin` allow-list **for this route only**, and ensure my `Access-Control-Allow-Credentials` configuration is set to `true` **for this route only**.

I then go to the Mintlify dashboard settings and enter `https://dash.foo.com/api/docs/user-info` for the API URL field.

### Dashboard at root, docs at root

I have a dashboard at `foo.com/dashboard`, which uses cookie-based session authentication. My dashboard API routes are hosted at `foo.com/api`. I want to set up authentication for my docs hosted at `foo.com/docs`.

To set up authentication with Mintlify, I create another dashboard endpoint `foo.com/api/docs/user-info` which identifies the user using session auth, and responds with their custom data according to Mintlify’s specification.

I then go to the Mintlify dashboard settings and enter `https://foo.com/api/docs/user-info` for the API URL field.
- **Same Domain**: For dashboard at `example.com/dashboard` and docs at `example.com/docs`
```text
API Endpoint: https://example.com/api/docs/user-info
```
94 changes: 20 additions & 74 deletions advanced/widget/chat.mdx
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -2,19 +2,17 @@
title: "Chat Widget"
---

Integrate the Mintlify widget into your products to offer users quick access to AI-powered chat with your docs content as the knowledge base.
Integrate the Mintlify chat widget into your products to provide AI-powered search through your documentation.

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

## Getting started
## Setup

First, generate an API key in [the Mintlify dashboard](https://dashboard.mintlify.com/chat/widget-auth).
1. Generate an API key in the [Mintlify dashboard](https://dashboard.mintlify.com/chat/widget-auth)
2. Add the widget to your site:

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

## Installation

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

```html
<script>
Expand All @@ -37,7 +35,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:
### React/Next.js
Install and use the widget component:

```jsx
<MintlifyWidget
Expand All @@ -47,73 +46,20 @@ 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
## Configuration

| Prop | Type | Description |
| --------------- | -------- | -------------------------------------------------------- |
| `primary?` | `string` | Primary color used in the widget. Defaults to `#0D9373`. |
| `primaryLight?` | `string` | Primary color in dark mode. Defaults to `#55D799`. |
The widget can be customized using the following props:

#### MintlifyWidgetDisplayChatProps
| Prop | Description |
| ------------ | ---------------------------------------------------------- |
| `connection` | API connection settings (required) |
| `display` | Widget appearance and interaction settings |
| `tracking` | Analytics tracking callbacks |

| 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 `[]`. |
### Display Options

### MintlifyWidgetTrackingFunctions
- **Trigger Types**: Choose between `button` or `input` display
- **Colors**: Customize primary colors for light/dark modes
- **Chat Settings**: Configure example queries and citation behavior

| 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. |
For detailed configuration options, visit our [API Reference](https://mintlify.com/docs/api-reference/introduction).
Loading
Loading