CI Checks

Mintlify is capable of using its installed Github App 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 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.

​

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 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 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.

​

Packages

Vale supports a range of 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, and they will automatically be downloaded and used in your Vale configuration.

​

Vale with MDX

Vale does not natively support MDX, but Vale’s author has provided a custom extension to support it.

If you’d prefer not to use this extension, we recommend the following lines in your .vale.ini file:

[formats]
mdx = md

[*.mdx]
CommentDelimiters = {/*, */}

TokenIgnores = (?sm)((?:import|export) .+?$), \
(?<!`)(<\w+ ?.+ ?\/>)(?!`), \
(<[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 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.

{/* 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:

{/* <!-- vale off --> */}

This text will be ignored by Vale

{/* <!-- vale on --> */}

Please note that these commment tags are not supported within Mintlify components, but can be used anywhere at the base level of a document.