Skip to content

Optimize content structure and formatting for LLM indexing #478

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

Optimize content structure and formatting for LLM indexing #478

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
161 changes: 70 additions & 91 deletions api-playground/openapi/setup.mdx
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -3,35 +3,47 @@ title: "OpenAPI Setup"
description: "Reference OpenAPI endpoints in your docs pages"
---

## Add an OpenAPI specification file
## Adding Your OpenAPI Spec

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+.
### Format Requirements
Make sure your OpenAPI document follows these requirements:
- Valid JSON or YAML format
- Follows OpenAPI specification 3.0+
- Contains complete endpoint and schema definitions

## Auto-populate API pages
### Validating Your Spec
Before proceeding, validate your OpenAPI spec using our CLI tool:

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.
```bash
mintlify openapi-check <openapiFilenameOrUrl>
```

## Auto-Generation Options

**Example with Anchors:**
You have two main options for automatically generating API documentation from your OpenAPI spec:

### Using Anchors
Add the OpenAPI spec to an anchor in your `mint.json` to generate pages under that section:

```json {5}
{
"anchors": [
{
"name": "API Reference",
"openapi": "/path/to/openapi.json",
"openapi": "/path/to/openapi.json", // Local path or URL
"url": "api-reference",
"icon": "square-terminal"
}
]
}
```

![](/images/anchors-autogeneration-anchors.png)
<Frame>
<img src="/images/anchors-autogeneration-anchors.png" alt="OpenAPI Anchor Generation Example" />
</Frame>

**Example with Tabs:**
### Using Tabs
Alternatively, add the spec to a tab to organize the generated pages under that tab:

```json {6}
{
Expand All @@ -45,108 +57,75 @@ 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.

* `description`: The `description` field from the OpenAPI operation, if present.
<Frame>
<img src="/images/autogeneration-with-tabs.png" alt="OpenAPI Tab Generation Example" />
</Frame>

* `version`: The `version` value from the anchor or tab, if present.
### Generated Page Metadata
Auto-generated pages will include the following metadata by default:

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.
- **Title**: Uses the OpenAPI operation's `summary` field, or generates one from the HTTP method and endpoint
- **Description**: Uses the OpenAPI operation's `description` field if present
- **Version**: Inherits the `version` from the parent anchor or tab if specified

## Create MDX files for API pages
## Custom MDX 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;
For more control over your API documentation, you can create individual MDX pages for each operation.

![](/images/elevenlabs-mdx-autogeneration-example.png)
### Why Create Custom Pages?
Custom MDX pages allow you to:
- Customize page metadata
- Add supplementary content and examples
- Control which operations to include
- Organize pages in a custom order

### 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.
### Using the Scraper
For large APIs, manually creating pages can be time-consuming. Use our scraper tool to automate this process:

```bash
# Basic usage
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.

```bash
# Specify output directory
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.
The scraper requires a valid OpenAPI document. Invalid specs will cause the generation to fail.
</Note>

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

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

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.
### Manual Page Creation
You can also create pages manually by referencing OpenAPI operations in your page metadata:

<CodeGroup>
```md Example
---
title: "Get users"
openapi: "/path/to/openapi-1.json GET /users"
---
```

```md Format
---
title: "title of the page"
openapi: openapi-file-path method path
---
```
</CodeGroup>
```md Single OpenAPI File
---
title: "Get Users"
openapi: "GET /users"
---
```

<br />
```md Multiple OpenAPI Files
---
title: "Get Users"
openapi: "/path/to/openapi-1.json GET /users"
---
```
</CodeGroup>

<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.
The method and path must exactly match your OpenAPI specification. Mismatches will result in empty pages.
</Note>

## Create MDX files for OpenAPI schemas
## Schema Documentation

Mintlify also allows you to create individual pages for any OpenAPI schema
defined in an OpenAPI document's `components.schemas` field:
### Creating Schema Pages
Generate standalone pages for your OpenAPI schemas defined in `components.schemas`:

<CodeGroup>
```md Example
---
openapi-schema: OrderItem
---
```

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

This automatically creates a page documenting the structure and properties of your schema.
104 changes: 67 additions & 37 deletions development.mdx
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -3,13 +3,17 @@ title: 'Local Development'
description: 'Preview changes locally to update your docs'
---

## Prerequisites

<Info>
Please make sure you have **Node.js version 19 or higher** installed before proceeding with the setup.
</Info>

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

</Info>
### Installing Mintlify CLI

**Step 1**: Install Mintlify:
You can install Mintlify globally on your system using your preferred package manager:

<CodeGroup>

Expand All @@ -27,13 +31,9 @@ description: 'Preview changes locally to update your docs'

</CodeGroup>

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

```bash
mintlify dev
```
### Alternative Installation

Alternatively, if you do not want to install Mintlify globally you can use a run script available:
If you prefer not to install Mintlify globally, you can use it directly through package manager execution commands:

<CodeGroup>
```bash npm
Expand All @@ -51,31 +51,47 @@ Alternatively, if you do not want to install Mintlify globally you can use a run
</CodeGroup>

<Warning>
Yarn's "dlx" run script requires yarn version >2. See [here](https://yarnpkg.com/cli/dlx) for more information.
If you're using Yarn's "dlx" command, note that it requires Yarn version >2. Learn more about dlx [here](https://yarnpkg.com/cli/dlx).
</Warning>

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

### Starting the Development Server

1. Navigate to your docs directory (where the `mint.json` file is located)
2. Run the following command:

```bash
mintlify dev
```

Your documentation preview will be available at `http://localhost:3000`.

### Custom Ports
### Port Configuration

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:
#### Default Port

By default, Mintlify runs on port 3000. You can customize this using the `--port` flag:

```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:
#### Port Conflicts

If your specified port is already in use, Mintlify will automatically try the next available port:

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

## Mintlify Versions
## Maintenance

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:
### Version Management

<CodeGroup>
The CLI version needs to match Mintlify's platform version. If you notice discrepancies between local and production previews, update your CLI:

<CodeGroup>
```bash npm
npm i -g mintlify@latest
```
Expand All @@ -87,45 +103,59 @@ Please note that each CLI release is associated with a specific version of Mintl
```bash pnpm
pnpm up --global mintlify
```

</CodeGroup>

## Validating Links
### Link Validation

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

```bash
mintlify broken-links
```

## Deployment
## Development Tools

### Code Editor Setup

If the deployment is successful, you should see the following:
For the best development experience, we recommend:

1. [MDX VSCode extension](https://marketplace.visualstudio.com/items?itemName=unifiedjs.vscode-mdx) for syntax highlighting
2. [Prettier](https://marketplace.visualstudio.com/items?itemName=esbenp.prettier-vscode) for code formatting

### Deployment Verification

After a successful deployment, you should see a confirmation screen:

<Frame>
<img
className="rounded-md"
src="https://mintlify.s3-us-west-1.amazonaws.com/mintlify/images/checks-passed.png"
alt="Deployment success screen showing all checks passed"
/>
</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

<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 title='Module Loading Error (Sharp)'>
If you encounter the error: "Could not load the sharp module using the darwin-arm64 runtime", follow these steps:

1. Remove existing Mintlify installation:
```bash
npm remove -g mintlify
```
2. Upgrade Node.js to v19 or higher
3. Reinstall Mintlify:
```bash
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="Unknown Errors">
For unexpected errors:

1. Navigate to your device's root directory
2. Delete the ~/.mintlify folder
3. Run `mintlify dev` again
</Accordion>
</AccordionGroup>
</AccordionGroup>
Loading
Loading