mirror of
https://github.com/mintlify/docs.git
synced 2026-09-14 13:35:46 +08:00
locadex-agent[bot]
35efaf55fd
Co-authored-by: locadex-agent[bot] <217277504+locadex-agent[bot]@users.noreply.github.com>
438 lines
6.9 KiB
Plaintext
438 lines
6.9 KiB
Plaintext
---
|
||
title: "CI 检查"
|
||
description: "在 CI/CD 中自动执行失效链接检测、lint 与语法校验。"
|
||
keywords: ["continuous integration", "CI/CD", "checks", "Vale", "linter"]
|
||
---
|
||
|
||
<Info>
|
||
[Pro 和 Enterprise 方案](https://mintlify.com/pricing?ref=docs-ci)包含针对 GitHub 存储库的 CI 检查。
|
||
</Info>
|
||
|
||
使用 CI 检查对文档进行 lint，捕捉错误并在部署前给出 Warning。Mintlify 的 CI 检查会在指向已配置部署用分支的拉取请求（PR）上运行。
|
||
|
||
<div id="installation">
|
||
## 安装
|
||
</div>
|
||
|
||
首先，请按照 [GitHub](/zh/deploy/github) 页面上的步骤进行操作。
|
||
|
||
<Tip>
|
||
只需访问存放文档内容的存储库，因此强烈建议仅授予该存储库的访问权限。
|
||
</Tip>
|
||
|
||
## 配置
|
||
|
||
前往控制台的 [附加组件](https://dashboard.mintlify.com/products/addons) 页面，配置在部署中启用的 CI 检查。开启你希望运行的检查。
|
||
|
||
启用检查时，你可以选择以 `Warning` 或 `Blocking` 级别运行。
|
||
|
||
* `Warning` 级别的检查即使出现错误或提出建议，也不会标记为失败。
|
||
* `Blocking` 级别的检查如果出现错误或提出建议，则会标记为失败。
|
||
|
||
<div id="available-ci-checks">
|
||
## 可用的 CI 检测
|
||
</div>
|
||
|
||
<div id="broken-links">
|
||
### 失效链接
|
||
</div>
|
||
|
||
与[命令行界面（CLI）链接检查器](/zh/installation#find-broken-links)在本地环境中的工作方式类似，失效链接 CI 检查会自动扫描你的文档内容，查找失效的内部链接。
|
||
|
||
要查看检查结果，请前往 GitHub 上该特定提交的检查结果页面。
|
||
|
||
<div id="vale">
|
||
### Vale
|
||
</div>
|
||
|
||
[Vale](https://vale.sh/) 是一款开源的、基于规则的文本风格检查工具（prose linter），支持多种文档类型，包括 Markdown 和 MDX。使用 Vale 可以检查文档中的写作风格和语气是否一致。
|
||
|
||
Mintlify 支持在 CI 检查中自动运行 Vale，并将结果显示为检查状态。
|
||
|
||
<div id="configuration">
|
||
#### 配置
|
||
</div>
|
||
|
||
如果在你的部署的内容根目录中有一个 `.vale.ini` 文件，那么 Vale CI 检查会使用该配置文件以及你在 `stylesPath` 中指定的任何配置文件。
|
||
|
||
如果你没有 Vale 配置文件，则会自动加载默认配置。
|
||
|
||
```mdx Default vale.ini configuration expandable
|
||
# Top level styles
|
||
StylesPath = /app/styles
|
||
MinAlertLevel = suggestion
|
||
# 要忽略的内联 HTML 标签（code/tt 用于代码片段，img/url 用于链接/图像，a 用于锚标签）
|
||
IgnoredScopes = code, tt, img, url, a
|
||
SkippedScopes = script, style, pre, figure
|
||
|
||
# Vocabularies
|
||
Vocab = Mintlify
|
||
|
||
# Packages
|
||
Packages = MDX
|
||
|
||
# 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)^({.+.*})
|
||
```
|
||
|
||
默认的 Vale 词汇列表包含以下词汇。
|
||
|
||
```text Default Vale vocabulary expandable
|
||
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` 目录，并在其中添加 `accept.txt` 和 `reject.txt` 文件。
|
||
|
||
|
||
* `accept.txt`: 应由 Vale linter 忽略的词语，例如产品名称或不常见的术语。
|
||
* `reject.txt`: 应被标记为错误的词语，例如与你文档语气不相符的行话或用词。
|
||
|
||
```text Example Vale file structure
|
||
/your-project
|
||
|- docs.json
|
||
|- .vale.ini
|
||
|- styles/
|
||
|- config/
|
||
|- vocabularies/
|
||
|- Mintlify/
|
||
|- accept.txt
|
||
|- reject.txt
|
||
|- example-page.mdx
|
||
```
|
||
|
||
```text 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/
|
||
```
|
||
|
||
<Note>
|
||
出于安全原因，不支持使用绝对路径形式的 `stylesPath`，也不支持包含 `..` 的 `stylesPath`。
|
||
|
||
请使用相对路径，并在你的存储库中包含该 `stylesPath`。
|
||
</Note>
|
||
|
||
<div id="packages">
|
||
#### 软件包
|
||
</div>
|
||
|
||
Vale 支持一系列[软件包](https://vale.sh/docs/keys/packages)，可用于检查拼写和写作风格错误。任何你在存储库中放在正确 `stylesPath` 下的软件包，都会被自动安装并在你的 Vale 配置中使用。
|
||
|
||
对于未包含在存储库中的软件包，你可以指定来自 [Vale package registry](https://vale.sh/explorer) 的任意软件包，它们会被自动下载并在你的 Vale 配置中使用。
|
||
|
||
<Note>
|
||
出于安全原因，**不**支持自动下载不来自 [Vale package registry](https://vale.sh/explorer) 的软件包。
|
||
</Note>
|
||
|
||
<div id="vale-with-mdx">
|
||
#### 将 Vale 与 `MDX` 搭配使用
|
||
</div>
|
||
|
||
<Note>
|
||
对 MDX 的原生支持需要 Vale 3.10.0 或更高版本。使用 `vale --version` 来检查你的 Vale 版本。
|
||
</Note>
|
||
|
||
要在 MDX 文件中使用 Vale 的文内注释，请使用 MDX 风格的注释 `{/* ... */}`：
|
||
|
||
```mdx
|
||
{/* vale off */}
|
||
|
||
此文本会被 Vale 忽略
|
||
|
||
{/* vale on */}
|
||
```
|
||
|
||
Vale 会在 MDX 文件中自动识别并遵守这些注释，无需额外配置。使用注释来跳过需要被 linter 忽略的行或片段。
|