---
title: Validate documentation in CI
description: Catch broken links, invalid OpenAPI specifications, and content issues before they ship.
url: https://pr-7-a9c4e9fe1b6c.thally.app/guides/ci-checks
---

# Validate documentation in CI

Catch broken links, invalid OpenAPI specifications, and content issues before they ship.

`thally check` lints your docs and, with `--ci`, fails a pull request when something
is broken, so CI can stop the change before it reaches production.

## What it checks

- **Content** — orphan pages (not in `docs.json`), missing `title`/`description`, thin pages, pages in nav with no file.
- **Internal links & anchors** — every `/page` link resolves to a real page, and every `#heading` anchor exists. Links inside code blocks are ignored (they're examples).
- **OpenAPI** — your API spec parses and has the required structure (`openapi` version, `info`, valid `paths`).

> **Note:**
External links are skipped by default for deterministic, network-free CI. Pass
`--external` to HEAD-check them too.

## Run it

```bash
thally check           # human-readable report
thally check --fix     # auto-add orphan pages to navigation
thally check --ci      # GitHub annotations + non-zero exit on errors
```

No global install? `npx create-thally-docs check --ci .` does the same.

## In GitHub Actions

New projects scaffold a `.github/workflows/thally-check.yml` that runs on every pull
request and annotates broken links and invalid specs inline on the diff:

```yaml
- name: thally check
  run: npx --yes create-thally-docs@latest check --ci .
```

Warnings (orphans, thin pages) are reported but don't fail the build; **errors**
(broken links, missing pages, invalid OpenAPI) do.