diff --git a/advanced/rest-api/overview.mdx b/advanced/rest-api/overview.mdx index f9d74b067..05273b1ae 100644 --- a/advanced/rest-api/overview.mdx +++ b/advanced/rest-api/overview.mdx @@ -4,16 +4,11 @@ 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)! +Use our REST API to trigger updates programmatically. More API functionality is in development - share feature requests 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). One API key works for all deployments in your org. @@ -21,12 +16,11 @@ associated with the entire org and can be used across multiple deployments. ## 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 lets you embed AI chat into any app. The chat is powered by your docs and provides cited responses to help users find information. ## Getting Started -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): - 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. + Discovery API tokens are public and safe for frontend code. API keys are for server-side use only and should remain private. -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). +See our [example implementation](https://github.com/mintlify/discovery-api-example) or check out the live demo at [chat.mintlify.com](https://chat.mintlify.com). \ No newline at end of file diff --git a/advanced/subpath/cloudflare.mdx b/advanced/subpath/cloudflare.mdx index 13ff2d841..a53a65288 100644 --- a/advanced/subpath/cloudflare.mdx +++ b/advanced/subpath/cloudflare.mdx @@ -5,9 +5,7 @@ description: "Host documentation at a /docs subpath using Cloudflare Workers" ## Create Cloudflare Worker -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. +Go to `Workers & Pages > Create application > Create worker` to set up a new Cloudflare worker. Create a Cloudflare worker @@ -15,10 +13,11 @@ Cloudlfare worker. ### 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. +After creating the worker: +1. Click `Configure worker` +2. Go to `Settings > Triggers` +3. Click `Add Custom Domain` +4. Add your domain (both with and without `www.`) -If you have trouble setting up a custom subdirectory, -[contact our support team](mailto:sales@mintlify.com) and we'll walk you through -upgrading your hosting with us. +Need help? [Contact our support team](mailto:sales@mintlify.com) for hosting upgrades. ### Edit Worker Script -Click on `Edit Code` and add the following script into the worker's code. +Click `Edit Code` and add this script: Cloudflare edit code - Edit `DOCS_URL` by replacing `[SUBDOMAIN]` with your unique subdomain and - `CUSTOM_URL` with your website's base URL. + Replace `[SUBDOMAIN]` with your subdomain and `CUSTOM_URL` with your website's URL in `DOCS_URL`. ```javascript @@ -76,5 +72,4 @@ async function handleRequest(request) { } ``` -Click on `Deploy` and wait for the changes to propagate (it can take up to a few -hours). +Deploy and wait for changes to propagate (up to a few hours). \ No newline at end of file diff --git a/api-playground/mdx/configuration.mdx b/api-playground/mdx/configuration.mdx index 55682df30..2f06e3c11 100644 --- a/api-playground/mdx/configuration.mdx +++ b/api-playground/mdx/configuration.mdx @@ -1,13 +1,13 @@ --- title: 'MDX Setup' -description: 'Generate docs pages for your API endpoints using MDX' +description: 'Generate API docs using MDX' --- -Mintlify allows you to define your API endpoints using a combination of `mint.json` configuration, MDX metadata fields, and the `` component. From the defined endpoints, we generate an API playground, request examples, and response examples. +Define your API endpoints using `mint.json` config, MDX metadata, and the `` component to generate an API playground with request and response examples. - In your `mint.json` file, define your base URL and auth method: + Add API configuration to your `mint.json`: ```json { @@ -20,7 +20,7 @@ Mintlify allows you to define your API endpoints using a combination of `mint.js } ``` - 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: ```json { @@ -32,12 +32,11 @@ 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). + See all API configurations [here](/settings/global#api-configurations). - - - Each API endpoint page should have a corresponding MDX file. At the top of each file, define: + + Create an MDX file for each endpoint with the required metadata: ```md --- @@ -46,20 +45,18 @@ 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 path parameters, use `{}`: ```bash https://api.example.com/v1/endpoint/{userId} ``` - - If you have `baseUrl` configured in [mint.json](/settings/global), you can use relative paths like `/v1/endpoint`. - + With `baseUrl` configured in mint.json, you can use relative paths like `/v1/endpoint` - - 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). + + Add endpoint pages to your sidebar in `mint.json`'s `navigation` field. See [navigation docs](/settings/navigation). - + \ No newline at end of file diff --git a/api-playground/openapi/setup.mdx b/api-playground/openapi/setup.mdx index bc24fbbf6..d72dd0f84 100644 --- a/api-playground/openapi/setup.mdx +++ b/api-playground/openapi/setup.mdx @@ -5,16 +5,13 @@ description: "Reference OpenAPI endpoints in your docs pages" ## Add an OpenAPI specification file -To describe your endpoints with OpenAPI, make sure you have a valid OpenAPI -document in either JSON or YAML format that follows the -[OpenAPI specification](https://swagger.io/specification/). Your document must -follow OpenAPI specification 3.0+. +Add your OpenAPI document (JSON or YAML) following the [OpenAPI 3.0+ specification](https://swagger.io/specification/). ## Auto-populate API pages -The fastest way to get started with OpenAPI is to add an `openapi` field to a tab or anchor in the `mint.json`. This field can contain either the path to an OpenAPI document in your docs repo, or the URL of a hosted OpenAPI document. Mintlify will automatically generate a page for each OpenAPI operation and place them in the tab/anchor. +The quickest setup: Add an `openapi` field to your `mint.json` under a tab or anchor. Use either a file path or URL to your OpenAPI doc. -**Example with Anchors:** +**Using Anchors:** ```json {5} { @@ -29,9 +26,7 @@ The fastest way to get started with OpenAPI is to add an `openapi` field to a ta } ``` -![](/images/anchors-autogeneration-anchors.png) - -**Example with Tabs:** +**Using Tabs:** ```json {6} { @@ -45,108 +40,50 @@ The fastest way to get started with OpenAPI is to add an `openapi` field to a ta } ``` -![](/images/autogeneration-with-tabs.png) - -To validate your OpenAPI spec, you can use this command:
`mintlify openapi-check ` - - -When using this option, the metadata for the generated pages will have the following default values: - -* `title`: The `summary` field from the OpenAPI operation, if present. Otherwise a title generated from the HTTP method and endpoint. - -* `description`: The `description` field from the OpenAPI operation, if present. - -* `version`: The `version` value from the anchor or tab, if present. +Validate your OpenAPI spec: `mintlify openapi-check ` -There are some scenarios in which the default behavior isn't sufficient. If you need more customizability, you can create an MDX page for your OpenAPI operation, and modify it just like any other MDX page. +Default page metadata will use: +- `title`: OpenAPI operation's `summary` or auto-generated from method/endpoint +- `description`: OpenAPI operation's `description` +- `version`: Anchor/tab's version value -## Create MDX files for API pages +## Custom API Pages -If you want to customize the page metadata, add additional content, omit certain OpenAPI operations, or reorder OpenAPI pages in your navigation, you'll need an MDX page for each operation. Here is [an example MDX OpenAPI page](https://github.com/elevenlabs/elevenlabs-docs/blob/e5e267c97b8d1e4c21db1dcdb8b005eb1dfed7da/api-reference/speech-to-speech.mdx?plain=1#L2) from [Elevenlabs](https://elevenlabs.io/docs/api-reference/speech-to-speech). +Need more control? Create MDX pages for your API operations. -![](/images/elevenlabs-mdx-autogeneration-example.png) - -### Autogenerate files - -For large OpenAPI documents, creating one MDX page for each OpenAPI operation can be a lot of work. To make it easier, we created a local OpenAPI page scraper. - -Our Mintlify [scraper](https://www.npmjs.com/package/@mintlify/scraping) -autogenerates MDX files for your OpenAPI endpoints. Use the relative path to the -OpenAPI document in your codebase. - -```bash -npx @mintlify/scraping@latest openapi-file -``` +### Generate MDX Files Automatically -Add the `-o` flag to specify a folder to populate the files into. If a folder is -not specified, the files will populate in the working directory. +For large APIs, use our scraper to generate MDX files: ```bash npx @mintlify/scraping@latest openapi-file -o api-reference ``` -Learn more about our scraping package [here](https://www.npmjs.com/package/@mintlify/scraping). - -The scraper will output an array of -[Navigation entries](/settings/global#structure) containing your OpenAPI MDX -files. You can either append these entries to your existing Navigation, or -reorder and add the files to your navigation manually. - - If your OpenAPI document is invalid, the files will not autogenerate. + Invalid OpenAPI docs won't generate files. -### Manually specify files - -You can always create an MDX page manually, and reference the OpenAPI operation in the page's metadata using the `openapi` field. - - - -By using the OpenAPI reference, the name, description, parameters, responses, -and the API playground will be automatically generated from the OpenAPI document. - -If you have multiple OpenAPI files, include the path to the OpenAPI file to ensure Mintlify finds the correct OpenAPI document. This is not required if you have -only one OpenAPI file - it will automatically detect your OpenAPI file. - - - ```md Example - --- - title: "Get users" - openapi: "/path/to/openapi-1.json GET /users" - --- - ``` +### Manual MDX Creation - ```md Format - --- - title: "title of the page" - openapi: openapi-file-path method path - --- - ``` - +Create custom MDX pages by referencing OpenAPI operations in the frontmatter: -
+```md +--- +title: "Get users" +openapi: "/path/to/openapi.json GET /users" +--- +``` - The method and path must match the method and path specified in the OpenAPI - document exactly. If the endpoint doesn't exist in the OpenAPI file, - the page will be empty. + Method and path must exactly match your OpenAPI document. -## Create MDX files for OpenAPI schemas +## OpenAPI Schema Pages -Mintlify also allows you to create individual pages for any OpenAPI schema -defined in an OpenAPI document's `components.schemas` field: +Create pages for schema definitions using: - - ```md Example - --- - openapi-schema: OrderItem - --- - ``` - - ```md Format - --- - openapi-schema: "schema-key" - --- - ``` - \ No newline at end of file +```md +--- +openapi-schema: "schema-key" +--- +``` \ No newline at end of file diff --git a/code.mdx b/code.mdx index b137fcce0..d42f86a69 100644 --- a/code.mdx +++ b/code.mdx @@ -8,15 +8,15 @@ icon: 'code' ### Inline Code -To denote a `word` or `phrase` as code, enclose it in backticks (`). +Use backticks (`) to mark `code` within text. ``` -To denote a `word` or `phrase` as code, enclose it in backticks (`). +Use backticks (`) to mark `code` within text. ``` ### Code Block -Use [fenced code blocks](https://www.markdownguide.org/extended-syntax/#fenced-code-blocks) by enclosing code in three backticks and follow the leading ticks with the programming language of your snippet to get syntax highlighting. Optionally, you can also write the name of your code after the programming language. +Create code blocks using three backticks. Add a language name for syntax highlighting, and optionally a filename. ```java HelloWorld.java class HelloWorld { @@ -36,4 +36,4 @@ class HelloWorld { ``` ```` -Visit the [Code Block page](/content/components/code) for more detailed docs. +For more details, see the [Code Block page](/content/components/code). \ No newline at end of file diff --git a/content/components/code.mdx b/content/components/code.mdx index d59351bb4..59822bee2 100644 --- a/content/components/code.mdx +++ b/content/components/code.mdx @@ -16,7 +16,7 @@ const hello = "world"; ## Basic Code Block -Use [fenced code blocks](https://www.markdownguide.org/extended-syntax/#fenced-code-blocks) by enclosing code in three backticks. +Use triple backticks to create code blocks: ``` helloWorld(); @@ -30,9 +30,7 @@ helloWorld(); ## Syntax Highlighting -Put the name of your programming language after the three backticks to get syntax highlighting. - -We use [Prism](https://prismjs.com/#supported-languages) for syntax highlighting. [Test Drive Prism](https://prismjs.com/test.html#language=markup) lists all the languages supported. +Add a language identifier after the backticks for syntax highlighting. We use [Prism](https://prismjs.com/#supported-languages). ```java class HelloWorld { @@ -54,7 +52,7 @@ class HelloWorld { ## Names -You can add more text after the programming language to set the name of your code example. The text can be anything as long as its all in one line. +Add text after the language to name your code example: ```javascript Code Block Example const hello = "world"; @@ -68,7 +66,7 @@ const hello = "world"; ## Line Highlighting -You can highlight specific lines in your code blocks by adding a special comment after the language identifier. Use curly braces `{}` and specify line numbers or ranges separated by commas. +Highlight specific lines using `{line-numbers}` after the language identifier: ```javascript Line Highlighting Example {1,3-5} const greeting = "Hello, World!"; @@ -90,7 +88,7 @@ sayHello(); ## Code Groups -Want to display multiple code examples in one code box? Check out the Code Group docs: +Need multiple code examples in one block? See the Code Group docs: Read the reference for the Code Group component + + \ No newline at end of file diff --git a/development.mdx b/development.mdx index 856629aaf..7862dbd9c 100644 --- a/development.mdx +++ b/development.mdx @@ -1,18 +1,17 @@ --- title: 'Local Development' -description: 'Preview changes locally to update your docs' +description: 'Preview docs locally' --- - -**Prerequisite**: Please install Node.js (version 19 or higher) before proceeding. - +Requires Node.js v19+ -**Step 1**: Install Mintlify: +## Install and Run - +**1. Install Mintlify** + ```bash npm npm i -g mintlify ``` @@ -24,16 +23,17 @@ description: 'Preview changes locally to update your docs' ```bash pnpm pnpm add -g mintlify ``` - -**Step 2**: Navigate to the docs directory (where the `mint.json` file is located) and execute the following command: +**2. Start Dev Server** + +Run this in your docs directory (where `mint.json` is): ```bash mintlify dev ``` -Alternatively, if you do not want to install Mintlify globally you can use a run script available: +Alternatively, run without global installation: ```bash npm @@ -47,35 +47,26 @@ Alternatively, if you do not want to install Mintlify globally you can use a run ```bash pnpm pnpm dlx mintlify dev ``` - - Yarn's "dlx" run script requires yarn version >2. See [here](https://yarnpkg.com/cli/dlx) for more information. + Yarn's "dlx" needs yarn v2+. [Details](https://yarnpkg.com/cli/dlx) -A local preview of your documentation will be available at `http://localhost:3000`. - -### Custom Ports +Preview at `http://localhost:3000` -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: +## Custom Port +Change the default port (3000): ```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: +## Updates -```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 to match production: - ```bash npm npm i -g mintlify@latest ``` @@ -87,20 +78,18 @@ Please note that each CLI release is associated with a specific version of Mintl ```bash pnpm pnpm up --global mintlify ``` - -## Validating Links - -The CLI can assist with validating reference links made in your documentation. To identify any broken links, use the following command: +## Link Validator +Check for broken links: ```bash mintlify broken-links ``` ## Deployment -If the deployment is successful, you should see the following: +Successful deployment shows: -## Code Formatting +## Editor Setup -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. +For VSCode users: +- [MDX extension](https://marketplace.visualstudio.com/items?itemName=unifiedjs.vscode-mdx) for syntax highlighting +- [Prettier](https://marketplace.visualstudio.com/items?itemName=esbenp.prettier-vscode) for formatting ## Troubleshooting - - - 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` + + 1. Remove mintlify: `npm remove -g mintlify` + 2. Upgrade to Node v19+ + 3. Reinstall: `npm install -g mintlify` - - - Solution: Go to the root of your device and delete the \~/.mintlify folder. Afterwards, run `mintlify dev` again. + + Delete ~/.mintlify folder and run `mintlify dev` again - + \ No newline at end of file diff --git a/integrations/analytics/clearbit.mdx b/integrations/analytics/clearbit.mdx index 629525434..5363d3104 100644 --- a/integrations/analytics/clearbit.mdx +++ b/integrations/analytics/clearbit.mdx @@ -2,7 +2,7 @@ title: "Clearbit" --- -Add the following to your `mint.json` file to send analytics to Clearbit. +Configure Clearbit analytics in `mint.json`: @@ -23,3 +23,4 @@ Add the following to your `mint.json` file to send analytics to Clearbit. ``` + \ No newline at end of file diff --git a/integrations/analytics/google-analytics.mdx b/integrations/analytics/google-analytics.mdx index 7ebfe1610..3bd95ede1 100644 --- a/integrations/analytics/google-analytics.mdx +++ b/integrations/analytics/google-analytics.mdx @@ -2,27 +2,24 @@ 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. +Generate a new GA4 property for your Mintlify documentation. If you're using Universal Analytics (UA), you can still create a GA4 property in the same project. -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 +### 1. Create a Web Stream -### 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. Go to Google Analytics settings (cog icon, bottom left) +2. Navigate to Data Streams +3. Click "Add Stream" > "Web" +4. Enter your Mintlify docs URL ![](/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. +Your Measurement ID (format: `G-XXXXXXX`) will appear in Stream Details. -### Put Measurement ID in mint.json +### 2. Configure mint.json -Add your Measurement ID to your `mint.json` file like so: +Add your Measurement ID: ```json mint.json "analytics": { @@ -32,14 +29,12 @@ Add your Measurement ID to your `mint.json` file like so: } ``` -### Wait +### 3. Verification -Google Analytics takes two to three days to show your data. - -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 appears in GA4 within 2-3 days +- Use [Google Analytics Debugger](https://chrome.google.com/webstore/detail/google-analytics-debugger/jnkmfdileelhofjcijamephohjechhna?hl=en) to verify setup +- Check browser console for GA4 requests - -Preview links have analytics turned off. - - +Preview links don't track analytics. + \ No newline at end of file diff --git a/integrations/analytics/hotjar.mdx b/integrations/analytics/hotjar.mdx index a872a8f72..e75bda99d 100644 --- a/integrations/analytics/hotjar.mdx +++ b/integrations/analytics/hotjar.mdx @@ -2,7 +2,7 @@ title: "HotJar" --- -Add the following to your `mint.json` file to send analytics to HotJar. +Add to `mint.json` to enable HotJar analytics: ```json Analytics options in mint.json "analytics": { @@ -11,4 +11,4 @@ Add the following to your `mint.json` file to send analytics to HotJar. "hjsv": "required" } } -``` +``` \ No newline at end of file diff --git a/integrations/analytics/pirsch.mdx b/integrations/analytics/pirsch.mdx index e4b3e3085..8b24375ad 100644 --- a/integrations/analytics/pirsch.mdx +++ b/integrations/analytics/pirsch.mdx @@ -2,26 +2,21 @@ title: "Pirsch" --- -Add the following to your `mint.json` file to send analytics to Pirsch. +Add Pirsch analytics to your `mint.json`: -You can get your site ID from Settings \> Developer \> Identification Code. - - - -```json Analytics options in mint.json +```json "analytics": { "pirsch": { - "id": "required" + "id": "required" // Get from Settings > Developer > Identification Code } } ``` -```json Example +Example: +```json "analytics": { "pirsch": { "id": "8Kw7OKxBfswOjnKGZa7P9Day8JmVYwTp" } } -``` - - +``` \ No newline at end of file diff --git a/integrations/analytics/segment.mdx b/integrations/analytics/segment.mdx index 1f1b8076b..a296a3d2f 100644 --- a/integrations/analytics/segment.mdx +++ b/integrations/analytics/segment.mdx @@ -2,7 +2,7 @@ title: "Segment" --- -Add your Segment write key to your `mint.json` file to send analytics to Segment. +Add your Segment write key in `mint.json`: diff --git a/integrations/privacy/osano.mdx b/integrations/privacy/osano.mdx index ded3d2d59..fc1044d35 100644 --- a/integrations/privacy/osano.mdx +++ b/integrations/privacy/osano.mdx @@ -2,7 +2,7 @@ title: "Osano" --- -Add the following to your `mint.json` file to add the [Osano](https://www.osano.com/) cookie consent manager. +To integrate the [Osano](https://www.osano.com/) cookie consent manager, add this to your `mint.json`: @@ -20,7 +20,7 @@ Add the following to your `mint.json` file to add the [Osano](https://www.osano. -The `SOURCE` can be found as the `src` value in the code snippet generated by Osano. It always starts with `https://cmp.osano.com/`. +Get the `SOURCE` from Osano's generated code snippet - it's the `src` URL that starts with `https://cmp.osano.com/`. ```html Code snippet from Osano