diff --git a/advanced/dashboard/permissions.mdx b/advanced/dashboard/permissions.mdx index d39d099a4..1757af375 100644 --- a/advanced/dashboard/permissions.mdx +++ b/advanced/dashboard/permissions.mdx @@ -3,7 +3,7 @@ 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. @@ -11,6 +11,8 @@ If another editor attempts to update the docs while on the free plan, you will s -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). \ No newline at end of file diff --git a/advanced/rest-api/overview.mdx b/advanced/rest-api/overview.mdx index c1f399434..235364f43 100644 --- a/advanced/rest-api/overview.mdx +++ b/advanced/rest-api/overview.mdx @@ -7,8 +7,8 @@ title: Overview You can leverage the REST API to programmatically trigger an update when desired. - 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)! @@ -16,27 +16,27 @@ You can leverage the REST API to programmatically trigger an update when desired 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. -## 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. 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. 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). \ No newline at end of file diff --git a/api-playground/mdx/configuration.mdx b/api-playground/mdx/configuration.mdx index 9ef4eb106..0052ef467 100644 --- a/api-playground/mdx/configuration.mdx +++ b/api-playground/mdx/configuration.mdx @@ -7,7 +7,7 @@ Mintlify allows you to define your API endpoints using a combination of `docs.js - 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": { @@ -15,13 +15,13 @@ Mintlify allows you to define your API endpoints using a combination of `docs.js "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": { @@ -35,7 +35,6 @@ Mintlify allows you to define your API endpoints using a combination of `docs.js - Each API endpoint page should have a corresponding MDX file. At the top of each file, define: ```md @@ -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} ``` - If you have `server` configured in [docs.json](/settings/global), you can use relative paths like `/v1/endpoint`. - - 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' + --- ``` - 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). - + \ No newline at end of file diff --git a/docs.json b/docs.json index 381cdcce0..647709581 100644 --- a/docs.json +++ b/docs.json @@ -22,7 +22,10 @@ { "group": "Editing", "icon": "pen-paintbrush", - "pages": ["development", "web-editor"] + "pages": [ + "development", + "web-editor" + ] }, "settings/global", { @@ -37,7 +40,8 @@ ] }, "themes", - "migration" + "migration", + "settings/github" ] }, { @@ -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" @@ -85,7 +90,8 @@ "settings/github", "settings/gitlab", "settings/ci", - "settings/preview-deployments" + "settings/preview-deployments", + "settings/ci" ] }, { @@ -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", @@ -153,7 +163,8 @@ "advanced/rest-api/chat/create-topic", "advanced/rest-api/chat/generate-message" ] - } + }, + "advanced/rest-api/overview" ] } ] @@ -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", @@ -251,7 +262,9 @@ "groups": [ { "group": "Changelog", - "pages": ["changelog/overview"] + "pages": [ + "changelog/overview" + ] } ] } @@ -363,4 +376,4 @@ "publicApiKey": "pk_76a6caa274e800f3ceff0b2bc6b9b9d82ab8" } } -} +} \ No newline at end of file diff --git a/settings/ci.mdx b/settings/ci.mdx index 357c1a3a7..ddd08a364 100644 --- a/settings/ci.mdx +++ b/settings/ci.mdx @@ -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. -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. +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.
- -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. ## 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 @@ -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`. 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. -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. #### Packages @@ -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 */} @@ -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 {/* */} @@ -111,4 +107,5 @@ This text will be ignored by Vale {/* */} ``` -Please note that these commment tags are not supported within Mintlify components, but can be used anywhere at the base level of a document. \ No newline at end of file + +Please note that these comment tags are not supported within Mintlify components but can be used anywhere at the base level of a document. \ No newline at end of file diff --git a/settings/github.mdx b/settings/github.mdx index 310499c06..50e3cfd1e 100644 --- a/settings/github.mdx +++ b/settings/github.mdx @@ -5,22 +5,23 @@ 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 +documentation 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). ## 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 +where your documentation repository 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). -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. +For GitHub Apps, you can choose to grant permissions to a single repository. +We highly recommend this approach, as we only need access to the repository where +your documentation is hosted. @@ -28,35 +29,35 @@ your docs are hosted. ## Permissions -During the installation of our GitHub app, you will be prompted to grant certain -permissions: +During the installation of our GitHub App, you will be prompted to grant the +following permissions: - Read and write access to `checks`, `contents`, `deployments`, `pull requests`, and `workflows` These permissions are leveraged to provide a seamless experience when managing -your docs. +your documentation: -When you make a commit to the branch you configured as your docs deployment -branch, we fetch the contents of the files changed to update your docs. To -accomplish this we need read access to your `contents`. +- When you make a commit to your configured documentation deployment branch, + we fetch the contents of the changed files to update your documentation. + This requires read access to your `contents`. -When pull requests are created we create a check and preview deployment which is -why we need write access to `checks` and `deployments`. +- When pull requests are created, we create a check and preview deployment, + which requires write access to `checks` and `deployments`. -Inside the Mintlify web editor, Mintlify works on your behalf to create branches -and pull requests which is why we need write access to `pull requests` and -`workflows`. +- Within the Mintlify web editor, Mintlify works on your behalf to create + branches and pull requests, necessitating write access to `pull requests` + and `workflows`. - If you are concerned about the write permissions, the GitHub App will only - have access to the repos you give it access to _and_ if you have branch - protections on it _cannot_ push directly to your branches - it abides by your - branch protection rules. + If you are concerned about the write permissions, please note that the GitHub + App will only have access to the repositories you explicitly grant it access to. + Additionally, if you have branch protection rules in place, the App cannot + push directly to your branches—it must abide by your branch protection rules. -## Repositories Installations +## Repository Installations -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). +When installing our GitHub App, you will be prompted to select either all repositories +or a specific subset. This selection can be modified at any time through the +[GitHub App settings](https://github.com/apps/mintlify/installations/new). \ No newline at end of file