From 52600a07403b548d22baf95e2241d7be2bae5776 Mon Sep 17 00:00:00 2001 From: IHSten <32083682+IHSten@users.noreply.github.com> Date: Thu, 30 Jan 2025 16:43:16 -0800 Subject: [PATCH 01/10] add ci checks page, add to mint.json --- mint.json | 1 + settings/ci.mdx | 113 ++++++++++++++++++++++++++++++++++++++++++++++++ 2 files changed, 114 insertions(+) create mode 100644 settings/ci.mdx diff --git a/mint.json b/mint.json index 65c9d33d9..2dc50c804 100644 --- a/mint.json +++ b/mint.json @@ -118,6 +118,7 @@ "settings/add-members", "settings/github", "settings/gitlab", + "settings/ci", "settings/preview-deployments" ] }, diff --git a/settings/ci.mdx b/settings/ci.mdx new file mode 100644 index 000000000..1ba1fc29b --- /dev/null +++ b/settings/ci.mdx @@ -0,0 +1,113 @@ +--- +title: CI/CD +description: "Use Mintlify's CI tools to check your docs" +icon: 'circle-check' +--- + + + This feature is only available for customers using GitHub. If you'd like it enabled for other platforms, please provide [feedback](https://feedback.mintlify.com/roadmap). + + +Mintlify is capable of using its installed Github App to check your docs for errors, and gives you warnings before you deploy. + +## Installation + +To begin, 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 + +{/* */} +``` From 210090536c80d20c29f0d24542f2be9c7925a2e2 Mon Sep 17 00:00:00 2001 From: IHSten <32083682+IHSten@users.noreply.github.com> Date: Mon, 3 Feb 2025 23:25:45 -0800 Subject: [PATCH 02/10] wording, messaging --- settings/ci.mdx | 7 ++++--- 1 file changed, 4 insertions(+), 3 deletions(-) diff --git a/settings/ci.mdx b/settings/ci.mdx index 1ba1fc29b..ab72d8ea0 100644 --- a/settings/ci.mdx +++ b/settings/ci.mdx @@ -1,6 +1,6 @@ --- -title: CI/CD -description: "Use Mintlify's CI tools to check your docs" +title: CI Checks +description: "Use Mintlify's CI tools to lint your docs" icon: 'circle-check' --- @@ -8,7 +8,7 @@ icon: 'circle-check' This feature is only available for customers using GitHub. If you'd like it enabled for other platforms, please provide [feedback](https://feedback.mintlify.com/roadmap). -Mintlify is capable of using its installed Github App to check your docs for errors, and gives you warnings before you deploy. +Mintlify is capable of using its installed Github App to lint your docs for errors, and give you warnings before you deploy. ## Installation @@ -111,3 +111,4 @@ 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 From 8a459a19f9024b88f448fe1576ac2b4c35bfd8c2 Mon Sep 17 00:00:00 2001 From: IHSten <32083682+IHSten@users.noreply.github.com> Date: Tue, 4 Feb 2025 11:04:34 -0800 Subject: [PATCH 03/10] add note to warning about paid plans --- settings/ci.mdx | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/settings/ci.mdx b/settings/ci.mdx index ab72d8ea0..3a61a084e 100644 --- a/settings/ci.mdx +++ b/settings/ci.mdx @@ -5,7 +5,7 @@ icon: 'circle-check' --- - This feature is only available for customers using GitHub. If you'd like it enabled for other platforms, please provide [feedback](https://feedback.mintlify.com/roadmap). + This feature is only available for customers on paid plans using GitHub. If you'd like it enabled for other platforms, please provide [feedback](https://feedback.mintlify.com/roadmap). Mintlify is capable of using its installed Github App to lint your docs for errors, and give you warnings before you deploy. From 84055b03b8428f2c24dee160e9b6b76654566d80 Mon Sep 17 00:00:00 2001 From: IHSten <32083682+IHSten@users.noreply.github.com> Date: Tue, 4 Feb 2025 17:02:49 -0800 Subject: [PATCH 04/10] empty trigger to trigger source checks From 487214a9bd57e81d75936650a68888b35ddb86cc Mon Sep 17 00:00:00 2001 From: IHSten <32083682+IHSten@users.noreply.github.com> Date: Tue, 4 Feb 2025 17:30:47 -0800 Subject: [PATCH 05/10] test commit since we need an effective change --- settings/ci.mdx | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/settings/ci.mdx b/settings/ci.mdx index 3a61a084e..e8d77b579 100644 --- a/settings/ci.mdx +++ b/settings/ci.mdx @@ -111,4 +111,4 @@ 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 commment tags are not supported within Mintlify components, but can be used anywhere at the base level of a document. Remove this later! \ No newline at end of file From 6368f37bca3f747c90f782e352ed39ec797b2a17 Mon Sep 17 00:00:00 2001 From: IHSten <32083682+IHSten@users.noreply.github.com> Date: Tue, 4 Feb 2025 17:31:16 -0800 Subject: [PATCH 06/10] remove test commit --- settings/ci.mdx | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/settings/ci.mdx b/settings/ci.mdx index e8d77b579..3a61a084e 100644 --- a/settings/ci.mdx +++ b/settings/ci.mdx @@ -111,4 +111,4 @@ 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. Remove this later! \ No newline at end of file +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 From bb5c400fcdc18a977fd6c0719e37360de522c7b9 Mon Sep 17 00:00:00 2001 From: IHSten <32083682+IHSten@users.noreply.github.com> Date: Tue, 4 Feb 2025 20:21:21 -0800 Subject: [PATCH 07/10] test commit to trigger Vale --- settings/ci.mdx | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/settings/ci.mdx b/settings/ci.mdx index 3a61a084e..918cf5fcd 100644 --- a/settings/ci.mdx +++ b/settings/ci.mdx @@ -111,4 +111,4 @@ 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 commment tags are not supported within Mintlify components, but can be used anywhere at the base level of a document. Another test commit. \ No newline at end of file From aef0a4819bb204de9fa604e379c2127bf109e6f3 Mon Sep 17 00:00:00 2001 From: IHSten <32083682+IHSten@users.noreply.github.com> Date: Tue, 4 Feb 2025 20:23:06 -0800 Subject: [PATCH 08/10] drop test changes --- settings/ci.mdx | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/settings/ci.mdx b/settings/ci.mdx index 918cf5fcd..3a61a084e 100644 --- a/settings/ci.mdx +++ b/settings/ci.mdx @@ -111,4 +111,4 @@ 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. Another test commit. \ No newline at end of file +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 From c8403ee45bdeae3fa2141b3d765a75c75e945d1b Mon Sep 17 00:00:00 2001 From: IHSten <32083682+IHSten@users.noreply.github.com> Date: Wed, 5 Feb 2025 09:00:00 -0800 Subject: [PATCH 09/10] add CI checks page to docs.json --- docs.json | 3 ++- 1 file changed, 2 insertions(+), 1 deletion(-) diff --git a/docs.json b/docs.json index 857d50abe..bd1b01016 100644 --- a/docs.json +++ b/docs.json @@ -75,7 +75,8 @@ "settings/add-members", "settings/github", "settings/gitlab", - "settings/preview-deployments" + "settings/ci" +, "settings/preview-deployments" ] }, { From 3d7c7ab041c2294ab3612b3a6d61f0c8c47c2500 Mon Sep 17 00:00:00 2001 From: IHSten <32083682+IHSten@users.noreply.github.com> Date: Wed, 5 Feb 2025 09:02:31 -0800 Subject: [PATCH 10/10] small typo --- settings/ci.mdx | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/settings/ci.mdx b/settings/ci.mdx index 3a61a084e..e75149b55 100644 --- a/settings/ci.mdx +++ b/settings/ci.mdx @@ -12,7 +12,7 @@ Mintlify is capable of using its installed Github App to lint your docs for erro ## Installation -To begin, will need to have followed the steps on the [GitHub](/settings/github) page. +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