Skip to content

docs: simplify quickstart page and improve documentation structure #418

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

docs: simplify quickstart page and improve documentation structure #418

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
10 changes: 3 additions & 7 deletions advanced/rest-api/overview.mdx
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -6,17 +6,13 @@ title: Introduction
The Mintlify REST API is only available on the startup plan and above.
</Check>

Leverage the external API to programmatically trigger an update when desired.
The primary use-case will be to trigger updates. We will be adding more and more
functionality to the API overtime. Let us know what else you want to see in
[our community](https://mintlify.com/community)!
The Mintlify REST API allows you to programmatically trigger documentation updates. For feature requests, join us in [our community](https://mintlify.com/community).

## Authentication

You can generate an API key through
[the dashboard](https://dashboard.mintlify.com/settings/integrations). The API key is
associated with the entire org and can be used across multiple deployments.
Generate your API key in [the dashboard](https://dashboard.mintlify.com/settings/integrations). Each API key works for all deployments within your organization.

<Frame>
<img src="/images/external-api-key.png" />
</Frame>
</fileContent>
42 changes: 14 additions & 28 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,20 @@ import SubpathGatingSnippet from "/snippets/custom-subpath-gating.mdx";

<SubpathGatingSnippet platform="Cloudflare" />

## Create Cloudflare Worker
## Setup Guide

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 Worker
- Go to `Workers & Pages > Create application > Create worker`
- Create a new Cloudflare 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. Configure Domain
- In your worker, go to `Settings > Triggers`
- Click `Add Custom Domain`
- Add your domain (both with and without `www.`)

<Frame>
<img
Expand All @@ -31,22 +29,11 @@ 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.

<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 Worker Script
- Click `Edit Code`
- Copy and paste the script below
- Replace `[SUBDOMAIN]` and `[YOUR_DOMAIN]` with your values
- Click `Deploy`

```javascript
addEventListener("fetch", (event) => {
Expand Down Expand Up @@ -80,5 +67,4 @@ 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]).
15 changes: 3 additions & 12 deletions advanced/subpath/vercel.mdx
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -3,14 +3,7 @@ title: "Vercel"
description: "Host documentation at a /docs subpath using Vercel"
---

import SubpathGatingSnippet from "/snippets/custom-subpath-gating.mdx";

<SubpathGatingSnippet platform="Vercel" />

## vercel.json Configuration

To host your documentation at a custom subpath using Vercel, you need to add the
following configuration to your `vercel.json` file.
To host your documentation at a custom subpath using Vercel, add the following configuration to your `vercel.json` file:

```json
{
Expand All @@ -28,7 +21,5 @@ following configuration to your `vercel.json` file.
```

<Note>
For more information, you can also refer to Vercel's offical guide on
rewrites: [Project Configuration:
Rewrites](https://vercel.com/docs/projects/project-configuration#rewrites)
</Note>
For more information, see [Vercel's rewrites documentation](https://vercel.com/docs/projects/project-configuration#rewrites)
</Note>
93 changes: 19 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,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 chat widget into your products to provide AI-powered documentation search for your users.

![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 the following 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/Next.js Installation

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

```jsx
<MintlifyWidget
Expand All @@ -47,73 +48,17 @@ 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

| 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 the following main properties:

### MintlifyWidgetTrackingFunctions
| Prop | Description |
|------|-------------|
| `connection.apiKey` | Required. Your widget API key |
| `display.trigger.type` | Optional. Either 'button' or 'input' |
| `display.trigger.label` | Optional. Custom trigger text |
| `display.colors.primary` | Optional. Custom primary color |
| `display.chat.exampleQueries` | Optional. Array of example questions |

| 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 advanced configuration options, visit our [detailed configuration guide]()</fileContent>
</invoke>
Loading
Loading