> ## Documentation Index > Fetch the complete documentation index at: https://docs.holydocs.com/llms.txt > Use this file to discover all available pages before exploring further. # 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 | `` | 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](https://vale.sh) to check your documentation for grammar, spelling, and style issues. ### Style Packages Two style packages are available: **Google Developer Docs** Based on the [Google Developer Documentation Style Guide](https://developers.google.com/style). 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" } ``` **Write Good** Based on the [write-good](https://github.com/btford/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.