diff --git a/api-playground/troubleshooting.mdx b/api-playground/troubleshooting.mdx index fbd97ff58..6340a04bb 100644 --- a/api-playground/troubleshooting.mdx +++ b/api-playground/troubleshooting.mdx @@ -4,8 +4,7 @@ description: "Common issues with API References" icon: "message-square-warning" --- -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: +If your API pages aren't displaying correctly, check these common configuration issues: diff --git a/components/cards.mdx b/components/cards.mdx index 03d8cf92d..8b25fc39f 100644 --- a/components/cards.mdx +++ b/components/cards.mdx @@ -92,7 +92,14 @@ You can group cards in [columns](/components/columns). A [Font Awesome icon](https://fontawesome.com/icons), [Lucide - icon](https://lucide.dev/icons), or SVG code in `icon={}` + icon](https://lucide.dev/icons), or JSX compatible SVG code in `icon={}`. + + To generate JSX compatible SVG code: + + 1. Use the [SVGR converter](https://react-svgr.com/playground/). + 2. Copy the code inside the `` tag. + 3. Paste the code into your card. Make sure to only copy and paste the code inside the `` tag. + 4. You may need to decrease the height and width to make the image fit. diff --git a/contact-support.mdx b/contact-support.mdx new file mode 100644 index 000000000..748aae165 --- /dev/null +++ b/contact-support.mdx @@ -0,0 +1,25 @@ +--- +title: "Contact Support" +icon: "circle-help" +description: "We're here to help you get the most out of Mintlify" +--- + +## Ask our docs + +Select Command + I to start a chat with our AI assistant trained on our documentation. + +## Watch video tutorials + +Visit our [YouTube](https://www.youtube.com/@GetMintlify/videos) channel for tutorials and guides on using Mintlify. + +## Message support + +Send us a message from your [dashboard](https://dashboard.mintlify.com/) by selecting **Support** in the sidebar. + + +We aim to respond to all requests within 24 hours, but delays may occur during busy times. + + +## Email support + +If you can't access your dashboard, please email us at support@mintlify.com. diff --git a/docs.json b/docs.json index f20329ea9..7c1fc1056 100644 --- a/docs.json +++ b/docs.json @@ -24,8 +24,7 @@ "index", "quickstart", "installation", - "editor", - "support" + "editor" ] }, { @@ -160,7 +159,8 @@ "advanced/dashboard/roles" ] - } + }, + "contact-support" ] }, { diff --git a/navigation.mdx b/navigation.mdx index 945c02c77..f6e96842b 100644 --- a/navigation.mdx +++ b/navigation.mdx @@ -8,6 +8,10 @@ The [navigation](settings#param-navigation) property in [docs.json](settings) de With proper navigation configuration, you can organize your content into a logical hierarchy that makes it easy for users to find exactly what they're looking for. + +Do not use `api` as a title for any navigation element. The `/api` path is reserved in production and will cause pages to return 404 errors if their URLs contain `/api`. + + ## Pages Pages are the most fundamental navigation component. diff --git a/settings/github.mdx b/settings/github.mdx index e42cac7a5..bc2016cc2 100644 --- a/settings/github.mdx +++ b/settings/github.mdx @@ -1,26 +1,19 @@ --- -title: GitHub +title: "GitHub" description: "Sync your docs with a GitHub repo" -icon: 'github' +icon: "github" --- -Mintlify integrates with the GitHub API, enabling synchronization between your -docs and your GitHub repository. This integration is made possible through the -utilization of -[GitHub Apps](https://docs.github.com/en/developers/apps/getting-started-with-apps/about-apps#about-github-apps). +Mintlify uses a GitHub App to automatically sync your documentation with your GitHub repository. ## Installation -To begin, you need to install the Mintlify GitHub App into the GitHub account -where your docs repo resides. Installing a GitHub App requires either -organization ownership or admin permissions in a repository. If you lack the -necessary permissions, the repository owner will need to approve the request. -You can access the installation page by logging into the -[Mintlify dashboard](https://dashboard.mintlify.com). +Install the Mintlify GitHub App on the GitHub account or organization that owns your docs repository. Installing a GitHub App requires either +organization ownership or admin permissions in a repository. If you lack the necessary permissions, the repository owner will need to approve the request. -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 -your docs are hosted. +You can install the Mintlify GitHub App through your [dashboard](https://dashboard.mintlify.com/settings/organization/github-app). + +We recommend granting access only to the repository where your docs are hosted. @@ -60,3 +53,18 @@ and pull requests which is why we need write access to `pull requests` and When installing our GitHub app, you will be prompted to select all repositories or a subset of them. This selection can be changed at any time by going to the [GitHub app settings](https://github.com/apps/mintlify/installations/new). + +## Troubleshooting + +If you encounter problems with the GitHub app, resetting the connection can solve most problems. + + + + 1. In GitHub, go to [installations](https://github.com/settings/installations) and select **Configure** next to the Mintlify app. Scroll down and select **Uninstall**. + 2. Go to [Authorized GitHub Apps](https://github.com/settings/apps/authorizations) and select **Revoke** next to the Mintlify app. + + + 1. In your Mintlify dashboard, go to [Git Settings](https://dashboard.mintlify.com/settings/deployment/git-settings) and install the GitHub app. + 2. Authorize your account in the [My Profile](https://dashboard.mintlify.com/settings/account) section of your dashboard. + + diff --git a/support.mdx b/support.mdx deleted file mode 100644 index 2bc6e01ca..000000000 --- a/support.mdx +++ /dev/null @@ -1,135 +0,0 @@ ---- -title: "Support" -icon: "circle-help" -description: "We're here to help you get the most out of Mintlify" ---- - -export function openSearch(e) { - e.preventDefault(); - document.getElementById('search-bar-entry').click(); -} - -
- - Ask our AI assistant that's been trained on our documentation. - -
- - - - Send us a message from your dashboard. Select **Support** in your dashboard's sidebar. - - - If you can't access your dashboard, email us at support@mintlify.com. - - - Join our community and ask our AI assistant that's been trained on our documentation. - - - Watch tutorials and guides on our YouTube channel. - - - -## Frequently Asked Questions - - - - The GitHub app can be temperamental and resetting the connection is a great way to solve issues. - - - - 1. In GitHub, go to [installations](https://github.com/settings/installations) and select **Configure** next to the Mintlify app. Scroll down and select **Uninstall**. - 2. Go to [Authorized GitHub Apps](https://github.com/settings/apps/authorizations) and select **Revoke** next to the Mintlify app. - - - 1. In your Mintlify dashboard, go to [Git Settings](https://dashboard.mintlify.com/settings/deployment/git-settings) and install the GitHub app. - 2. Authorize your account in the [My Profile](https://dashboard.mintlify.com/settings/account) section of your dashboard. - - - - - - 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: - - - - In this scenario, it's likely that either Mintlify cannot find your OpenAPI document or your OpenAPI document is invalid. - - Running `mint dev` locally should reveal some of these issues. - - To verify your OpenAPI document will pass validation: - - 1. Run `mint openapi-check ` in your CLI. - 2. Validate your OpenAPI spec with [Swagger Editor](https://editor.swagger.io/). - - Additionally, Mintlify does not support OpenAPI 2.0. If your document uses OpenAPI 2.0, you may encounter this issue. You can convert your document with [Swagger Editor](https://editor.swagger.io/). - - - !["Convert to OpenAPI 3" menu item highlighted in the Swagger Editor](/images/convert-oas-3.png) - - - - This is usually caused by a misspelled `openapi` field in the page metadata. Make sure that the HTTP method and path match the HTTP method and path in the OpenAPI document exactly. - - Here's an example of how things might go wrong: - - ```md get-user.mdx - --- - openapi: "GET /users/{id}/" - --- - ``` - - ```yaml openapi.yaml - paths: - "/users/{id}": - get: ... - ``` - Notice that the path in the `openapi` field has a trailing slash, whereas 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: - - ```md api-reference/v1/users/get-user.mdx - --- - openapi: "v1 GET /users/{id}" - --- - ``` - - - 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.proxy` setting in the `docs.json`. See the [configurations for the API playground](/settings#param-proxy) for more information. This will - likely require you to configure CORS on your server, as these requests will now come directly - from your users' browsers. - - - - - - Check to see if you have `/api` in the URL. This is a reserved folder in production environments, which produces a 404 error. - - - - - We support a specific type of SVG, called JSX, and as such the image will need to be converted. - - 1. Use the [SVGR converter](https://react-svgr.com/playground/) to generate JSX compatible SVG code. - 2. Copy the code inside the `` tag. - - ![Output from the SVGR converter with the code inside and tags highlighted.](/images/svg-jsx.png) - - 3. Paste the code into your card. Make sure you only copy and paste the code inside the `` tag. - 4. You may need to decrease the height and width to make the image fit. - - - - -We do our best to respond to all requests within 24 hours but delays may occur during busy times. - -