From 6e087ef1d1787b9d11ea005860751cd5fc799df9 Mon Sep 17 00:00:00 2001 From: Ethan Palm <56270045+ethanpalm@users.noreply.github.com> Date: Fri, 30 May 2025 10:53:13 -0700 Subject: [PATCH 1/9] move github troubleshooting info --- settings/github.mdx | 38 +++++++++++++++++++++++--------------- support.mdx | 14 -------------- 2 files changed, 23 insertions(+), 29 deletions(-) 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 index 2bc6e01ca..d178c42a0 100644 --- a/support.mdx +++ b/support.mdx @@ -33,20 +33,6 @@ export function openSearch(e) { ## 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: From a90a800522e41fa10a688279b62295f6f2a3ea09 Mon Sep 17 00:00:00 2001 From: Ethan Palm <56270045+ethanpalm@users.noreply.github.com> Date: Fri, 30 May 2025 10:56:41 -0700 Subject: [PATCH 2/9] remove duplicate API troubleshooting info --- api-playground/troubleshooting.mdx | 3 +- support.mdx | 63 ------------------------------ 2 files changed, 1 insertion(+), 65 deletions(-) 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/support.mdx b/support.mdx index d178c42a0..b456f0fb2 100644 --- a/support.mdx +++ b/support.mdx @@ -34,69 +34,6 @@ export function openSearch(e) { - - 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. From 5d48bead3657173cc6fe766cbe34d3b79a04bfb0 Mon Sep 17 00:00:00 2001 From: Ethan Palm <56270045+ethanpalm@users.noreply.github.com> Date: Fri, 30 May 2025 11:07:21 -0700 Subject: [PATCH 3/9] move SVG info to cards page --- components/cards.mdx | 9 ++++++++- support.mdx | 11 ----------- 2 files changed, 8 insertions(+), 12 deletions(-) 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/support.mdx b/support.mdx index b456f0fb2..ecb37c660 100644 --- a/support.mdx +++ b/support.mdx @@ -39,17 +39,6 @@ export function openSearch(e) { - - 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. - From 0553699d48c3135e776f655f4049c5b5b60c945c Mon Sep 17 00:00:00 2001 From: Ethan Palm <56270045+ethanpalm@users.noreply.github.com> Date: Fri, 30 May 2025 11:14:26 -0700 Subject: [PATCH 4/9] move `/api` 404 info to navigation --- navigation.mdx | 4 ++++ support.mdx | 9 --------- 2 files changed, 4 insertions(+), 9 deletions(-) diff --git a/navigation.mdx b/navigation.mdx index 945c02c77..d98dc62a9 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. + +No navigation elements can be titled `api`. The `/api` path is a reserved folder in production environments. If a page URL has `/api`, it will return a 404 error. + + ## Pages Pages are the most fundamental navigation component. diff --git a/support.mdx b/support.mdx index ecb37c660..e148a4297 100644 --- a/support.mdx +++ b/support.mdx @@ -32,15 +32,6 @@ export function openSearch(e) { ## Frequently Asked Questions - - - - Check to see if you have `/api` in the URL. This is a reserved folder in production environments, which produces a 404 error. - - - - - We do our best to respond to all requests within 24 hours but delays may occur during busy times. From a01872eb1f0a794e82c25ee9b5ecd778ed54e815 Mon Sep 17 00:00:00 2001 From: Ethan Palm <56270045+ethanpalm@users.noreply.github.com> Date: Fri, 30 May 2025 11:19:05 -0700 Subject: [PATCH 5/9] move and rename support --- support.mdx => contact-support.mdx | 3 +-- docs.json | 6 +++--- 2 files changed, 4 insertions(+), 5 deletions(-) rename support.mdx => contact-support.mdx (98%) diff --git a/support.mdx b/contact-support.mdx similarity index 98% rename from support.mdx rename to contact-support.mdx index e148a4297..ffd833012 100644 --- a/support.mdx +++ b/contact-support.mdx @@ -1,5 +1,5 @@ --- -title: "Support" +title: "Contact Support" icon: "circle-help" description: "We're here to help you get the most out of Mintlify" --- @@ -35,4 +35,3 @@ export function openSearch(e) { We do our best to respond to all requests within 24 hours but delays may occur during busy times. - 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" ] }, { From cd29923c7dcfbd5320711d16e32a7eb58c95c793 Mon Sep 17 00:00:00 2001 From: Ethan Palm <56270045+ethanpalm@users.noreply.github.com> Date: Fri, 30 May 2025 11:36:03 -0700 Subject: [PATCH 6/9] update support info --- contact-support.mdx | 46 +++++++++++++++++---------------------------- 1 file changed, 17 insertions(+), 29 deletions(-) diff --git a/contact-support.mdx b/contact-support.mdx index ffd833012..798a4564b 100644 --- a/contact-support.mdx +++ b/contact-support.mdx @@ -1,37 +1,25 @@ --- title: "Contact Support" icon: "circle-help" -description: "We're here to help you get the most out of Mintlify" +description: "We are 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 +## 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/). Select **Support** in your dashboard's sidebar. -We do our best to respond to all requests within 24 hours but delays may occur during busy times. +We do our best to respond to all requests within 24 hours, but delays may occur during busy times. + +## Email support + +If you cannot access your dashboard, please email us at support@mintlify.com. From 7940fb52e3fa8626a796c47569cec10a568a64d5 Mon Sep 17 00:00:00 2001 From: Ethan Palm <56270045+ethanpalm@users.noreply.github.com> Date: Fri, 30 May 2025 11:41:51 -0700 Subject: [PATCH 7/9] copyedits --- contact-support.mdx | 8 ++++---- 1 file changed, 4 insertions(+), 4 deletions(-) diff --git a/contact-support.mdx b/contact-support.mdx index 798a4564b..748aae165 100644 --- a/contact-support.mdx +++ b/contact-support.mdx @@ -1,7 +1,7 @@ --- title: "Contact Support" icon: "circle-help" -description: "We are here to help you get the most out of Mintlify" +description: "We're here to help you get the most out of Mintlify" --- ## Ask our docs @@ -14,12 +14,12 @@ Visit our [YouTube](https://www.youtube.com/@GetMintlify/videos) channel for tut ## Message support -Send us a message from your [dashboard](https://dashboard.mintlify.com/). Select **Support** in your dashboard's sidebar. +Send us a message from your [dashboard](https://dashboard.mintlify.com/) by selecting **Support** in the sidebar. -We do our best to respond to all requests within 24 hours, but delays may occur during busy times. +We aim to respond to all requests within 24 hours, but delays may occur during busy times. ## Email support -If you cannot access your dashboard, please email us at support@mintlify.com. +If you can't access your dashboard, please email us at support@mintlify.com. From 9fad4fff0f9d86b1e5487d882cbcb81f01fd5e6a Mon Sep 17 00:00:00 2001 From: Ethan Palm <56270045+ethanpalm@users.noreply.github.com> Date: Fri, 30 May 2025 11:47:10 -0700 Subject: [PATCH 8/9] fix wording --- navigation.mdx | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/navigation.mdx b/navigation.mdx index d98dc62a9..3d8ae045b 100644 --- a/navigation.mdx +++ b/navigation.mdx @@ -9,7 +9,7 @@ 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. -No navigation elements can be titled `api`. The `/api` path is a reserved folder in production environments. If a page URL has `/api`, it will return a 404 error. +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 if their URLs contain `/api`. ## Pages From 8075d4273b5e21a0b55ca6e114d9852ef4203dc1 Mon Sep 17 00:00:00 2001 From: Ethan Palm <56270045+ethanpalm@users.noreply.github.com> Date: Fri, 30 May 2025 11:51:09 -0700 Subject: [PATCH 9/9] typo fix --- navigation.mdx | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/navigation.mdx b/navigation.mdx index 3d8ae045b..f6e96842b 100644 --- a/navigation.mdx +++ b/navigation.mdx @@ -9,7 +9,7 @@ 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 if their URLs contain `/api`. +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