GitHub Action reference

The packaged Action runs the same npm package the CLI does. It sets up Node, fetches docmeta, and shells out to docmeta validate. Nothing it does is unavailable from the CLI. It exists so the invocation lives in one place, instead of being copy-pasted into every repository that wants it.

- uses: actions/checkout@v4
- uses: hawkeyexl/docmeta@v4
  with:
    paths: "docs/**/*.md"

Inputs

Every input is optional. An input left unset contributes nothing to the command line, and it does not become an empty flag.

Input	Default	Maps to
paths	none	Positional paths. Files, directories, or globs. Falls back to paths: in your config when unset.
schema	none	One -s per entry.
config	none	-c
format	github	--format. One of pretty, json, github, sarif, junit.
version	4	The npm version range fetched, as docmeta@<version>. Also accepts a path or tarball.
args	none	Appended verbatim after everything else, for anything the inputs above do not cover.
node-version	24	Passed to actions/setup-node. docmeta needs 24 or newer.

Quotes are not shell-processed

paths and args accept several values either space-separated on one line or one per line. On a single line the value is split on whitespace only, and shell quoting is not interpreted. So args: --exclude "*.draft.md" reaches docmeta with the quote marks still inside the pattern, and the exclusion silently matches nothing.

Use one item per line whenever a value contains a space. The Action emits a workflow warning if it sees a quote character in a single-line value.

- uses: hawkeyexl/docmeta@v4
  with:
    paths: |
      docs/**/*.md
      guides/my notes/*.mdx
    args: |
      --exclude
      *.draft.md

Globs reach docmeta unexpanded

A paths value like docs/**/*.md is passed through as that string. The Action disables shell globbing deliberately. docmeta applies its own extension filtering and gitignore rules. Letting the runner expand the pattern first would substitute the shell’s view of the tree for docmeta’s. It would do so silently, and differently depending on the working directory.

Outputs

Output	Value
exit-code	docmeta’s exit code. 0 clean, 1 validation failures, 2 operational or usage error.

exit-code is only observable with continue-on-error: true. Without it a non-zero code has already failed the step, so there is nothing left to read:

- id: docmeta
  uses: hawkeyexl/docmeta@v4
  continue-on-error: true
  with:
    paths: "docs/**/*.md"
- if: steps.docmeta.outputs.exit-code == '1'
  run: echo "Metadata problems found, but not blocking this job."

Why there is no flag-per-input

The Action deliberately stops at seven inputs. Enumerating every CLI flag would create a second command surface to keep in step with the first, and args already reaches anything not listed. The inputs that do exist are checked against action.yml by npm run docs:check-action, so this table cannot drift from the Action itself.

Versioning

@v4 is a moving tag that tracks the newest 4.x release; it is force-updated by the release job on each stable release. Pin @v4.1.2 instead when you want an immutable reference. That is the usual trade between getting fixes automatically and knowing exactly what runs.

The version input is separate, and controls which npm version the Action fetches rather than which Action code runs. Leave it unset unless you are pinning the CLI independently of the Action.

The equivalent by hand

The Action replaces this, which remains supported and is what examples/docmeta.yml shows:

- uses: actions/checkout@v4
- uses: actions/setup-node@v4
  with:
    node-version: 24
- run: npx -y docmeta@4 validate "docs/**/*.md" --format github

Use the hand-written form on a runner that cannot use a composite action, or when you need to control the Node setup yourself. Everything else moves inside the Action, including the pin, the --format github default, and the Node version. So changing the recommended invocation is a tag move, rather than an edit in every repository.