Skip to content

Commit

Permalink
Documentation edits made through Mintlify web editor
Browse files Browse the repository at this point in the history
  • Loading branch information
@mintlify-development
mintlify-development[bot] authored Dec 2, 2024
1 parent d70b909 commit 0e05445
Show file tree
Hide file tree
Showing 21 changed files with 361 additions and 1,410 deletions.
53 changes: 14 additions & 39 deletions advanced/subpath/cloudflare.mdx
View file
Original file line number Diff line number Diff line change
Expand Up @@ -7,46 +7,20 @@ import SubpathGatingSnippet from "/snippets/custom-subpath-gating.mdx";

<SubpathGatingSnippet platform="Cloudflare" />

## Create Cloudflare Worker
## Setup Instructions

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>
2. Add your custom domain:
- Go to `Settings > Triggers`
- Click `Add Custom Domain`
- Add your domain (with and without `www.`)

### 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.

<Frame>
<img
alt="Cloudflare worker custom domain"
src="/images/cloudflare/custom-domain.png"
/>
</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.

<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.
</Tip>
3. Add the worker script:
- Click `Edit Code`
- Copy the script below
- Replace `[SUBDOMAIN]` and `[YOUR_DOMAIN]` with your values
- Click `Deploy`

```javascript
addEventListener("fetch", (event) => {
Expand Down Expand Up @@ -80,5 +54,6 @@ async function handleRequest(request) {
}
```

Click on `Deploy` and wait for the changes to propagate (it can take up to a few
hours).
<Note>
Changes may take a few hours to propagate. For setup assistance, [contact our support team](mailto:[email protected]).
</Note>
58 changes: 29 additions & 29 deletions advanced/user-auth/oauth.mdx
View file
Original file line number Diff line number Diff line change
@@ -1,41 +1,41 @@
---
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.
Integrate your existing OAuth server with Mintlify for user authentication using the PKCE flow.

## 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 that:
- Accepts an OAuth access token
- Returns user data in [UserInfo](./sending-data) format
- Has defined scope requirements
</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="Set OAuth Configuration">
In your [Mintlify dashboard](https://dashboard.mintlify.com/mintlify/mintlify/settings/deployment/user-authentication):
- Select OAuth option
- Enter Authorization URL
- Provide Client ID
- List required Scopes
- Add Token URL
- Input 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="Add Redirect URL">
Copy the Redirect URL from your Mintlify dashboard and add it 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.
## Quick Example

```json
{
"authorizationUrl": "https://auth.foo.com/authorization",
"clientId": "ydybo4SD8PR73vzWWd6S0ObH",
"scopes": ["docs-user-info"],
"tokenUrl": "https://auth.foo.com/exchange",
"infoApiUrl": "https://api.foo.com/docs/user-info"
}
```
55 changes: 22 additions & 33 deletions advanced/user-auth/shared-session.mdx
View file
Original file line number Diff line number Diff line change
Expand Up @@ -3,48 +3,37 @@ title: 'Shared Session Auth'
description: 'Seamlessly share user sessions between your dashboard and your docs'
---

This method utilizes the session authentication info already stored in your user’s browser to create a seamless documentation experience.
Share your existing user authentication between your dashboard and documentation for a seamless experience.

## Implementation

<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>
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:
```
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 Mintlify 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

### Dashboard at subdomain, docs at subdomain

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`.

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**.

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
## Example Setup

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`.
Your setup will depend on where your dashboard and docs are hosted:

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.
- **Same domain** (e.g., `foo.com/dashboard` and `foo.com/docs`):
No special CORS configuration needed

I then go to the Mintlify dashboard settings and enter `https://foo.com/api/docs/user-info` for the API URL field.
- **Different subdomains** (e.g., `dash.foo.com` and `docs.foo.com`):
Configure CORS headers for the docs domain on your user info endpoint</fileContent>
</invoke>
90 changes: 16 additions & 74 deletions advanced/widget/chat.mdx
View file
Original file line number Diff line number Diff line change
Expand Up @@ -2,19 +2,18 @@
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 widget to provide AI-powered chat using your docs as the knowledge base.

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

## Getting started

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 using one of these methods:

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

## Installation

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

```html
<script>
Expand All @@ -37,7 +36,9 @@ 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 Installation

Install and use the `@mintlify/widget-react` package:

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

| 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 `[]`. |
The widget can be customized using these main props:

### MintlifyWidgetTrackingFunctions
| Prop | Description |
| ------------ | ---------------------------------------------------------- |
| `connection` | Required. API connection settings (`apiKey` required) |
| `display` | Optional. Widget appearance and interaction settings |
| `tracking` | Optional. Analytics callback functions |

| 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 and customization, visit our [full documentation](https://mintlify.com/docs/api-playground/chat-widget).
Loading

0 comments on commit 0e05445

Please sign in to comment.