diff --git a/advanced/widget/chat.mdx b/advanced/widget/chat.mdx index 216179a7a..bf4522514 100644 --- a/advanced/widget/chat.mdx +++ b/advanced/widget/chat.mdx @@ -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 `...` 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 `` tag: ```html ``` -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 ``` -## 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 | | ------------ | ------------------------------------------------------------------- | ---------------------------------------------------------- | @@ -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. | \ No newline at end of file diff --git a/development.mdx b/development.mdx index 15581014c..f09ad76df 100644 --- a/development.mdx +++ b/development.mdx @@ -4,99 +4,59 @@ description: 'Preview changes locally to update your docs' --- - -**Prerequisite**: Please install Node.js (version 19 or higher) before proceeding. - +**Prerequisite**: Node.js (version 19 or higher) -**Step 1**: Install Mintlify: +## Quick Start +1. Install Mintlify CLI: - - ```bash npm - npm i -g mintlify - ``` - +```bash npm +npm i -g mintlify +``` ```bash yarn yarn global add mintlify ``` - -**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: - - ```bash npm - npm i -g mintlify@latest - ``` - +```bash npm +npm i -g mintlify@latest +``` ```bash yarn yarn global upgrade mintlify ``` - -## 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 - - - - -## 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. - - - 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` - - - - - Solution: Go to the root of your device and delete the \~/.mintlify folder. Afterwards, run `mintlify dev` again. + + - **Sharp Module Error**: Update to Node v19+, then remove and reinstall Mintlify + - **Unknown Errors**: Delete ~/.mintlify folder and restart - + \ No newline at end of file diff --git a/integrations/analytics/google-analytics.mdx b/integrations/analytics/google-analytics.mdx index 7ebfe1610..67485a5e1 100644 --- a/integrations/analytics/google-analytics.mdx +++ b/integrations/analytics/google-analytics.mdx @@ -2,28 +2,20 @@ title: "Google Analytics 4" --- -You will need to generate a new GA4 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 (GA4) 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 GA4 property. GA4 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`) ![](/images/ga4-web-streams.png) -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": { @@ -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 - Preview links have analytics turned off. - - + \ No newline at end of file diff --git a/integrations/sdks/speakeasy.mdx b/integrations/sdks/speakeasy.mdx index d45628bed..679173ba3 100644 --- a/integrations/sdks/speakeasy.mdx +++ b/integrations/sdks/speakeasy.mdx @@ -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: @@ -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 @@ -66,7 +56,7 @@ sources: targets: {} ``` -```yaml .speakeasy/workflows/sdk_generation.yaml +```yaml .github/workflows/sdk_generation.yaml name: Generate permissions: checks: write @@ -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. \ No newline at end of file diff --git a/integrations/sdks/stainless.mdx b/integrations/sdks/stainless.mdx index 8a21bfab4..4dacb61c3 100644 --- a/integrations/sdks/stainless.mdx +++ b/integrations/sdks/stainless.mdx @@ -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: @@ -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 \ No newline at end of file diff --git a/quickstart.mdx b/quickstart.mdx index fc6eb786c..f211b422b 100644 --- a/quickstart.mdx +++ b/quickstart.mdx @@ -17,165 +17,51 @@ icon: "rocket" ## Getting Started -Welcome! Follow the instructions below to learn how to deploy, update and -supercharge your documentation with Mintlify. +Welcome to Mintlify! Follow these three simple steps to get your documentation up and running. -### Creating the Repository +### 1. Set Up Your Repository -Mintlify docs are rendered from MDX files and configurations defined in our -[starter kit](https://github.com/mintlify/starter). We use GitHub to integrate -your docs with your code, and make source control effortless. +1. Clone our [starter template](https://github.com/mintlify/starter) into a new repository +2. Install our [GitHub app](https://dashboard.mintlify.com/settings) to enable automatic deployments - - - - If you've created a docs repo in our onboarding, this step is complete. You can find your docs repository on your Mintlify [dashboard](https://dashboard.mintlify.com). - - To create your docs repo without logging into GitHub, follow these instructions: - 1. Clone our [starter template](https://github.com/mintlify/starter) into a new public repo. You can make the repo private later. - 2. [Get in touch](mailto:support@mintlify.com) with our team to deploy your repo. - - - ![Starter Template](https://mintlify.s3-us-west-1.amazonaws.com/mintlify/images/starter-template.png) - - - - - - - The next step is to install our GitHub app. This ensures that your updates are automatically deployed when you push changes. You can find the installation link in the [dashboard](https://dashboard.mintlify.com/settings), on the Settings page. Upon successful installation, a check mark will appear next to the commit hash of the repository. - - - ![GitHub Bot Verification](https://mintlify.s3-us-west-1.amazonaws.com/mintlify/images/github-bot-verification.png) - - - +### 2. Update Your Content - - -### Updating the Content - -Mintlify enables you to easily customize the style, structure, and content of -your docs. +Choose your preferred editing method: - - - 1. Install [git](https://git-scm.com/book/en/v2/Getting-Started-Installing-Git). - 2. Once git is installed, clone your docs repository using `git clone `. If you haven't set it up yet, now would be a good time to do so with these [SSH keys](https://docs.github.com/en/authentication/connecting-to-github-with-ssh/generating-a-new-ssh-key-and-adding-it-to-the-ssh-agent). - 3. Use your favorite IDE to open the repository. - 4. Install our Mintlify CLI to preview changes with `npm i -g mintlify`. - - Learn more about this in our [local development guide](/development). - - - - - - Learn more about how to use the web editor on our [guide](/web-editor). - - - - - - Easily customize colors, logos and buttons among other configurations in our `mint.json` file. Start with these basic configurations: - - ```json - "name": "Your Company" - "logo": { - "light": "/logo/light.svg", - "dark": "/logo/dark.svg", - "href": "https://yourcompany.com" - }, - "favicon": "/favicon.svg", - "colors": { - "primary": "#2AB673", - "light": "#55D799", - "dark": "#117866", - }, - ``` - - A full list of supported configurations can be found at [global settings](/settings/global). - + + 1. Install [git](https://git-scm.com/book/en/v2/Getting-Started-Installing-Git) + 2. Clone your docs repository + 3. Install Mintlify CLI: `npm i -g mintlify` + 4. Start editing in your IDE - - - Add content with simple MDX files. Initiate your pages with this template: - - ```md - --- - title: "Page Title" - sidebarTitle: "Sidebar title (optional - if different from page title)" - description: "Subtitle (optional)" - --- - ``` - - Learn more about adding images, tables, lists, and more using the [MDX syntax](/text). We also offer a [wide array of components](/content/components). - - - - - - Once ready, commit and push your changes to update your docs site. Here is a [guide](https://docs.github.com/en/get-started/using-git/pushing-commits-to-a-remote-repository#about-git-push) on how to do that. If the GitHub app is unable to successfully deploy your changes, you can manually update your docs through our [dashboard](https://dashboard.mintlify.com). - - - ![Manual Update](https://mintlify.s3-us-west-1.amazonaws.com/mintlify/images/manual-update.png) - - - - - - - You can easily set up your API references using an OpenAPI document. - - 1. Add your `openapi.yaml` or `openapi.json` file into your docs repository or define the `openapi` field in `mint.json` with a URL. - - ```json - "openapi": "link-to-your-openapi-file" - ``` - - 2. Use our [scraper](/api-playground/openapi/setup#autogenerate-files-recommended) to autogenerate your OpenAPI endpoints files as: - - ```bash - npx @mintlify/scraping@latest openapi-file - ``` - - 3. Finally, include the generated endpoint MDX files to your `mint.json` under `navigation`. - - For a complete guide on using Mintlify with OpenAPI, check out [this guide](/api-playground/openapi/setup). [This guide](/api-playground/openapi/writing-openapi) explains how to configure your API authentication methods. For manual API references definition, explore [our syntax](/api-playground/overview). - - - - - - Our in-house analytics give you insights into page views, search analytics, session recordings and more. Access these on your [dashboard](https://dashboard.mintlify.com/analytics). - - We also support integrations with a range of analytics providers. You can find the list of providers [here](/integrations/analytics/overview). - + + Access our web editor through the [dashboard](https://dashboard.mintlify.com) - - We provide a white-glove migration service as part of our Enterprise plan. - Interested? You can request it by [contacting us](mailto:sales@mintlify.com). - +### 3. Customize Your Docs -### Publishing +Update your `mint.json` file to match your brand: - +```json +{ + "name": "Your Company", + "logo": { + "light": "/logo/light.svg", + "dark": "/logo/dark.svg" + }, + "colors": { + "primary": "#2AB673" + } +} +``` - Integrate your docs into your website by hosting them on a custom domain. This is included even in the free plan. - - Navigate to your [dashboard settings](https://www.dashboard.mintlify.com/settings) to add a custom domain. - - - ![Custom Domain](/images/custom-domain.png) - +### Next Steps - +- Add API references using our [OpenAPI integration](/api-playground/openapi/setup) +- Set up a [custom domain](https://dashboard.mintlify.com/settings) +- Explore our [component library](/content/components) -Congrats! You've set up your Mintlify Docs and it's looking amazing! Need -support or want to give some feedback? You can join our -[community](https://mintlify.com/community) or drop us an email at -[support@mintlify.com](mailto:support@mintlify.com). +Need help? Join our [community](https://mintlify.com/community) or contact [support@mintlify.com](mailto:support@mintlify.com). \ No newline at end of file