Skip to content

Simplify quickstart page and improve related documentation #428

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 improve related documentation #428

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
21 changes: 8 additions & 13 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,14 @@
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.
Add an AI-powered chat widget to your product that lets users search your documentation instantly.

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

## Getting started
## Quick Start

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

![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.
1. Get your API key from [the Mintlify dashboard](https://dashboard.mintlify.com/chat/widget-auth)
2. Add this code to your website's `<head>` tag:

```html
<script>
Expand All @@ -37,7 +32,7 @@ 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:
For React apps, install the `@mintlify/widget-react` package:

```jsx
<MintlifyWidget
Expand All @@ -47,9 +42,9 @@ To use the widget in React and Next.js apps, use the React component from the `@
/>
```

## Usage
## Configuration Options

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:
You can customize the widget's appearance and behavior using the following configuration options:

| Prop | Type | Description |
| ------------ | ------------------------------------------------------------------- | ---------------------------------------------------------- |
Expand Down Expand Up @@ -116,4 +111,4 @@ Here is an overview of what the trigger looks like with different configurations
| `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. |
| `trackChatClose` | `(queriesCount: number)=> void` | Triggered when the user exits the chat widget. |
88 changes: 24 additions & 64 deletions development.mdx
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -4,99 +4,59 @@ description: 'Preview changes locally to update your docs'
---

<Info>

**Prerequisite**: Please install Node.js (version 19 or higher) before proceeding.

**Prerequisite**: Node.js (version 19 or higher)
</Info>

**Step 1**: Install Mintlify:
## Quick Start

1. Install Mintlify CLI:
<CodeGroup>

```bash npm
npm i -g mintlify
```

```bash npm
npm i -g mintlify
```
```bash yarn
yarn global add mintlify
```

</CodeGroup>

**Step 2**: Navigate to the docs directory (where the `mint.json` file is located) and execute the following command:

2. Start the development server:
```bash
mintlify dev
```
Your documentation will be available at `http://localhost:3000`.

A local preview of your documentation will be available at `http://localhost:3000`.

### Custom Ports

By default, Mintlify uses port 3000. You can customize the port Mintlify runs on by using the `--port` flag. To run Mintlify on port 3333, for instance, use this command:
## Common Tasks

### Custom Port
To use a different port (e.g., 3333):
```bash
mintlify dev --port 3333
```

If you attempt to run Mintlify on a port that's already in use, it will use the next available port:

```md
Port 3000 is already in use. Trying 3001 instead.
```

## Mintlify Versions

Please note that each CLI release is associated with a specific version of Mintlify. If your local website doesn't align with the production version, please update the CLI:

### Update CLI Version
Keep your CLI up to date for the latest features:
<CodeGroup>

```bash npm
npm i -g mintlify@latest
```

```bash npm
npm i -g mintlify@latest
```
```bash yarn
yarn global upgrade mintlify
```

</CodeGroup>

## Validating Links

The CLI can assist with validating reference links made in your documentation. To identify any broken links, use the following command:

### Validate Links
Check for broken documentation links:
```bash
mintlify broken-links
```

## Deployment

If the deployment is successful, you should see the following:
## Development Tips

<Frame>
<img
className="rounded-md"
src="https://mintlify.s3-us-west-1.amazonaws.com/mintlify/images/checks-passed.png"
/>
</Frame>

## Code Formatting

We suggest using extensions on your IDE to recognize and format MDX. If you're a VSCode user, consider the [MDX VSCode extension](https://marketplace.visualstudio.com/items?itemName=unifiedjs.vscode-mdx) for syntax highlighting, and [Prettier](https://marketplace.visualstudio.com/items?itemName=esbenp.prettier-vscode) for code formatting.

## Troubleshooting
- **IDE Setup**: Use the [MDX VSCode extension](https://marketplace.visualstudio.com/items?itemName=unifiedjs.vscode-mdx) for syntax highlighting and [Prettier](https://marketplace.visualstudio.com/items?itemName=esbenp.prettier-vscode) for formatting.

<AccordionGroup>
<Accordion title='Error: Could not load the "sharp" module using the darwin-arm64 runtime'>

This may be due to an outdated version of node. Try the following:
1. Remove the currently-installed version of mintlify: `npm remove -g mintlify`
2. Upgrade to Node v19 or higher.
3. Reinstall mintlify: `npm install -g mintlify`
</Accordion>

<Accordion title="Issue: Encountering an unknown error">

Solution: Go to the root of your device and delete the \~/.mintlify folder. Afterwards, run `mintlify dev` again.
<Accordion title='Troubleshooting Common Issues'>
- **Sharp Module Error**: Update to Node v19+, then remove and reinstall Mintlify
- **Unknown Errors**: Delete ~/.mintlify folder and restart
</Accordion>
</AccordionGroup>
</AccordionGroup>
37 changes: 13 additions & 24 deletions integrations/analytics/google-analytics.mdx
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -2,28 +2,20 @@
title: "Google Analytics 4"
---

You will need to generate a new <Tooltip tip="Google Analytics 4">GA4</Tooltip> property to use with Mintlify. The data collected will go into the same project as your other Google Analytics data.
Mintlify supports Google Analytics 4 (<Tooltip tip="Google Analytics 4">GA4</Tooltip>) integration for tracking your documentation usage. Follow these steps to set it up:

If you are using the old version of Google Analytics, Universal Analytics, you will still be able to generate a <Tooltip tip="Google Analytics 4">GA4</Tooltip> property. <Tooltip tip="Google Analytics 4">GA4</Tooltip> data is slightly different from UA data but still gets collected in the same project.
## Setup Steps

## How to Connect GA4 to Mintlify

### Create a Web Stream

You will need to create a web stream to get the Measurement ID to put into Mintlify.

Click the cog at the bottom left of the Google Analytics screen. Then click on Data Streams.
1. Create a GA4 property in your Google Analytics account if you haven't already
2. Create a Web Stream:
- Go to Admin (cog icon) → Data Streams
- Click "Add Stream" → "Web"
- Enter your Mintlify docs URL
- Copy your Measurement ID (format: `G-XXXXXXX`)

<Frame>![](/images/ga4-web-streams.png)</Frame>

Create a Web Stream and put the URL of your Mintlify docs site as the stream URL.

Your Measurement ID looks like `G-XXXXXXX` and will show up under Stream Details immediately after you create the Web Stream.

### Put Measurement ID in mint.json

Add your Measurement ID to your `mint.json` file like so:

3. Add the Measurement ID to your `mint.json`:
```json mint.json
"analytics": {
"ga4": {
Expand All @@ -32,14 +24,11 @@ Add your Measurement ID to your `mint.json` file like so:
}
```

### Wait

Google Analytics takes two to three days to show your data.
## Verification

You can use the [Google Analytics Debugger](https://chrome.google.com/webstore/detail/google-analytics-debugger/jnkmfdileelhofjcijamephohjechhna?hl=en) to check analytics are enabled correctly. The extension will log to your browser's console every time GA4 makes a request.
- Data typically appears in Google Analytics after 2-3 days
- Use the [Google Analytics Debugger](https://chrome.google.com/webstore/detail/google-analytics-debugger/jnkmfdileelhofjcijamephohjechhna?hl=en) to verify setup

<Note>

Preview links have analytics turned off.

</Note>
</Note>
44 changes: 18 additions & 26 deletions integrations/sdks/speakeasy.mdx
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -3,11 +3,11 @@ title: Speakeasy
description: Automate your SDK usage snippets in the API playground
---

You can integrate Speakeasy-generated code snippets from your SDKs directly into your Mintlify API reference documentation. SDK usage snippets are shown in the [interactive playground](https://mintlify.com/docs/api-playground/overview) of your Mintlify-powered documentation.
Speakeasy-generated code snippets from your SDKs can be integrated directly into your Mintlify API reference documentation. These snippets appear in the [interactive playground](https://mintlify.com/docs/api-playground/overview) of your documentation.

## Speakeasy SDK Repository Changes
## SDK Configuration

In your Speakeasy SDK repos, add the following to the `targets` section of your `.speakeasy/workflow.yaml` file to ensure code samples are automatically produced alongside SDK generations.
Add the following to the `targets` section of your SDK's `.speakeasy/workflow.yaml` file:

```yaml .speakeasy/workflow.yaml
targets:
Expand All @@ -18,39 +18,29 @@ targets:
output: codeSamples.yaml
```

Code samples will be generated in the form of an [OpenAPI overlay file](https://www.speakeasyapi.dev/openapi/overlays) that will be used in the Mintlify docs repository.
This generates code samples as an [OpenAPI overlay file](https://www.speakeasyapi.dev/openapi/overlays) for use in your Mintlify docs.

## Mintlify Docs Repository Changes
## Setup Options

The workflow files produced will automatically bundle your source OpenAPI spec and Speakeasy code samples into a single output file, `openapi.yaml`. Mintlify will use this output file when constructing your API reference.
You can set up Speakeasy integration either through the CLI or manual configuration.

### Interactive CLI Set Up
### Option 1: Interactive CLI Setup

Run the following commands to set up the `.speakeasy/workflow.yaml` and `.github/workflows/sdk_generation.yaml` files through the interactive Speakeasy CLI.
Run these commands to configure your environment:

```bash
speakeasy configure sources
speakeasy configure github
```

Set up your source spec. The source spec is the OpenAPI spec that code samples will be generated for, and it's often the same specification used to power Mintlify docs.
Follow the CLI prompts to:
1. Set up your source OpenAPI spec
2. Add the Speakeasy overlay for code snippets
3. Configure the output spec path for Mintlify

![](/images/speakeasy-1.webp)

Add the overlay created by Speakeasy to inject code snippets into your spec.

![](/images/speakeasy-2.webp)

Provide a name and path for the OpenAPI spec. This will be the final spec used by Mintlify.

![](/images/speakeasy-3.webp)

Finally, Add your `SPEAKEASY_API_KEY` as a repository secret to your Minlify repo under `Settings > Secrets & Variables > Actions`. Find the Speakeasy API key in the Speakeasy dashboard under the **API Keys** tab.

## Manual Set Up

Alternatively, you can manually set up the following files in your Mintlify docs repo.
### Option 2: Manual Setup

Create the following configuration files in your Mintlify docs repo:

```yaml .speakeasy/workflow.yaml
workflowVersion: 1.0.0
Expand All @@ -66,7 +56,7 @@ sources:
targets: {}
```

```yaml .speakeasy/workflows/sdk_generation.yaml
```yaml .github/workflows/sdk_generation.yaml
name: Generate
permissions:
checks: write
Expand Down Expand Up @@ -94,4 +84,6 @@ jobs:
speakeasy_api_key: ${{ secrets.SPEAKEASY_API_KEY }}
```

Finally, make sure you add your `SPEAKEASY_API_KEY` as a repository secret to your Minlify repo under `Settings > Secrets & Variables > Actions`. Find the Speakeasy API key in the Speakeasy dashboard under the **API Keys** tab.
## Final Step

Add your `SPEAKEASY_API_KEY` as a repository secret under `Settings > Secrets & Variables > Actions`. You can find this key in the Speakeasy dashboard under the **API Keys** tab.
22 changes: 12 additions & 10 deletions integrations/sdks/stainless.mdx
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -3,18 +3,21 @@ title: Stainless
description: Automate your SDK example snippets in the API playground
---

If you use Mintlify's OpenAPI support for your API reference documentation, add the following to your Stainless config:
Follow these steps to integrate Stainless with your Mintlify documentation:

1. Add this to your Stainless config:

```yaml openapi.stainless.yml
openapi:
code_samples: mintlify
```

Configure the [OpenAPI setup](/api-playground/openapi/setup#in-the-repo) in your Mintlify docs. To integrate Stainless, modify the GitHub Action that uploads your OpenAPI spec to Stainless so that it pushes the Stainless-enhanced OpenAPI spec into your docs repo like so:
2. Configure the [OpenAPI setup](/api-playground/openapi/setup#in-the-repo) in your Mintlify docs.

3. Add this GitHub Action to automatically sync your OpenAPI spec between Stainless and your docs:

```yaml
name: Upload OpenAPI spec to Stainless and (Mintlify) docs repo
name: Sync OpenAPI Spec

on:
push:
Expand All @@ -40,13 +43,12 @@ jobs:
with:
source_file: 'config/my-company-openapi.documented.json'
destination_repo: '{DOCS_REPO_NAME}'
destination_folder: 'openapi-specs' # (optional) the folder in the destination repository to place the file in, if not the root directory
user_email: '{EMAIL}' # the email associated with the GH token
user_name: '{USERNAME}' # the username associated with the GH token
destination_folder: 'openapi-specs'
user_email: '{EMAIL}'
user_name: '{USERNAME}'
commit_message: 'Auto-updates from Stainless'
```

This assumes the following secrets have been [uploaded to your GitHub Actions Secrets](https://docs.github.com/en/actions/security-guides/using-secrets-in-github-actions):

- `secrets.STAINLESS_API_KEY`: Your Stainless API key.
- `secrets.API_TOKEN_GITHUB`: A GitHub [Personal Access Token](https://docs.github.com/en/authentication/keeping-your-account-and-data-secure/managing-your-personal-access-tokens) with permissions to push to your docs repo.
4. Add these GitHub secrets to your repository:
- `STAINLESS_API_KEY`: Your Stainless API key
- `API_TOKEN_GITHUB`: A GitHub [Personal Access Token](https://docs.github.com/en/authentication/keeping-your-account-and-data-secure/managing-your-personal-access-tokens) with push access to your docs repo
Loading
Loading