How to Add a Pre-Commit Quality Gate to Your Docs

In software development, any code that is pushed doesn't go straight to production; instead, it passes through checks such as tests, linters, and CI/CD builds, and those checks stop the change if something is wrong. Most of us call this a quality gate, and it exists so that people don't have to catch every small mistake manually.

In the technical documentation space, most documentation teams don't have anything like this. We write the page, open a pull request, and wait for someone to review it, often a few days later. If the reviewer spots a wrong term or a broken link, we fix it, push again, and wait again. On a busy release week, some of those problems slip through and reach readers.

So, I created my company's docs repo to catch these problems before a commit was even made. To do this, I built a pre-commit quality gate, as we do in SDLC. In this article, I'll explain what it is and show you how to set up the first check.

By the way, this knowledge is explained and shared properly in this book; you must try it AI Native Technical Writer

What is a docs quality gate?

A quality gate is a set of checks that runs automatically at a fixed point and stops the change if a check fails. For documentation, the best point is right before a commit, because the file is still open in your editor and fixing a problem takes seconds.

The checks themselves are ordinary tools. A linter such as Vale checks, your terminology and your docs platform's validation command checks that the site still builds. A link checker finds broken links and anchors. Small scripts can also compare the package versions you've published with what your changelog says.

Why review time is too late to catch docs problems

The later a problem is found, the more it costs to fix. At commit time, a wrong term takes a few seconds to correct.

• In review, the same problem turns into a comment, a new commit, and another round of waiting. In staging, it pulls in someone who didn't write the page.

And if a reader finds it first, it becomes a support ticket and a small loss of trust in your docs. The cost of fixing a docs problem grows at each stage, from seconds at commit time to a support ticket once a reader finds it

Moving each check to the earliest point where it can run is what people mean by "shift left." For docs, that point is the commit.

What does a pre-commit checklist look like?

On my docs platform, every check reports into a single checklist, so I see all the problems at once instead of one at a time. Here's what it looks like when something fails:

Pre-commit checklist
────────────────────
Git:        3 staged files (2 MDX, 1 changelog)
pkg drift:  DRIFT - @example/web-sdk 2.4.0 not in changelog/web-sdk.mdx
Vale:       2 findings - "log in to" in how-to/polling-and-retries.mdx (2x)
Style:      OK
Validate:   OK
────────────────────
Blocked:    yes - package drift
Next:       fix · ignore and commit (explicit skip flag) · cancel

The last two lines matter most. The gate doesn't decide for me. Instead, it shows what's wrong and gives me three choices:

• fix the problem
• commit anyway with an explicit skip flag that leaves a record
• cancel

As a tech writer, I always make the final call.

How to lint only the files you're committing?

The easiest check to start with is terminology. Vale reads its rules from YAML files, and a substitution rule maps the words you don't want to the words you do:

yaml

extends: substitution
message: "Use '%s' instead of '%s'."
level: error
ignorecase: true
swap:
  log in to: sign in to
  e-mail: email

To keep the check fast, run Vale only on the MDX files you've staged, not on the whole site:

git diff --cached --name-only --diff-filter=ACM -- '*.mdx' | xargs -r vale

This command lists the staged MDX files that were added, copied, or modified, and passes them to Vale. When no MDX files are staged, the -r option stops Vale from running at all. Run it from a pre-commit hook, and every commit gets a terminology check without anyone having to remember it.

Adding more checks to your docs quality gate

Once terminology linting is running, the next checks are easier to build, because each one follows the same pattern. It runs a command on the staged files, reports the result in the checklist, and blocks the commit if something fails. In my repo, the gate also compares published package versions with the changelog. It confirms that diagrams were rebuilt from their source after an edit, and it checks that the index coding agents read still matches the pages.

Each of these took some trial and error to get right, especially deciding when a check should block a commit and when it should only show a warning.

I've explained all of them in my book, The AI-Native Technical Writer, along with the script that combines every check into the single checklist you saw above.

The book also includes a starter kit of eight docs automations you can adapt to your own repo.

A good place to start is the terminology check from this article. Add it this week, and keep a note of every problem it catches before review. After a couple of weeks, you'll know which check to add next.