Stand up metadata validation for your repo

You own a docs repo, and you want every page to carry correct, complete frontmatter so search and your content catalog stay trustworthy. This guide threads the whole setup together: install docmeta, validate a folder by hand, capture your rules in a docmeta.config.yaml, then land a CI gate that runs the same check on every pull request.

By the end you will have a committed config file and a check that fails the build when a doc is missing required metadata.

What docmeta checks

docmeta validates the presence and format of your frontmatter against JSON Schema — that type exists, that timestamp is a real date-time, that resource is a URI. It does not review your prose. If a field is required by your schema and missing, the run fails.

Before you start

• Node.js 24 or newer. Check with node --version.
• A docs repo with frontmatter you want to enforce. The examples below assume Markdown under a docs/ folder, but docmeta handles other formats too — see the supported formats reference.

Stand it up

1. Validate a folder, no setup required.

   Run docmeta against a directory with npx. No install, no config — this tells you where you stand today.

   npx docmeta validate docs/

   docmeta walks docs/, finds every supported file, and validates each one against the built-in google:okf:0.1 schema, which requires a type field. You will see a pass/fail line per file and a summary. A nonzero exit code means at least one file failed.

   Tip

   To check a single file instead, pass its path: npx docmeta validate docs/intro.md. Explicit file arguments are always validated, regardless of extension filters.

2. Add a docmeta.config.yaml at your repo root.

   The command above works, but you do not want to retype paths and schemas every run — and CI needs a stored definition of what “valid” means for your repo. Capture it in a config file so a bare docmeta validate knows what to do.

   docmeta.config.yaml

   # Default targets when no paths are passed on the command line.
   paths:
     - "docs/**/*.md"
   
   # The schema set every matched file must satisfy.
   schemas:
     - google:okf:0.1

   paths is the fallback docmeta uses when you do not name files on the command line. schemas is the set each file is validated against — every file must satisfy every schema you list.

   Create your docmeta.config.yamlEvery config key explained — paths, exclude, schemas, and overrides — with a complete worked example.

3. Run the stored configuration.

   With the config committed, you no longer pass paths or schemas. docmeta discovers docmeta.config.yaml in the current directory and uses its paths and schemas.

   npx docmeta validate

   This is the exact command CI will run. Confirm it reports what you expect locally before you wire it up.

   Caution

   If you run a bare docmeta validate with no config file and no paths, docmeta exits with code 2 and the message No files to validate. That is an operational error, not a silent pass — it means docmeta had nothing to do.

4. Land the CI gate.

   The same npx docmeta validate command becomes a pull-request gate. docmeta exits 0 when everything passes and 1 when a file fails validation, so any CI system can use it as a pass/fail step. The --format github flag turns failures into inline annotations on the PR diff.

   npx -y docmeta validate --format github

   The full recipe — workflow file, exit-code contract, and annotation behavior — lives in the CI track. Copy the ready-made recipe there rather than assembling your own.

   Run it in CIReady-made recipes for GitHub Actions, GitLab CI, Jenkins, and pre-commit, plus the exit-code and annotation contract.

What you have now

A committed docmeta.config.yaml that defines which files to check and which schema they must satisfy, plus a CI step that runs the same check on every pull request and fails the build on bad metadata. New contributors get the same enforcement you do, without any review fatigue on your side.

Where to go next

Apply different schemas to different foldersRequire stricter metadata for /api than for /guides using config overrides.

Author a schema for your standardMove beyond the built-in OKF schema and encode your own required and recommended fields.