Skip to content

Simplify Documentation to Grade 10 Reading Level #445

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 Documentation to Grade 10 Reading Level #445

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
27 changes: 13 additions & 14 deletions advanced/rest-api/overview.mdx
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -4,29 +4,29 @@ 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
You can use our REST API to automatically start updates whenever you need them.
The main purpose is to let you control when updates happen. We're working on adding more
features to the API over time. Have suggestions? Share them with 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.
To use the API, you'll need an API key. You can create one through
[the dashboard](https://dashboard.mintlify.com/settings/integrations). This key works for your whole organization and can be used across all your deployments.

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

## 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 helps you add AI-powered chat to your documentation. This chat feature understands your docs and stays current with any changes you make.
When the AI responds, it includes references to show users exactly where the information came from.

## Getting Started

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

<Frame>
<img
Expand All @@ -36,10 +36,9 @@ 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.
There are two types of keys:
- The Discovery API token is public and can be used in your website's code
- The API key is private and should be kept secure on your server
</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).
Once you have your API key, you can see how to use it by checking out our [example code](https://github.com/mintlify/discovery-api-example). Want to see it in action? Visit [chat.mintlify.com](https://chat.mintlify.com) to try a live demo.
28 changes: 13 additions & 15 deletions advanced/subpath/cloudflare.mdx
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -5,20 +5,20 @@ 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.
To get started, go to `Workers & Pages > Create application > Create worker` in your Cloudflare dashboard. You'll see a screen where you can set up 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.
After creating your worker, follow these steps:
1. Click `Configure worker`
2. Go to `Settings > Triggers`
3. Click `Add Custom Domain`
4. Add your domain to the list
- We suggest adding two versions: one with `www.` and one without it

<Frame>
<img
Expand All @@ -27,21 +27,20 @@ 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.
Need help setting up your custom subdirectory? [Contact our support team](mailto:[email protected]) and we'll help you upgrade your hosting.

### Edit Worker Script

Click on `Edit Code` and add the following script into the worker's code.
Now you'll need to add some code to your worker. Click on `Edit Code` and copy the script below into the code editor.

<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.
Before using the code, you need to make two changes in `DOCS_URL`:
1. Replace `[SUBDOMAIN]` with your unique subdomain
2. Replace `CUSTOM_URL` with your website's base URL
</Tip>

```javascript
Expand Down Expand Up @@ -76,5 +75,4 @@ async function handleRequest(request) {
}
```

Click on `Deploy` and wait for the changes to propagate (it can take up to a few
hours).
Click `Deploy` to save your changes. Please note that it might take a few hours before all changes are fully active across the network.
36 changes: 18 additions & 18 deletions api-playground/openapi/advanced-features.mdx
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -1,25 +1,25 @@
---
title: "Advanced Features"
description: "Support for advanced OpenAPI features"
description: "Learn how to use powerful OpenAPI features"
---

OpenAPI 3 has some advanced features for describing complex APIs. Here's how you can use them with Mintlify.
OpenAPI 3 offers several advanced ways to describe complex APIs. Let's explore how to use these features with Mintlify.

## `oneOf`, `anyOf`, `allOf`

For complex datatypes, OpenAPI provides the `oneOf`, `anyOf`, and `allOf` keywords, allowing you to combine schemas in certain ways. You can read more about these keywords in the [Swagger documentation](https://swagger.io/docs/specification/data-models/oneof-anyof-allof-not/), but essentially:
OpenAPI provides three special keywords to help you work with complex data types: `oneOf`, `anyOf`, and `allOf`. These keywords let you combine different data structures. Here's what each one does:

- `oneOf` functions like an "exclusive-or" operator
- `anyOf` functions like an "or" operator
- `allOf` functions like an "and" operator
- `oneOf`: Means "pick exactly one option from the list"
- `anyOf`: Means "pick one or more options from the list"
- `allOf`: Means "include everything from all options"

<Warning>Mintlify treats the `oneOf` and `anyOf` keywords the same. We have found that, when people use `oneOf`, they often *mean* `anyOf` - and there is often no meaningful difference to the user.</Warning>
<Warning>In Mintlify, we handle `oneOf` and `anyOf` the same way. We've found that most developers use these terms interchangeably, and the difference rarely matters to users.</Warning>

<Info>Mintlify currently does not support the `not` keyword.</Info>
<Info>Note: Mintlify doesn't support the `not` keyword at this time.</Info>

### Combining schemas with `allOf`
### Using `allOf` to Combine Data Structures

Mintlify performs some preprocessing on your OpenAPI document to display these complex combinations in a readable way. For example, when you combine two object schemas with `allOf`, Mintlify combines the properties of both into a single object. This becomes especially useful when leveraging [OpenAPI's reusable `components`](https://swagger.io/docs/specification/components/).
Mintlify makes it easy to read combined data structures. For example, when you join two objects with `allOf`, we show all their properties together in one place. This is especially helpful when you're using [reusable components in OpenAPI](https://swagger.io/docs/specification/components/).

```yaml
org_with_users:
Expand Down Expand Up @@ -52,9 +52,9 @@ components:
</Expandable>
</ParamField>

### Providing options with `oneOf` and `anyOf`
### Offering Choices with `oneOf` and `anyOf`

When you use `oneOf` or `anyOf`, Mintlify displays the options in a tabbed container. To give your options helpful names, make sure to give each subschema a `title` field. For example, here's how you might display two different types of delivery addresses:
When you use `oneOf` or `anyOf`, Mintlify shows the options in tabs. To make these tabs easy to understand, give each option a clear title. Here's an example showing two different ways to write a delivery address:

```yaml
delivery_address:
Expand Down Expand Up @@ -94,21 +94,21 @@ delivery_address:

## `x-codeSamples`

If your users interact with your API using an SDK rather than directly through a network request, you can add code samples to your OpenAPI document, and Mintlify will display them in your OpenAPI pages. You can define your code samples using the `x-codeSamples` extension. This property can be added within any request method, and has the following schema:
If your users work with your API through an SDK instead of direct API calls, you can add example code to your documentation. Use the `x-codeSamples` feature to add these examples. You can add this to any API endpoint, and it needs:

<ParamField body="lang" type="string" required>
The language of the code sample.
The programming language used in the example
</ParamField>

<ParamField body="label" type="string">
The label for the sample. This is useful when providing multiple examples for a single endpoint.
A name for the example (helpful when you have multiple examples)
</ParamField>

<ParamField body="source" type="string" required>
The source code of the sample.
The actual code for the example
</ParamField>

Here's an example of some code samples for a plant tracking app, which has both a Bash CLI tool and a JavaScript SDK.
Here's an example from a plant tracking app that has both a command-line tool and a JavaScript SDK:

```yaml
paths:
Expand All @@ -134,4 +134,4 @@ paths:
source: |
const planter = require('planter');
planter.list({ potted: true });
```
```
88 changes: 37 additions & 51 deletions api-playground/openapi/setup.mdx
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -1,20 +1,21 @@
---
title: "OpenAPI Setup"
description: "Reference OpenAPI endpoints in your docs pages"
description: "Learn how to add API documentation to your pages"
---

## Add an OpenAPI specification file
## Add an OpenAPI 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+.
To document your API endpoints, you'll need a valid OpenAPI file in either JSON or YAML format. This file needs to follow the [OpenAPI 3.0+ specification](https://swagger.io/specification/).

## Auto-populate API pages
## Quick Setup: Auto-generate 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 easiest way to get started is to add an `openapi` field to your `mint.json` file. You can either:
- Point to an OpenAPI file in your docs folder
- Link to an OpenAPI file hosted online

**Example with Anchors:**
Mintlify will then create pages for each API endpoint automatically.

**Setting up with Anchors:**

```json {5}
{
Expand All @@ -31,7 +32,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:**
**Setting up with Tabs:**

```json {6}
{
Expand All @@ -47,66 +48,54 @@ The fastest way to get started with OpenAPI is to add an `openapi` field to a ta

![](/images/autogeneration-with-tabs.png)

<Tip>To validate your OpenAPI spec, you can use this command: <br/>`mintlify openapi-check <openapiFilenameOrUrl>`</Tip>


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.
<Tip>Check if your OpenAPI file is valid with this command: <br/>`mintlify openapi-check <yourFile>`</Tip>

* `description`: The `description` field from the OpenAPI operation, if present.
When you use this auto-generate option, your pages will have these default settings:
* The page title will use the OpenAPI operation's `summary` field, or create one from the endpoint details
* The description will come from the OpenAPI operation's `description` field
* The version will match what's in your anchor or tab settings

* `version`: The `version` value from the anchor or tab, if present.
Need more control? You can create custom pages for each API endpoint using MDX files.

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.
## Custom API Pages with MDX

## Create MDX files for API pages
Sometimes you might want to:
- Change how the page information appears
- Add extra content
- Skip certain API endpoints
- Change the order of 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).&#x20;
In these cases, you'll need to create MDX files for your API endpoints. Here's [an example from Elevenlabs](https://github.com/elevenlabs/elevenlabs-docs/blob/e5e267c97b8d1e4c21db1dcdb8b005eb1dfed7da/api-reference/speech-to-speech.mdx?plain=1#L2).

![](/images/elevenlabs-mdx-autogeneration-example.png)

### Autogenerate files
### Create MDX Files Automatically

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.
If you have many API endpoints, creating MDX files by hand can take a long time. Our Mintlify [scraper tool](https://www.npmjs.com/package/@mintlify/scraping) can create these files for you:

```bash
npx @mintlify/scraping@latest openapi-file <path-to-openapi-file>
```

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.
Want to save the files in a specific folder? Use the `-o` option:

```bash
npx @mintlify/scraping@latest openapi-file <path-to-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.

<Note>
If your OpenAPI document is invalid, the files will not autogenerate.
Your OpenAPI file must be valid for this to work.
</Note>

### Manually specify files
### Create MDX Files by Hand

You can always create an MDX page manually, and reference the OpenAPI operation in the page's metadata using the `openapi` field.
You can also create MDX pages manually. Just add an `openapi` field in the page's settings to link it to your API endpoint.

<Snippet file="api-playground/openapi.mdx" />

By using the OpenAPI reference, the name, description, parameters, responses,
and the API playground will be automatically generated from the OpenAPI document.
This will automatically add the endpoint's details and an interactive API playground to your page.

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.
If you have multiple OpenAPI files, include the file path to help Mintlify find the right one:

<CodeGroup>
```md Example
Expand All @@ -118,7 +107,7 @@ only one OpenAPI file - it will automatically detect your OpenAPI file.

```md Format
---
title: "title of the page"
title: "page title"
openapi: openapi-file-path method path
---
```
Expand All @@ -127,15 +116,12 @@ only one OpenAPI file - it will automatically detect your OpenAPI file.
<br />

<Note>
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.
Make sure the method and path match exactly what's in your OpenAPI file.
</Note>

## Create MDX files for OpenAPI schemas
## Pages for API Data Types

Mintlify also allows you to create individual pages for any OpenAPI schema
defined in an OpenAPI document's `components.schemas` field:
You can also create pages that explain the data types (schemas) defined in your OpenAPI file:

<CodeGroup>
```md Example
Expand All @@ -146,7 +132,7 @@ defined in an OpenAPI document's `components.schemas` field:

```md Format
---
openapi-schema: "schema-key"
openapi-schema: "schema-name"
---
```
</CodeGroup>
Loading
Loading