GitHub Action reference

The packaged Action runs the same npm package the CLI does. It sets up Node, fetches manni meta, and shells out to manni meta 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@v7
- uses: hawkeyexl/manni@v2
  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. Space-separated, or one per line. Use lines for any path containing a space. Unset, it falls back to the collections in your config, which is every declared one unless args narrows the run with --collection.
schema	none	One -s per entry.
config	none	-c
format	github	--format. One of pretty, json, github, sarif, junit.
version	latest	The npm version range fetched, as @hawkeyexl/manni@<version>. Also accepts a path or tarball.
args	none	Appended verbatim after everything else, for anything the inputs above do not cover. --collection reaches the Action this way.
node-version	24	Passed to actions/setup-node. manni meta 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 manni meta 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/manni@v2
  with:
    paths: |
      docs/**/*.md
      guides/my notes/*.mdx
    args: |
      --exclude
      *.draft.md

Globs reach manni meta unexpanded

A paths value like docs/**/*.md is passed through as that string. The Action disables shell globbing deliberately. manni meta 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 manni meta’s. It would do so silently, and differently depending on the working directory.

Selecting a collection

There is no collection input. --collection reaches the Action through args, the documented escape hatch for every flag the inputs above do not name:

- uses: hawkeyexl/manni@v2
  with:
    args: --collection guides

The flag repeats rather than splitting on commas, so two collections are two occurrences on the same line:

- uses: hawkeyexl/manni@v2
  with:
    args: --collection guides --collection blog

Leave paths unset when you do this. --collection selects from the config, so it cannot be combined with positional paths. A workflow that sets both fails the step with exit 2. The message is --collection selects a configured collection; it cannot be combined with paths. With neither, the run covers every declared collection, which is what the paths-less form above already did.

Outputs

Output	Value
exit-code	manni meta’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: manni
  uses: hawkeyexl/manni@v2
  continue-on-error: true
  with:
    paths: "docs/**/*.md"
- if: steps.manni.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

@vN is a moving tag. On each stable release, the release job moves it to the newest release of that major. Pin a full tag such as uses: hawkeyexl/manni@v2.2.0 instead when you want an immutable Action. That is the usual trade between getting fixes automatically and knowing exactly what runs.

The Action tag chooses the Action’s code. The version input chooses the CLI it runs, and defaults to latest, the newest published CLI. Set version to a major such as 2, or to an exact version, when you want a reproducible CLI.

The equivalent by hand

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

- uses: actions/checkout@v7
- uses: actions/setup-node@v6
  with:
    node-version: 24
- run: npx -y @hawkeyexl/manni meta 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 CLI version it fetches, the --format github default, and the Node version. So changing the recommended invocation is a tag move, rather than an edit in every repository.