Skip to content

Fix Grammar and Spelling Across Documentation #477

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

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
53 changes: 26 additions & 27 deletions api-playground/troubleshooting.mdx
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -4,29 +4,29 @@ description: "Common issues with API References"
icon: "triangle-exclamation"
---

API pages are complicated. As a result, there are a lot of things that can go wrong.
Here's a list of common issues we've seen customers run into:
API pages can be complex, and several common issues may arise. Here's a list of problems we frequently see and how to resolve them:

<AccordionGroup>
<Accordion title="All of my OpenAPI pages are completely blank">
In this scenario, it's likely that either Mintlify cannot find your OpenAPI document,
When all OpenAPI pages are blank, this typically means either Mintlify cannot find your OpenAPI document,
or your OpenAPI document is invalid.

Running `mintlify dev` locally should reveal some of these issues.
Running `mintlify dev` locally will reveal most of these issues.

To verify your OpenAPI document will pass validation:
To verify your OpenAPI document's validity:

1. Visit [this validator](https://apitools.dev/swagger-parser/online/)
2. Switch to the "Validate text" tab
3. Paste in your OpenAPI document
4. Click "Validate it!"

If the text box that appears below has a green border, your document has passed validation.
This is the exact validation package Mintlify uses to validate OpenAPI documents, so if your document
passes validation here, there's a great chance the problem is elsewhere.
This is the same validation package Mintlify uses to validate OpenAPI documents, so if your document
passes validation here, the issue likely lies elsewhere.

Additionally, Mintlify does not support OpenAPI 2.0. If your document uses this version of the specification,
you could encounter this issue. You can convert your document at [editor.swagger.io](https://editor.swagger.io/) (under Edit > Convert to OpenAPI 3):
you will encounter this issue. You can convert your document at [editor.swagger.io](https://editor.swagger.io/)
by selecting Edit > Convert to OpenAPI 3:

<Frame>
<img src="/images/convert-oas-3.png" />
Expand All @@ -35,10 +35,10 @@ Here's a list of common issues we've seen customers run into:
</Accordion>

<Accordion title="One of my OpenAPI pages is completely blank">
This is usually caused by a misspelled `openapi` field in the page metadata. Make sure
the HTTP method and path match the HTTP method and path in the OpenAPI document exactly.
This issue usually stems from a mismatched `openapi` field in the page metadata. Ensure
the HTTP method and path exactly match those in your OpenAPI document.

Here's an example of how things might go wrong:
Here's an example of a common mismatch:

```md get-user.mdx
---
Expand All @@ -52,12 +52,12 @@ paths:
get: ...
```

Notice that the path in the `openapi` field has a trailing slash, whereas the path in the OpenAPI
Notice that the path in the `openapi` field has a trailing slash, while the path in the OpenAPI
document does not.

Another common issue is a misspelled filename. If you are specifying a particular OpenAPI document
in the `openapi` field, ensure the filename is correct. For example, if you have two OpenAPI
documents `openapi/v1.json` and `openapi/v2.json`, your metadata might look like this:
Another common issue is referencing the wrong OpenAPI file. When specifying a particular OpenAPI document
in the `openapi` field, verify the filename is correct. For example, if you have two OpenAPI
documents `openapi/v1.json` and `openapi/v2.json`, your metadata should look like this:

```md api-reference/v1/users/get-user.mdx
---
Expand All @@ -68,17 +68,16 @@ openapi: "v1 GET /users/{id}"
</Accordion>

<Accordion title="Requests from the API Playground don't work">
If you have a custom domain configured, this could be an issue with your reverse proxy. By
default, requests made via the API Playground start with a `POST` request to the
`/api/request` path on the docs site. If your reverse proxy is configured to only allow `GET`
requests, then all of these requests will fail. To fix this, configure your reverse proxy to
allow `POST` requests to the `/api/request` path.

Alternatively, if your reverse proxy prevents you from accepting `POST` requests, you can configure
Mintlify to send requests directly to your backend with the `api.playground.disableProxy`
setting in the `mint.json`, as described [here](/settings/global#api-configurations). This will
likely require you to configure CORS on your server, as these requests will now come directly
from your users' browsers.
For sites with a custom domain, this may be caused by your reverse proxy configuration. By
default, the API Playground makes `POST` requests to the `/api/request` path on your docs site.
If your reverse proxy only allows `GET` requests, these API Playground requests will fail.
To resolve this, configure your reverse proxy to allow `POST` requests to the `/api/request` path.

If you cannot configure your reverse proxy to accept `POST` requests, you can set Mintlify
to send requests directly to your backend using the `api.playground.disableProxy`
setting in your `mint.json`, as described in the [API Configurations documentation](/settings/global#api-configurations).
Note that this approach requires CORS configuration on your server since requests will come directly
from users' browsers.

</Accordion>
</AccordionGroup>
</AccordionGroup>
8 changes: 7 additions & 1 deletion mint.json
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -65,12 +65,14 @@
"icon": "pen-paintbrush",
"pages": [
"development",
"web-editor",
"web-editor"
]
},
"settings/global",
"settings/navigation",
"migration"
"migration",
"quickstart"
]
},
{
Expand Down Expand Up @@ -105,6 +107,7 @@
"api-playground/mdx/authentication"
]
},
"api-playground/troubleshooting",
"api-playground/troubleshooting"
]
},
Expand Down Expand Up @@ -164,9 +167,12 @@
"settings/authentication-personalization/personalization-setup/choosing-a-handshake",
"settings/authentication-personalization/personalization-setup/shared-session",
"settings/authentication-personalization/personalization-setup/jwt",
"settings/authentication-personalization/personalization-setup/oauth",
"settings/authentication-personalization/personalization-setup/oauth"
]
},
"settings/authentication-personalization/sending-data",
"settings/authentication-personalization/authentication",
"settings/authentication-personalization/sending-data"
]
},
Expand Down
39 changes: 19 additions & 20 deletions quickstart.mdx
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -17,20 +17,20 @@ icon: "rocket"

## Getting Started

Welcome! Follow the instructions below to learn how to deploy, update and
Welcome! Follow the instructions below to learn how to deploy, update, and
supercharge your documentation with Mintlify.

### Creating the 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. Onboard through the [dashboard](https://dashboard.mintlify.com) or clone our [starter kit](https://github.com/mintlify/starter) to get started.
your docs with your code and make source control effortless. Onboard through the [dashboard](https://dashboard.mintlify.com) or clone our [starter kit](https://github.com/mintlify/starter) to get started.

<AccordionGroup>

<Accordion icon="message-bot" title="Install the GitHub app">
<Accordion icon="message-bot" title="Install the GitHub App">

Install our GitHub app to ensure 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.
Install our GitHub App to ensure 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.

<Frame>
![GitHub Bot Verification](https://mintlify.s3-us-west-1.amazonaws.com/mintlify/images/github-bot-verification.png)
Expand All @@ -40,9 +40,9 @@ your docs with your code, and make source control effortless. Onboard through th

<Accordion icon="code-branch" title="Monorepo Setup">
If you want your docs to live alongside your code as a monorepo setup, you
can: 1. Move your docs content to your monorepo. 2. Specify the path to your
`mint.json` in the
[dashboard](https://dashboard.mintlify.com/settings/deployment/git-settings)
can:
1. Move your docs content to your monorepo
2. Specify the path to your `mint.json` in the [dashboard](https://dashboard.mintlify.com/settings/deployment/git-settings)
<Frame>
<img
alt="Monorepo setup"
Expand All @@ -67,24 +67,24 @@ your docs.
<AccordionGroup>
<Accordion icon="rectangle-terminal" title="Editing locally (recommended for developers)">

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 <your-repo>`. 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).
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 <your-repo>`. 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).

</Accordion>

<Accordion icon="pen-to-square" title="Editing with the web editor">
<Accordion icon="pen-to-square" title="Editing with the Web Editor">

Learn more about how to use the web editor on our [guide](/web-editor).
Learn more about how to use the Web Editor on our [guide](/web-editor).

</Accordion>

<Accordion icon="palette" title="Customizing to your brand">

Easily customize colors, logos and buttons among other configurations in our `mint.json` file. Start with these basic configurations:
Easily customize colors, logos, and buttons among other configurations in our `mint.json` file. Start with these basic configurations:

```json
"name": "Your Company"
Expand Down Expand Up @@ -123,11 +123,10 @@ your docs.

<Accordion icon="rocket" title="Pushing changes">

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

<Frame>
![Manual
Update](https://mintlify.s3-us-west-1.amazonaws.com/mintlify/images/manual-update.png)
![Manual Update](https://mintlify.s3-us-west-1.amazonaws.com/mintlify/images/manual-update.png)
</Frame>

</Accordion>
Expand All @@ -142,21 +141,21 @@ your docs.
"openapi": "link-to-your-openapi-file"
```

2. Use our [scraper](/api-playground/openapi/setup#autogenerate-files-recommended) to autogenerate your OpenAPI endpoints files as:
2. Use our [scraper](/api-playground/openapi/setup#autogenerate-files-recommended) to autogenerate your OpenAPI endpoints files:

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

3. Finally, include the generated endpoint MDX files to your `mint.json` under `navigation`.
3. Finally, include the generated endpoint MDX files in 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).

</Accordion>

<Accordion icon="chart-simple" title="Adding analytics">

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

Expand All @@ -180,7 +179,7 @@ Navigate to your [dashboard settings](https://www.dashboard.mintlify.com/setting

</Accordion>

Congrats! You've set up your Mintlify Docs and it's looking amazing! Need
Congrats! You've set up your Mintlify Docs and they're 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
[[email protected]](mailto:[email protected]).
[[email protected]](mailto:[email protected]).
19 changes: 8 additions & 11 deletions settings/authentication-personalization/authentication.mdx
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -3,23 +3,20 @@ title: "Authentication"
description: "Guarantee privacy of your docs by authenticating users"
---

Authentication offers full privacy for all of your
documentation content by requiring users to authenticate before viewing any content, such as:
Authentication offers full privacy for all of your documentation content by requiring users to authenticate before viewing any content, including:

- Documentation page content
- Images used in documentation pages
- Images used in documentation pages
- Search results
- AI chat interactions

You can authenticate users through handshake methods such as:
You can authenticate users through the following handshake methods:

- [Password](./authentication-setup/password)
- [JWT](./authentication-setup/jwt)
- [OAuth](./authentication-setup/oauth)
- [Mintlify dashboard](./authentication-setup/mintlify)
- [JWT](./authentication-setup/jwt)
- [OAuth 2.0](./authentication-setup/oauth)
- [Mintlify Dashboard](./authentication-setup/mintlify)

Authentication is similar to our [Personalization](./personalization) offering, but with guaranteed privacy. In addition
to securing your documentation content, all features that are available via
Personalization are also available via Authentication.
Authentication is similar to our [Personalization](./personalization) offering but with guaranteed privacy. In addition to securing your documentation content, all features available via Personalization are also available via Authentication.

Check out our docs for more info on [choosing Authentication vs Personalization](./authentication-vs-personalization).
To learn more about choosing between Authentication and Personalization, read our guide on [Authentication vs. Personalization](./authentication-vs-personalization).
Loading
Loading