CI checks

リンク切れ、リント、文法チェックを更新プロセスに追加する

Pro と Enterprise プランには、GitHub リポジトリ向けの CI チェックが含まれます。

CI チェックを使って、ドキュメントのエラーを検出し、デプロイ前に警告を出せます。CI チェックは、設定したデプロイブランチへのコミット時、またはそのブランチへのプルリクエスト時に実行されるように構成されています。

インストール

まずは GitHub ページの手順に従ってください。

GitHub App では、権限を単一のリポジトリのみに付与できます。ドキュメントをホストしているリポジトリへのアクセスだけで十分なため、その設定を強く推奨します。

設定

ダッシュボードのAdd-onsページに移動し、デプロイに対して有効化する CI チェックを設定します。実行したいチェックをオンにしてください。

チェックを有効化する際は、Warning または Blocking のレベルで実行するよう選択できます。

• Warning レベルのチェックは、エラーや提案があっても失敗ステータスにはなりません。
• Blocking レベルのチェックは、不合格の場合や変更が提案された場合に失敗ステータスになります。

利用可能な CI チェック

リンク切れ

ローカル環境のCLI リンクチェッカーと同様に、ドキュメント内のリンク切れを自動で検出します。

結果を確認するには、該当のコミットの GitHub のチェック結果ページを開いてください。

Vale

Vale は、Markdown や MDX などの各種ドキュメント形式に対応した、オープンソースのルールベース文章リンターです。

Mintlify では、CI チェックで Vale を自動実行し、その結果をチェックステータスとして表示できます。

設定

デプロイ対象のルートコンテンツディレクトリに .vale.ini ファイルがある場合、その設定ファイルが自動的に使用されます。指定した stylesPath 内にある設定ファイルも自動的に読み込まれます。

Vale の設定ファイルがない場合は、デフォルト設定が自動的に適用されます。

Default vale.ini configuration

# Top level styles
StylesPath = /app/styles
MinAlertLevel = suggestion
IgnoredScopes = code, tt, img, url, a
SkippedScopes = script, style, pre, figure, code

# Vocabularies
Vocab = Mintlify

# This is required since Vale doesn't officially support MDX
[formats]
mdx = md

# MDX support
[*.mdx]
BasedOnStyles = Vale
Vale.Terms = NO # Enforces really harsh capitalization rules, keep off

# `import ...`, `export ...`
# `<Component ... />`
# `<Component>...</Component>`
# `{ ... }`
TokenIgnores = (?sm)((?:import|export) .+?$), \
(?<!`)(<\w+ ?.+ ?\/>)(?!`), \
(<[A-Z]\w+>.+?<\/[A-Z]\w+>)

# Exclude:
# `<Component \n ... />`
BlockIgnores = (?sm)^(<\w+\n .*\s\/>)$, \
(?sm)^({.+.*})

CommentDelimiters = {/*, */}

Default Vale vocabulary

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

セキュリティ上の理由により、絶対パスの stylesPath や .. を含む stylesPath はサポートしていません。相対パスを使用し、stylesPath をリポジトリに含めてください。

パッケージ

Vale はさまざまなパッケージをサポートしており、スペルやスタイルの誤りの検出に利用できます。 適切な stylesPath の配下にリポジトリへ追加したパッケージは、自動的にインストールされ、Vale の設定で使用されます。

リポジトリに含まれていないパッケージについては、Vale package registry から任意のパッケージを指定でき、自動的にダウンロードされて Vale の設定で使用されます。

セキュリティ上の理由により、Vale package registry 以外のパッケージを自動ダウンロードすることはサポートしていませんのでご注意ください。

Vale と MDX

Vale は標準では MDX をサポートしていませんが、Vale の作者がそれを補うためのカスタム拡張を提供しています。

この拡張を使わない場合は、.vale.ini に次の行を追加することをおすすめします:

[formats]
mdx = md

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

TokenIgnores = (?sm)((?:import|export) .+?$), \
(?<!`)(<\w+ ?.+ ?\/>)(?!`), \
(<[A-Z]\w+>.+?<\/[A-Z]\w+>)

BlockIgnores = (?sm)^(<\w+\n .*\s\/>)$, \
(?sm)^({.+.*})

Vale のインラインコメントを使うには、MDX 形式の {/* ... */} コメントを使用してください。設定で CommentDelimiters = {/*, */} のキーを指定すると、Vale はリンティング中にこれらのコメントを自動的に解釈します。これにより、行やセクションのスキップなど、Vale の組み込み機能を容易に利用できます。

{/* vale off */}

This text will be ignored by Vale

{/* vale on */}

CommentDelimiters を使わない一方で Vale のコメントを使う場合は、Vale のコメントを MDX コメント {/* ... */} で必ず囲んでください。例:

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

This text will be ignored by Vale

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

これらのコメントタグは Mintlify のコンポーネント内ではサポートされませんが、ドキュメントのベースレベルではどこでも使用できます。