Use CI checks to lint your docs for errors and provide warnings before you deploy. Mintlify CI checks run on pull requests against a configured deployment branch.
Installation
To begin, follow the steps on the GitHub page.
Configuration
Configure the CI checks enabled for a deployment by navigating to the Add-ons page of your dashboard. Enable the checks that you want to run.
When enabling checks, you can choose to run them at a Warning or Blocking level.
- A
Warning level check never provides a failure status, even if there is an error or suggestions.
- A
Blocking level check provides a failure status if there is an error or suggestions.
Available CI checks
Broken links
Similar to how the CLI link checker works on your local machine, the broken link CI check automatically searches your documentation content for broken internal links between pages within your site. It does not check external links to other websites.
To see detailed results for broken links on a pull request, click the Checks tab, then click the Mintlify broken links check. The results list any files with broken links found in the pull request.
Vale
Vale is an open source rule-based prose linter which supports a range of document types, including Markdown and MDX. Use Vale to check for consistency of style and tone in your documentation.
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 content directory of your deployment, the Vale CI check uses that configuration file and any configuration files in your specified stylesPath.
If you don’t have a Vale config file, the default configuration automatically loads.
Default vale.ini configuration
# Top level styles
StylesPath = /app/styles
MinAlertLevel = suggestion
# Inline HTML tags to ignore (code/tt for code snippets, img/url for links/images, a for anchor tags)
IgnoredScopes = code, tt, img, url, a
SkippedScopes = script, style, pre, figure
# Vocabularies
Vocab = Mintlify
# Parse MDX as MD to avoid fragility with JSX
[formats]
mdx = md
# Only match MDX
[*.mdx]
BasedOnStyles = Vale
Vale.Terms = NO # Enforces really harsh capitalization rules, keep off
# Ignore JSX/MDX-specific syntax patterns
# `import ...`, `export ...`
# `<Component ... />`
# `<Component>...</Component>`
# `{ ... }`
TokenIgnores = (?sm)((?:import|export) .+?$), \
(?<!`)(<\w+ ?.+ ?\/>)(?!`), \
(<[A-Z]\w+>.+?<\/[A-Z]\w+>), \
\{[^}]*\}
# Exclude multiline JSX and curly braces
# `<Component \n ... />`
BlockIgnores = (?sm)^(<\w+\n .*\s\/>)$, \
(?sm)^({.+.*})
Mintlify
mintlify
VSCode
openapi
OpenAPI
GitHub
APIs
repo
npm
dev
Lorem
ipsum
impsum
amet
const
myName
myObject
bearerAuth
favicon
topbar
url
borderRadius
args
modeToggle
ModeToggle
isHidden
autoplay
_italic_
Strikethrough
Blockquotes
Blockquote
Singleline
Multiline
onboarding
async
await
boolean
enum
func
impl
init
instanceof
typeof
params
stdin
stdout
stderr
stdout
stdin
var
const
let
null
undefined
struct
bool
cors
csrf
env
xhr
xhr2
jwt
oauth
websocket
localhost
middleware
runtime
webhook
stdin
stdout
json
yaml
yml
md
txt
tsx
jsx
css
scss
html
png
jpg
svg
cdn
cli
css
dom
dto
env
git
gui
http
https
ide
jvm
mvc
orm
rpc
sdk
sql
ssh
ssl
tcp
tls
uri
url
ux
ui
nodejs
npm
yarn
pnpm
eslint
pytest
golang
rustc
kubectl
mongo
postgres
redis
JavaScript
TypeScript
Python
Ruby
Rust
Go
Golang
Java
Kotlin
Swift
Node.js
NodeJS
Deno
React
Vue
Angular
Next.js
Nuxt
Express
Django
Flask
Spring
Laravel
Redux
Vuex
TensorFlow
PostgreSQL
MongoDB
Redis
PNPM
Docker
Kubernetes
AWS
Azure
GCP
Terraform
Jenkins
CircleCI
GitLab
Heroku
Git
git
GitHub
GitLab
Bitbucket
VSCode
Visual Studio Code
IntelliJ
WebStorm
ESLint
eslint
Prettier
prettier
Webpack
webpack
Vite
vite
Babel
babel
Jest
jest
Mocha
Cypress
Postman
HTTP
HTTPS
OAuth
JWT
GraphQL
REST
WebSocket
TCP/IP
NPM
Yarn
PNPM
Pip
PIP
Cargo
RubyGems
Swagger
OpenAPI
Markdown
MDX
Storybook
TypeDoc
JSDoc
MySQL
PostgreSQL
MongoDB
Redis
Elasticsearch
DynamoDB
Linux
Unix
macOS
iOS
Firefox
Chromium
WebKit
config
ctx
desc
dir
elem
err
len
msg
num
obj
prev
proc
ptr
req
res
str
tmp
val
vars
todo
href
lang
nav
prev
next
toc
styles/config/vocabularies/Mintlify directory with accept.txt and reject.txt files.
accept.txt: Words that the Vale linter should ignore. For example, product names or uncommon terms.reject.txt: Words that the Vale linter should flag as errors. For example, jargon or words that are not appropriate for the tone of your documentation.
Example Vale file structure
/your-project
|- docs.json
|- .vale.ini
|- styles/
|- config/
|- vocabularies/
|- Mintlify/
|- accept.txt
|- reject.txt
|- example-page.mdx
Example monorepo Vale file structure
/your-monorepo
|- main.ts
|- docs/
|- docs.json
|- .vale.ini
|- styles/
|- config/
|- vocabularies/
|- Mintlify/
|- accept.txt
|- reject.txt
|- example-page.mdx
|- test/
For security reasons, absolute stylesPath, or stylesPath which include .. values aren’t supported.Use relative paths and include the stylesPath in your repository.
Packages
Vale supports a range of packages that check for spelling and style errors. Any packages you include in your repository under the correct stylesPath automatically install and run with your Vale configuration.
For packages not included in your repository, you may specify any packages from the Vale package registry, and they’re automatically downloaded and used in your Vale configuration.
For security reasons, automatically downloading packages that aren’t from the Vale package registry is not supported. Vale with MDX
MDX native support requires Vale 3.10.0 or later. Check your Vale version with vale --version.
{/* ... */}:
{/* vale off */}
Vale ignores this text
{/* vale on */}
Do not place {/* vale off */} or similar MDX expression comments as direct children of a JSX component between sibling elements. For example, between two <Step> elements inside a <Steps> component.Place comments inside a specific element’s content or restructure the content to avoid needing comments.
