diff --git a/changelog.mdx b/changelog.mdx index d458ef26..cf43911e 100644 --- a/changelog.mdx +++ b/changelog.mdx @@ -73,7 +73,7 @@ mode: "center" ## CI Checks - Automatically lint your docs to find broken links, discover spelling and grammar issues, or enforce writing styles with your own Vale config. Learn more in our [docs](settings/ci). + Automatically lint your docs to find broken links, discover spelling and grammar issues, or enforce writing styles with your own Vale config. Learn more in our [docs](/settings/add-ons/ci). ## .md support for LLMs diff --git a/docs.json b/docs.json index 74a53b64..07687131 100644 --- a/docs.json +++ b/docs.json @@ -128,8 +128,15 @@ "settings/broken-links", "settings/github", "settings/gitlab", - "settings/ci", - "settings/preview-deployments" + { + "group": "Add-Ons", + "icon": "puzzle-piece", + "pages": [ + "settings/add-ons/feedback", + "settings/add-ons/ci", + "settings/add-ons/preview-deployments" + ] + } ] }, { diff --git a/settings/add-ons/ci.mdx b/settings/add-ons/ci.mdx new file mode 100644 index 00000000..c5314da3 --- /dev/null +++ b/settings/add-ons/ci.mdx @@ -0,0 +1,114 @@ +--- +title: Continuous Improvement +description: "User analytics and checks to improve your documentation" +icon: "circle-check" +--- + + + This feature is only available for customers on [paid + plans](https://mintlify.com/pricing?ref=docs-ci) and for GitHub. Support for + other platforms is coming soon. Please{" "} + contact sales for more information. + + +To begin, you will need to have followed the steps on the [GitHub](/settings/github) page and have the `Mintlify` GitHub app installed on your repository. + +### 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. + +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 changes are suggested.
+ +A `Warning` level check will never provide a failure status, even if there is an error or suggestions. + + + +### When Do They Run? + +CI checks are configured to run on pull requests against your configured deployment branch. + +### Available CI Checks + +#### Broken Links + +Similarly to how the [CLI link checker](/settings/broken-links#broken-links) works on your local machine, the GitHub app will automatically check your docs for broken links. +To see the results of this check, you can visit the GitHub's check results page for a specific commit. + +#### Vale.sh + +[Vale.sh](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.sh 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. +We will also automatically use any configuration files in your specified `stylesPath`. For security reasons, we are unable to use any paths that reference files using `..` or absolute paths. + + + Don't have a Vale.sh 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. + + +##### Packages + +Vale.sh supports a range of [packages](https://vale.sh/docs/keys/packages), which can be used to check for spelling and style errors. +Any packages you include in your repository under the correct `stylesPath` will be automatically installed and used in your Vale.sh configuration. + +For packages not included in your repository, you may specify any packages from the [Vale.sh package registry](https://vale.sh/explorer), and they will automatically be downloaded and used in your Vale.sh configuration. + + + Please note that for security reasons, we are unable to support automatically + downloading packages that are not from the [Vale.sh package + registry](https://vale.sh/explorer). + + +##### Vale.sh with MDX + +Vale.sh does not natively support MDX, but its author has provided a [custom extension](https://github.com/errata-ai/MDX) to support it. + +If you'd prefer not to use this extension, we recommend the following lines in your `.vale.ini` file: + +```ini +[formats] +mdx = md + +[*.mdx] +CommentDelimiters = {/*, */} + +TokenIgnores = (?sm)((?:import|export) .+?$), \ +(?)(?!`), \ +(<[A-Z]\w+>.+?<\/[A-Z]\w+>) + +BlockIgnores = (?sm)^(<\w+\n .*\s\/>)$, \ +(?sm)^({.+.*}) +``` + +To use Vale.sh's in-document comments, use MDX-style comments `{/* ... */}`. +If you use the `CommentDelimiters = {/*, */}` [setting](https://vale.sh/docs/keys/commentdelimiters) in your configuration, Vale.sh will automatically interpret these comments while linting. +This means you can easily use Vale's in-built features, like skipping lines or sections. + +```mdx +{/* vale off */} + +This text will be ignored by Vale + +{/* vale on */} +``` + +If you choose not to use `CommentDelimiters`, but still choose to use Vale.sh's comments, you must wrap any Vale.sh comments in MDX comments `{/* ... */}`. For example: + +```mdx +{/* */} + +This text will be ignored by Vale + +{/* */} +``` + +Please note that these comment tags are not supported within Mintlify components, but can be used anywhere at the base level of a document. diff --git a/settings/add-ons/feedback.mdx b/settings/add-ons/feedback.mdx new file mode 100644 index 00000000..41fabc91 --- /dev/null +++ b/settings/add-ons/feedback.mdx @@ -0,0 +1,32 @@ +--- +title: Feedback +description: 'Allow users to give feedback on your docs' +icon: 'chart-line' +--- + +Mintlify supports a range of [feedback](#feedback) and [analytics tools](/integrations/analytics) to help you improve your documentation. + +Alongside third party integrations, Mintlify maintains features to help you collect feedback and build analytics on your docs. + +### Feedback +You can enable feedback collection on your docs in three ways: + +1. **Thumbs Rating**: Allow users to rate your docs with a thumbs up or down. This is useful for gauging user satisfaction and identifying areas for improvement +2. **Edit Suggestion**: Allow users to suggest edits to your docs. These edits are presented in your version control system (e.g. GitHub) as a pull request. This feature is only available on documentation which uses a public repository +3. **Raise Issues**: Allow users to raise issues with your docs. This is useful for users to report bugs, inconsistencies, or to raise accessibility concerns + +### Analytics +Mintlify automatically collects analytics on your docs to help you understand how users are interacting with your docs. This includes: + +- Any feedback you've chosen to collect +- Unique visitors +- Page views +- Actions taken on page +- Source\(s\) of traffic +- Your most popular pages +- Popular search queries + +These analytics are available in the 'Analytics' tab in your dashboard. + +### Privacy & Compliance +Built-in analytics can be disabled at any time using [data privacy integrations](/integrations/privacy/overview) for compliance purposes. diff --git a/settings/preview-deployments.mdx b/settings/add-ons/preview-deployments.mdx similarity index 74% rename from settings/preview-deployments.mdx rename to settings/add-ons/preview-deployments.mdx index 9d01bd45..facb7314 100644 --- a/settings/preview-deployments.mdx +++ b/settings/add-ons/preview-deployments.mdx @@ -5,13 +5,14 @@ icon: "scan-eye" --- - Preview Deployments are available on the [Growth and Enterprise plans](https://mintlify.com/pricing?ref=preview-deployments). Please{" "} + Preview Deployments are available on the [Growth and Enterprise + plans](https://mintlify.com/pricing?ref=preview-deployments). Please{" "} contact sales for more information. Preview Deployments allow you to preview changes to your docs in a live deployment without merging those changes to your production branch. -If you have created a pull or merge request when using Git, the generated preview URL will be available as a comment from the Mintlify bot in the PR. This URL will always reflect the latest deployment changes. +If you have created a pull request (GitHub) or merge request (GitLab) when using Git, the generated preview URL will be available as a comment from the Mintlify bot in the pull or merge request. This URL will always reflect the latest deployment changes. ## Sharing Preview Deployments diff --git a/settings/ci.mdx b/settings/ci.mdx deleted file mode 100644 index 0fafbfd1..00000000 --- a/settings/ci.mdx +++ /dev/null @@ -1,115 +0,0 @@ ---- -title: CI Checks -description: "Add broken links, linting, and grammar checks to the updating process" -icon: 'circle-check' ---- - - - This feature is only available for customers on [paid plans](https://mintlify.com/pricing?ref=docs-ci) and for GitHub. Support for other platforms is coming soon. Please{" "} - contact sales for more information. - - -Use CI checks to lint your docs for errors, and give you 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 -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. - -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 changes are suggested.
- -A `Warning` level check will never provide a failure status, even if there is an error 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. - -## Available CI Checks - -### Broken Links - -Similarly to how the [CLI link checker](/settings/broken-links#broken-links) works on your local machine, we will automatically check your docs for broken links. -To see the results of this check, you can visit GitHub's check results page for a specific commit. - -### Vale - -[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. - -#### Configuration -If you have a `.vale.ini` file in the root 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. - - -#### Packages -Vale supports a range of [packages](https://vale.sh/docs/keys/packages), which can be used to check for spelling and style errors. -Any packages you include in your repository under the correct `stylesPath` will be automatically installed and used in your Vale configuration. - -For packages not included in your repository, you may specify any packages from the [Vale package registry](https://vale.sh/explorer), and they will automatically be downloaded and used in your Vale configuration. - - -Please note that for security reasons, we are unable to support automatically downloading packages that are not from the [Vale package registry](https://vale.sh/explorer). - - -#### Vale with MDX -Vale does not natively support MDX, but Vale's author has provided a [custom extension](https://github.com/errata-ai/MDX) to support it. - -If you'd prefer not to use this extension, we recommend the following lines in your `.vale.ini` file: -```ini -[formats] -mdx = md - -[*.mdx] -CommentDelimiters = {/*, */} - -TokenIgnores = (?sm)((?:import|export) .+?$), \ -(?)(?!`), \ -(<[A-Z]\w+>.+?<\/[A-Z]\w+>) - -BlockIgnores = (?sm)^(<\w+\n .*\s\/>)$, \ -(?sm)^({.+.*}) -``` - -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. - -```mdx -{/* vale off */} - -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: - -```mdx -{/* */} - -This text will be ignored by Vale - -{/* */} -``` -Please note that these comment tags are not supported within Mintlify components, but can be used anywhere at the base level of a document.