From eab1abd11bff386d03b494b70918793c55ad6f85 Mon Sep 17 00:00:00 2001 From: IHSten <32083682+IHSten@users.noreply.github.com> Date: Fri, 11 Apr 2025 15:16:52 -0700 Subject: [PATCH 1/3] Split add-ons into an add-on section, add page about feedback and analytics --- docs.json | 13 +- settings/add-ons/ci.mdx | 102 ++++++++++++++++ settings/add-ons/feedback.mdx | 32 +++++ .../{ => add-ons}/preview-deployments.mdx | 10 +- settings/ci.mdx | 114 ------------------ 5 files changed, 149 insertions(+), 122 deletions(-) create mode 100644 settings/add-ons/ci.mdx create mode 100644 settings/add-ons/feedback.mdx rename settings/{ => add-ons}/preview-deployments.mdx (60%) delete mode 100644 settings/ci.mdx diff --git a/docs.json b/docs.json index 3142b96b..18c10ace 100644 --- a/docs.json +++ b/docs.json @@ -87,15 +87,22 @@ { "group": "Configurations", "pages": [ + { + "group": "Add-Ons", + "icon": "puzzle-piece", + "pages": [ + "settings/add-ons/feedback", + "settings/add-ons/ci", + "settings/add-ons/preview-deployments" + ] + }, "settings/custom-domain", "settings/seo", "settings/llms", "settings/custom-scripts", "settings/broken-links", "settings/github", - "settings/gitlab", - "settings/ci", - "settings/preview-deployments" + "settings/gitlab" ] }, { diff --git a/settings/add-ons/ci.mdx b/settings/add-ons/ci.mdx new file mode 100644 index 00000000..6d051ff5 --- /dev/null +++ b/settings/add-ons/ci.mdx @@ -0,0 +1,102 @@ +--- +title: Continuous Improvement +description: 'User analytics and checks to improve your documentation' +icon: 'circle-check' +--- + + + CI checks are available on the Growth and Enterprise plans, or as paid add-ons. 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 60% rename from settings/preview-deployments.mdx rename to settings/add-ons/preview-deployments.mdx index b12296da..123cd889 100644 --- a/settings/preview-deployments.mdx +++ b/settings/add-ons/preview-deployments.mdx @@ -1,17 +1,17 @@ --- -title: "Preview Deployments" -description: "Preview changes to your docs in a live deployment" -icon: "street-view" +title: Preview Deployments +description: 'Preview changes to your docs in a live deployment' +icon: 'street-view' --- - Preview Deployments are available on the Growth and Enterprise plans. Please{" "} + Preview Deployments are only available on Growth and Enterprise plans or as a paid add-on. 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 02fed042..00000000 --- a/settings/ci.mdx +++ /dev/null @@ -1,114 +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 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. - -## 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. From 496e3f8f516a12ebbf79e2085ebb580dbd005ccc Mon Sep 17 00:00:00 2001 From: IHSten <32083682+IHSten@users.noreply.github.com> Date: Fri, 11 Apr 2025 15:20:21 -0700 Subject: [PATCH 2/3] move add-ons to bottom of nav section --- docs.json | 16 ++++++++-------- 1 file changed, 8 insertions(+), 8 deletions(-) diff --git a/docs.json b/docs.json index 18c10ace..54607b8d 100644 --- a/docs.json +++ b/docs.json @@ -87,6 +87,13 @@ { "group": "Configurations", "pages": [ + "settings/custom-domain", + "settings/seo", + "settings/llms", + "settings/custom-scripts", + "settings/broken-links", + "settings/github", + "settings/gitlab", { "group": "Add-Ons", "icon": "puzzle-piece", @@ -95,14 +102,7 @@ "settings/add-ons/ci", "settings/add-ons/preview-deployments" ] - }, - "settings/custom-domain", - "settings/seo", - "settings/llms", - "settings/custom-scripts", - "settings/broken-links", - "settings/github", - "settings/gitlab" + } ] }, { From d5a8ab06f146cf38d4bd7cdd0eb02531d709a231 Mon Sep 17 00:00:00 2001 From: IHSten <32083682+IHSten@users.noreply.github.com> Date: Fri, 11 Apr 2025 16:12:33 -0700 Subject: [PATCH 3/3] fix a broken link --- changelog/overview.mdx | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/changelog/overview.mdx b/changelog/overview.mdx index 5454d30a..f7a81819 100644 --- a/changelog/overview.mdx +++ b/changelog/overview.mdx @@ -67,7 +67,7 @@ Export all of your documentation, a subdirectory, or a singe page as a PDF. ## 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