CI Checks

Automatically validate documentation quality with broken link detection and prose linting on every deployment.

Overview

HolyDocs CI checks run automatically on every deployment to catch quality issues before they reach your readers. Two checks are available:

Broken Link Checker -- Detects internal and external links that return errors
Prose Linter -- Validates grammar, spelling, and style using Vale

Each check can be set to off, warning (report issues but allow deployment), or blocking (fail the deployment if issues are found).

Check Types

Broken Links

Scans all internal and external links in your documentation and reports any that return 404 or other error status codes.

Prose Linter

Runs Vale-based style and grammar checks using configurable style packages and custom vocabulary lists.

Configuring Checks

Dashboard

Open CI Checks settings

Navigate to Settings > CI Checks in your project dashboard.

Set severity for Broken Links

Choose Off, Warning, or Blocking for the broken link checker.

Set severity for Prose Linter

Choose Off, Warning, or Blocking for the prose linter.

Configure prose linter options

Select a style package and add custom vocabulary words.

Save

Click Save to apply changes. New checks run on the next deployment.

docs.json

You can also configure CI checks in your docs.json:

json
{  "ciChecks": {    "brokenLinks": {      "level": "warning",      "externalLinks": true    },    "vale": {      "level": "blocking",      "stylePackage": "Google",      "vocab": {        "accept": ["HolyDocs", "MDX", "OpenAPI", "Cloudflare"],        "reject": ["irregardless", "synergize"]      }    }  }}

Severity Levels

Level	Behavior	GitHub Status Check
Off	Check does not run	No status posted
Warning	Issues reported but deployment succeeds	Posts a neutral/warning status
Blocking	Deployment fails if any issues are found	Posts a failure status

Start with Warning severity to understand the current state of your docs. Once you've resolved existing issues, switch to Blocking to prevent regressions.

Broken Link Checker

The broken link checker validates every link in your documentation:

What Gets Checked

Link Type	Example	Checked
Internal page links	`[Guide](/quickstart)`	Always
Internal anchor links	`[Section](#overview)`	Always
External URLs	`[GitHub](https://github.com)`	When `externalLinks` is enabled
Image sources	`![Logo](/images/logo.svg)`	Always
Card hrefs	`<Card href="/api">`	Always

External Link Checking

External link checking is optional because external sites may rate-limit or block automated requests. Enable it when you want thorough validation:

json
{  "ciChecks": {    "brokenLinks": {      "level": "warning",      "externalLinks": true    }  }}

External link checks use a 10-second timeout per URL and follow up to 3 redirects. Links that time out are reported as warnings, not errors.

Broken Link Results

Each broken link issue includes:

Field	Description
`file`	The MDX file containing the broken link
`line`	Line number where the link appears
`severity`	`error` for 404s, `warning` for timeouts and 5xx
`message`	Description of the issue (e.g., "404 Not Found")
`suggestion`	Auto-suggested fix when a similar valid page exists

Prose Linter (Vale)

The prose linter uses Vale to check your documentation for grammar, spelling, and style issues.

Style Packages

Two style packages are available:

Based on the Google Developer Documentation Style Guide. Enforces clear, concise technical writing:

Use active voice
Avoid jargon and overly complex sentences
Prefer present tense
Use second person ("you") instead of third person

json
{ "valeStylePackage": "Google" }

Based on the write-good linter. Lighter-touch checks focused on common writing pitfalls:

Flag passive voice
Detect weasel words
Identify unnecessarily complex words
Catch cliches

json
{ "valeStylePackage": "write-good" }

Custom Vocabulary

Add words that are specific to your product or industry to prevent false positives:

json
{  "ciChecks": {    "vale": {      "vocab": {        "accept": ["HolyDocs", "Kubernetes", "OAuth", "GraphQL", "WebSocket"],        "reject": ["irregardless", "synergize", "utilize"]      }    }  }}

List	Purpose	Effect
Accept	Words the linter should recognize as correct	Suppresses spelling warnings for these terms
Reject	Words that should never appear in your docs	Generates an error whenever these terms are used

You can add up to 500 words to each list.

Prose Linter Results

Each prose issue includes:

Field	Description
`file`	The MDX file with the issue
`line`	Line number
`column`	Column position
`severity`	`error`, `warning`, or `info`
`message`	Description of the style issue
`rule`	The Vale rule that triggered (e.g., `Google.Passive`)
`suggestion`	Suggested replacement text (when available)

Viewing Check Results

Dashboard

Check results appear on the Deployments page next to each deployment. Click a deployment to see the full results:

Passed (green) -- No issues found
Warnings (yellow) -- Issues found but deployment succeeded
Failed (red) -- Blocking issues prevented deployment

Each result lists individual issues with file, line, and severity. Click an issue to jump to the relevant line in the editor.

GitHub Status Checks

When your project is connected to GitHub, CI check results are posted as commit status checks on the pull request:

holydocs/broken-links -- Broken link check status
holydocs/prose-lint -- Prose linter status

These integrate with GitHub's required status checks, so you can enforce documentation quality in your merge rules.

API

Retrieve check results programmatically:

bash
curl "https://api.holydocs.com/api/v1/projects/PROJECT_ID/ci-checks/results?deploymentId=DEPLOY_ID" \  -H "Authorization: Bearer YOUR_API_KEY"

Response:

json
{  "data": [    {      "id": "chk_abc123",      "checkType": "broken-links",      "status": "warning",      "issueCount": 3,      "issues": [        {          "file": "api/authentication.mdx",          "line": 42,          "severity": "error",          "message": "Internal link '/api/tokens' resolves to 404",          "suggestion": "Did you mean '/api/auth-tokens'?"        }      ],      "createdAt": 1711929600000,      "completedAt": 1711929615000    }  ]}

Running Checks Manually

Trigger a check run without deploying using the CLI:

bash
holydocs check --broken-links --vale

This runs the same checks locally against your current docs directory and prints results to the terminal. Useful for catching issues before pushing.

The holydocs check command uses the same CI check settings from your docs.json. Pass --level blocking to override the severity level locally.

Best Practices

Fix existing issues before enabling blocking mode

Enable checks as Warning first, resolve the backlog of issues, then switch to Blocking to prevent new ones.

Add product terms to the accept list early

Your product name, API terms, and industry jargon will generate false positives. Add them to the accept vocabulary from the start.

Use GitHub required status checks

Combine HolyDocs CI checks with GitHub's required status check feature to prevent merging PRs that break documentation quality.

Run checks locally before pushing

Use holydocs check in your local dev workflow or add it to a pre-commit hook to catch issues before they reach CI.

Was this page helpful?

Previous Subfolder Hosting

Next Preview Access