|
| 1 | +--- |
| 2 | +title: Continuous Improvement |
| 3 | +description: 'User analytics and checks to improve your documentation' |
| 4 | +icon: 'circle-check' |
| 5 | +--- |
| 6 | + |
| 7 | +<Info> |
| 8 | + CI checks are available on the Growth and Enterprise plans, or as paid add-ons. Please{" "} |
| 9 | + < a href="mailto:[email protected]">contact sales</ a> for more information. |
| 10 | +</Info> |
| 11 | + |
| 12 | +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. |
| 13 | + |
| 14 | +### Configuration |
| 15 | + |
| 16 | +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. |
| 17 | + |
| 18 | +When enabling checks, you can choose to run them at a `Warning` or `Blocking` level. |
| 19 | + |
| 20 | +<Note> |
| 21 | + |
| 22 | +A `Blocking` level check will provide a failure status if not passed, or changes are suggested.<br/> |
| 23 | + |
| 24 | +A `Warning` level check will never provide a failure status, even if there is an error or suggestions. |
| 25 | + |
| 26 | +</Note> |
| 27 | + |
| 28 | +### When Do They Run? |
| 29 | + |
| 30 | +CI checks are configured to run on pull requests against your configured deployment branch. |
| 31 | + |
| 32 | +### Available CI Checks |
| 33 | + |
| 34 | +#### Broken Links |
| 35 | + |
| 36 | +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. |
| 37 | +To see the results of this check, you can visit the GitHub's check results page for a specific commit. |
| 38 | + |
| 39 | +#### Vale.sh |
| 40 | + |
| 41 | +[Vale.sh](https://vale.sh/) is an open-source rule-based prose linter which supports a range of document types, including Markdown and MDX. |
| 42 | + |
| 43 | +Mintlify supports automatically running Vale.sh in a CI check, and displaying the results as a check status. |
| 44 | + |
| 45 | +##### Configuration |
| 46 | +If you have a `.vale.ini` file in the root the content directory for your deployment, we will automatically use that configuration file. |
| 47 | +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. |
| 48 | + |
| 49 | +<Tip>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.</Tip> |
| 50 | + |
| 51 | +##### Packages |
| 52 | +Vale.sh supports a range of [packages](https://vale.sh/docs/keys/packages), which can be used to check for spelling and style errors. |
| 53 | +Any packages you include in your repository under the correct `stylesPath` will be automatically installed and used in your Vale.sh configuration. |
| 54 | + |
| 55 | +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. |
| 56 | + |
| 57 | +<Warning> |
| 58 | +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). |
| 59 | +</Warning> |
| 60 | + |
| 61 | +##### Vale.sh with MDX |
| 62 | +Vale.sh does not natively support MDX, but its author has provided a [custom extension](https://github.com/errata-ai/MDX) to support it. |
| 63 | + |
| 64 | +If you'd prefer not to use this extension, we recommend the following lines in your `.vale.ini` file: |
| 65 | +```ini |
| 66 | +[formats] |
| 67 | +mdx = md |
| 68 | + |
| 69 | +[*.mdx] |
| 70 | +CommentDelimiters = {/*, */} |
| 71 | + |
| 72 | +TokenIgnores = (?sm)((?:import|export) .+?$), \ |
| 73 | +(?<!`)(<\w+ ?.+ ?\/>)(?!`), \ |
| 74 | +(<[A-Z]\w+>.+?<\/[A-Z]\w+>) |
| 75 | + |
| 76 | +BlockIgnores = (?sm)^(<\w+\n .*\s\/>)$, \ |
| 77 | +(?sm)^({.+.*}) |
| 78 | +``` |
| 79 | + |
| 80 | +To use Vale.sh's in-document comments, use MDX-style comments `{/* ... */}`. |
| 81 | +If you use the `CommentDelimiters = {/*, */}` [setting](https://vale.sh/docs/keys/commentdelimiters) in your configuration, Vale.sh will automatically interpret these comments while linting. |
| 82 | +This means you can easily use Vale's in-built features, like skipping lines or sections. |
| 83 | + |
| 84 | +```mdx |
| 85 | +{/* vale off */} |
| 86 | + |
| 87 | +This text will be ignored by Vale |
| 88 | + |
| 89 | +{/* vale on */} |
| 90 | +``` |
| 91 | + |
| 92 | + |
| 93 | +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: |
| 94 | + |
| 95 | +```mdx |
| 96 | +{/* <!-- vale off --> */} |
| 97 | + |
| 98 | +This text will be ignored by Vale |
| 99 | + |
| 100 | +{/* <!-- vale on --> */} |
| 101 | +``` |
| 102 | +Please note that these comment tags are not supported within Mintlify components, but can be used anywhere at the base level of a document. |
0 commit comments