Skip to content

Fix Grammar and Spelling Across Documentation #531

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

Fix Grammar and Spelling Across Documentation #531

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
8 changes: 5 additions & 3 deletions advanced/dashboard/permissions.mdx
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -3,14 +3,16 @@ title: 'Editor Permissions'
description: 'Allow more members of your team to update your docs'
---

The team member who created your initial docs will have update access to your docs, as long as they push to your documentation repo with the same GitHub account that was used while signing up for Mintlify.
The team member who created your initial docs will have update access to your documentation, as long as they push to your documentation repo with the same GitHub account that was used during signup for Mintlify.

If another editor attempts to update the docs while on the free plan, you will see a warning in your git commit check.

<Frame>
<img className="rounded-md" src="/images/editor-gate.png" />
</Frame>

In the details of the git check warning, you'll find the link to upgrade your plan. You can also upgrade your plan on the [dashboard](https://dashboard.mintlify.com) to enable unlimited editors to update your docs. Once you upgrade your plan, trigger a manual update or push another change to deploy your updates.
In the details of the git check warning, you'll find a link to upgrade your plan. You can also upgrade your plan on the [dashboard](https://dashboard.mintlify.com) to enable unlimited editors to update your docs.

Learn more about our pricing [here](https://mintlify.com/pricing).
Once you upgrade your plan, trigger a manual update or push another change to deploy your updates.

Learn more about our pricing [here](https://mintlify.com/pricing).
16 changes: 8 additions & 8 deletions advanced/rest-api/overview.mdx
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -7,36 +7,36 @@ title: Overview
You can leverage the REST API to programmatically trigger an update when desired.

<Info>
While 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
While the primary use case will be to trigger updates, we will be adding more functionality
to the API over time. Let us know what else you want to see in
[our community](https://mintlify.com/community)!
</Info>

## Authentication

You can generate an API key through
[the dashboard](https://dashboard.mintlify.com/settings/organization/api-keys). The API key is
associated with the entire org and can be used across multiple deployments.
associated with the entire organization and can be used across multiple deployments.

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

## Admin API key
## Admin API Key

The Admin API key is used for the majority of the API. It is used to trigger updates via the [Update endpoint](/advanced/rest-api/update/trigger).

## Chat API key
## Chat API Key

The Chat API allows you to embed the AI chat experience grounded in your docs and continually kept up to date into any application of your choosing.
The Chat API allows you to embed the 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.

<Note>
The Chat 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
frontend code, whereas the API key is a server-side token that should be kept
secret.
</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).
the API for AI chat. You can also see a deployed version of this example at [chat.mintlify.com](https://chat.mintlify.com).
17 changes: 7 additions & 10 deletions api-playground/mdx/configuration.mdx
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -7,21 +7,21 @@ Mintlify allows you to define your API endpoints using a combination of `docs.js

<Steps>
<Step title="Configure your API">
In your `docs.json` file, define your base URL and auth method:
In your `docs.json` file, define your base URL and authentication method:

```json
"api": {
"mdx": {
"server": "https://mintlify.com/api", // string array for multiple base URLs
"auth": {
"method": "key",
"name": "x-api-key" // options: bearer, basic, key.
"name": "x-api-key" // options: bearer, basic, key
}
}
}
```

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:
If you do not want to show an API playground, you don't need to include authentication types. You can hide the playground with the following field:

```json
"api": {
Expand All @@ -35,7 +35,6 @@ Mintlify allows you to define your API endpoints using a combination of `docs.js
</Step>

<Step title="Create your endpoint pages">

Each API endpoint page should have a corresponding MDX file. At the top of each file, define:

```md
Expand All @@ -45,30 +44,28 @@ Mintlify allows you to define your API endpoints using a combination of `docs.js
---
```

You can specify path parameters by adding the parameter name to the path, wrapped with `{}`:
You can specify path parameters by adding the parameter name to the path, wrapped with curly braces `{}`:

```bash
https://api.example.com/v1/endpoint/{userId}
```

<Note>

If you have `server` configured in [docs.json](/settings/global), you can use relative paths like `/v1/endpoint`.

</Note>

You can also override the globally-defined display mode for the API playground per page by adding `playground` at the top of the MDX file:
You can also override the globally-defined display mode for the API playground per page by adding the `playground` field at the top of the MDX file:

```md
---
title: 'Create new user'
api: 'POST https://api.mintlify.com/user'
playground: 'none'
---
```

</Step>

<Step title="Add your endpoints to your docs">
Add your endpoint pages to the sidebar by adding the paths to the `navigation` field in your `docs.json`. Learn more about structuring your docs [here](/settings/navigation).
</Step>
</Steps>
</Steps>
31 changes: 22 additions & 9 deletions docs.json
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -22,7 +22,10 @@
{
"group": "Editing",
"icon": "pen-paintbrush",
"pages": ["development", "web-editor"]
"pages": [
"development",
"web-editor"
]
},
"settings/global",
{
Expand All @@ -37,7 +40,8 @@
]
},
"themes",
"migration"
"migration",
"settings/github"
]
},
{
Expand Down Expand Up @@ -69,7 +73,8 @@
"icon": "markdown",
"pages": [
"api-playground/mdx/configuration",
"api-playground/mdx/authentication"
"api-playground/mdx/authentication",
"api-playground/mdx/configuration"
]
},
"api-playground/troubleshooting"
Expand All @@ -85,7 +90,8 @@
"settings/github",
"settings/gitlab",
"settings/ci",
"settings/preview-deployments"
"settings/preview-deployments",
"settings/ci"
]
},
{
Expand Down Expand Up @@ -133,7 +139,11 @@
{
"group": "Dashboard Access",
"icon": "house-lock",
"pages": ["advanced/dashboard/sso", "advanced/dashboard/permissions"]
"pages": [
"advanced/dashboard/sso",
"advanced/dashboard/permissions",
"advanced/dashboard/permissions"
]
},
{
"group": "REST API",
Expand All @@ -153,7 +163,8 @@
"advanced/rest-api/chat/create-topic",
"advanced/rest-api/chat/generate-message"
]
}
},
"advanced/rest-api/overview"
]
}
]
Expand Down Expand Up @@ -205,7 +216,7 @@
"pages": [
"integrations/analytics/overview",
"integrations/analytics/amplitude",
"integrations/analytics/clearbit",
"integrations/analytics/clearbit",
"integrations/analytics/fathom",
"integrations/analytics/google-analytics",
"integrations/analytics/google-tag-manager",
Expand Down Expand Up @@ -251,7 +262,9 @@
"groups": [
{
"group": "Changelog",
"pages": ["changelog/overview"]
"pages": [
"changelog/overview"
]
}
]
}
Expand Down Expand Up @@ -363,4 +376,4 @@
"publicApiKey": "pk_76a6caa274e800f3ceff0b2bc6b9b9d82ab8"
}
}
}
}
33 changes: 15 additions & 18 deletions settings/ci.mdx
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -8,34 +8,31 @@ icon: 'circle-check'
This feature is only available for customers on paid plans and for GitHub. Support for other platforms is coming soon.
</Warning>

Use CI checks to lint your docs for errors, and give you warnings before you deploy.
Use CI checks to lint your docs for errors and get warnings before you deploy.

## Installation

To begin, you will need to have followed the steps on the [GitHub](/settings/github) page.

For GitHub Apps, you can choose to only give permissions to a single repository.
We highly recommend you do so as we only need access to the repository where
For GitHub Apps, you can choose to give permissions to a single repository.
We highly recommend this approach, as we only need access to the repository where
your docs are hosted.

## Configuration

You can configure the CI checks enabled for a deployment on the Mintlify dashboard by navigating to the 'Add-Ons' tab. There you can enable or disable the checks you'd like to run.
You can configure the CI checks enabled for a deployment on the Mintlify dashboard by navigating to the 'Add-Ons' tab. There, you can enable or disable the checks you'd like to run.

When enabling checks, you can choose to run them at a `Warning` or `Blocking` level.

<Note>
A `Blocking` level check will provide a failure status if not passed, or if changes are suggested.


A `Blocking` level check will provide a failure status if not passed, or changes are suggested.<br/>

A `Warning` level check will never provide a failure status, even if there is an error or suggestions.

A `Warning` level check will never provide a failure status, even if there are errors or suggestions.
</Note>

## When Do They Run?

CI checks are configured to run on commits to your configured deployment branch, or on pull requests against that branch.
CI checks are configured to run on commits to your configured deployment branch or on pull requests against that branch.

## Available CI Checks

Expand All @@ -46,18 +43,18 @@ To see the results of this check, you can visit GitHub's check results page for

### Vale

[Vale](https://vale.sh/) is an open-source rule-based prose linter which supports a range of document types, including Markdown and MDX.
[Vale](https://vale.sh/) is an open-source, rule-based prose linter which supports a range of document types, including Markdown and MDX.

Mintlify supports automatically running Vale in a CI check, and displaying the results as a check status.
Mintlify supports automatically running Vale in a CI check and displaying the results as a check status.

#### Configuration
If you have a `.vale.ini` file in the root the content directory for your deployment, we will automatically use that configuration file.
If you have a `.vale.ini` file in the root of the content directory for your deployment, we will automatically use that configuration file.
We will also automatically use any configuration files in your specified `stylesPath`.

<Tip>Don't have a Vale config or not sure where to get started? Don't worry, Mintlify has a default configuration that will automatically be used if one is not provided.</Tip>

<Warning>
Please note that for security reasons, we are unable to support any absolute `stylesPath`, or `stylesPath` which include `..` values. Please use relative paths and include the `stylesPath` in your repository.
Please note that for security reasons, we are unable to support any absolute `stylesPath` or `stylesPath` which include `..` values. Please use relative paths and include the `stylesPath` in your repository.
</Warning>

#### Packages
Expand Down Expand Up @@ -91,7 +88,7 @@ BlockIgnores = (?sm)^(<\w+\n .*\s\/>)$, \

To use Vale's in-document comments, use MDX-style comments `{/* ... */}`.
If you use the `CommentDelimiters = {/*, */}` [setting](https://vale.sh/docs/keys/commentdelimiters) in your configuration, Vale will automatically interpret these comments while linting.
This means you can easily use Vale's in-built features, like skipping lines or sections.
This means you can easily use Vale's built-in features, like skipping lines or sections.

```mdx
{/* vale off */}
Expand All @@ -101,8 +98,7 @@ This text will be ignored by Vale
{/* vale on */}
```


If you choose not to use `CommentDelimiters`, but still choose to use Vale's comments, you must wrap any Vale comments in MDX comments `{/* ... */}`. For example:
If you choose not to use `CommentDelimiters` but still want to use Vale's comments, you must wrap any Vale comments in MDX comments `{/* ... */}`. For example:

```mdx
{/* <!-- vale off --> */}
Expand All @@ -111,4 +107,5 @@ This text will be ignored by Vale

{/* <!-- vale on --> */}
```
Please note that these commment tags are not supported within Mintlify components, but can be used anywhere at the base level of a document.

Please note that these comment tags are not supported within Mintlify components but can be used anywhere at the base level of a document.
Loading