Skip to content

Simplify quickstart page and streamline documentation structure #451

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 quickstart page and streamline documentation structure #451

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
32 changes: 13 additions & 19 deletions advanced/rest-api/overview.mdx
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -2,31 +2,28 @@
title: Overview
---

## Trigger Updates

Leverage the REST 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)!

## 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 an API key through [the dashboard](https://dashboard.mintlify.com/settings/integrations). This key works across all deployments within your organization.

<Frame>
<img src="/images/external-api-key.png" />
</Frame>

## Trigger Updates

Use our REST API to programmatically trigger documentation updates. Additional API functionality will be added based on user feedback. Share your suggestions in [our community](https://mintlify.com/community).

## Discovery API

The Discovery API allows you to embed an AI chat 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.
The Discovery API enables AI-powered chat experiences within your documentation. Key features:
- Embedded chat interface for any application
- Responses include citations to source documentation
- Automatically stays synchronized with your content

## Getting Started
### Setup

To get started, you'll need to generate a Discovery API key in the [dashboard](https://dashboard.mintlify.com/products/chat/widget):
1. Generate a Discovery API key in the [dashboard](https://dashboard.mintlify.com/products/chat/widget):

<Frame>
<img
Expand All @@ -36,10 +33,7 @@ To get started, you'll need to generate a Discovery API key in the [dashboard](h
</Frame>

<Note>
The Discovery API token is a public token that can be referenced in your
frontend code whereas the API key is a server-side token that should be kept
secret.
The Discovery API token is public and safe for frontend code. Keep the API key secure on your server side.
</Note>

Now that you have an API key, check out our [example](https://github.com/mintlify/discovery-api-example) for how to use
the API for AI chat. You can also see a deployed version of this example at [chat.mintlify.com](https://chat.mintlify.com).
2. See our [example implementation](https://github.com/mintlify/discovery-api-example) or view the [live demo](https://chat.mintlify.com).
41 changes: 14 additions & 27 deletions advanced/subpath/cloudflare.mdx
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -3,22 +3,20 @@ title: "Cloudflare"
description: "Host documentation at a /docs subpath using Cloudflare Workers"
---

## Create Cloudflare Worker
## Quick 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`
- Give your worker a name and create it

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

<Frame>
<img
Expand All @@ -27,23 +25,16 @@ 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. Add the Worker Script
- Click `Edit Code`
- Copy the script below
- Replace `[SUBDOMAIN]` and `[YOUR_DOMAIN]` with your values
- Click `Deploy`

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

```javascript
addEventListener("fetch", (event) => {
event.respondWith(handleRequest(event.request));
Expand All @@ -52,9 +43,7 @@ addEventListener("fetch", (event) => {
async function handleRequest(request) {
try {
const urlObject = new URL(request.url);
// If the request is to the docs subdirectory
if (/^\/docs/.test(urlObject.pathname)) {
// Then Proxy to Mintlify
const DOCS_URL = "[SUBDOMAIN].mintlify.dev";
const CUSTOM_URL = "[YOUR_DOMAIN]";

Expand All @@ -70,11 +59,9 @@ async function handleRequest(request) {
return await fetch(proxyRequest);
}
} catch (error) {
// if no action found, play the regular request
return await fetch(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. Need help? [Contact our support team](mailto:[email protected]).
93 changes: 20 additions & 73 deletions advanced/widget/chat.mdx
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -9,15 +9,12 @@ description: "Integrate the Mintlify widget into your products to offer users qu

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

<Frame>
![widget](https://mintlify-assets.b-cdn.net/widget/key.webp)
</Frame>
2. Add the widget to your site:

## Installation

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

```html
<script>
Expand All @@ -40,7 +37,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 Installation
For React and Next.js apps, use our React component:

```jsx
<MintlifyWidget
Expand All @@ -50,73 +48,22 @@ 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 Options

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

#### MintlifyWidgetDisplayChatProps
| Prop | Description |
| ------------ | ---------------------------------------------------------- |
| `connection` | Required. Contains API connection details (`apiKey`) |
| `display` | Optional. Customize widget appearance and interactions |
| `tracking` | Optional. Add analytics tracking functions |

| 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 Customization

### MintlifyWidgetTrackingFunctions
- **Trigger Types**: Choose between `button` or `input` display
- **Colors**: Customize `primary` and `primaryLight` colors
- **Dark Mode**: Toggle with `isDarkMode`
- **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 and examples, see our [advanced configuration guide]()</fileContent>
</invoke>
34 changes: 14 additions & 20 deletions api-playground/mdx/configuration.mdx
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -1,26 +1,26 @@
---
title: 'MDX Setup'
description: 'Generate docs pages for your API endpoints using MDX'
description: 'Configure API endpoints documentation 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 and generate an interactive API playground.

<Steps>
<Step title="Configure your API">
In your `mint.json` file, define your base URL and auth method:
<Step title="Configure API settings">
Add your API configuration to `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 @@ -31,13 +31,10 @@ 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).
</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 with the following metadata:

```md
---
Expand All @@ -46,20 +43,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 `{parameterName}`:
```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` configured, 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 the `navigation` field in `mint.json` to display them in your sidebar.
</Step>
</Steps>
</Steps>
Loading
Loading