FAQ

Quick answers to the questions contributors ask most when a manni meta check goes red. Each one links to the page that covers it in full. If you’re staring at a failing check right now, start with Fix a failing check. This page is for the “wait, but what about…” follow-ups.

What if a file has no frontmatter at all?

It still fails, as long as the schema requires any field. A file with no frontmatter block reads as empty metadata. So a schema that requires type, as the built-in default does, reports the same “must have required property ‘type’” error. It is the same error you would get for a file that simply left type out.

So an empty or frontmatter-less file earns no free pass. It’s the maximally failing case. If you expected the file to have metadata, the usual cause is a missing opening --- fence, or content sitting above the block. See No frontmatter at all for the fix.

Which schema validated my file, and why did this rule fire?

Every error line ends with the schema that produced it, in brackets. For example [google:okf:0.1]. That’s the schema whose rule you tripped. If you’re surprised by which schema applied, manni meta picks it through a fixed precedence chain. A --schema flag wins over a $schema key in your file. That wins over config overrides, then config schemas, then the built-in default.

The first source that yields a schema wins, and lower sources are ignored for that file. Say your repo’s config assigns a strict schema to /api/**, and your file is under /api. That’s the rule that fired, even if you never set anything in the file itself.

How schema resolution worksThe full precedence chain, the three reference kinds, and how each error is tagged with its schema.

Can I validate just one field?

No. validate checks a file against whole schemas, not individual fields. There is no “validate only type” mode. What you can do is narrow which schema applies (via $schema, config overrides, or --schema) so that only the rules you care about run.

If your goal is just to read a field’s value rather than validate it, that’s a different command. get extracts named field values without validating anything.

manni meta get type docs/guide.md

See the validate and get references for each command’s full surface.

How do I validate content coming from stdin?

Pass - as the path and tell manni meta which format to use with --as, since there’s no filename extension to detect from:

cat page.md | manni meta validate - --as markdown

--as takes an extractor name (markdown, mdx, asciidoc, and so on). The same pattern works for get. Without --as, stdin is an error.

CLI reference: shared input modelHow paths, stdin, and --as work the same way across validate and get.

How do I check only Markdown and skip my other formats?

Use --ext to restrict which extensions directory and glob walks pick up:

manni meta validate docs/ --ext md

This walks docs/ but considers only .md files, leaving .mdx, .adoc, and the rest untouched. Pass a comma-separated list for more than one, as in --ext md,mdx.

Note

--ext filters directory and glob expansion. An explicit file path you pass directly is always validated, regardless of its extension.

What exit code does CI see?

One of three:

Code	Meaning
0	Every file passed. The check is green.
1	One or more files failed validation, from a missing or malformed field. The red check you’re here to fix.
2	An operational error, where manni meta couldn’t run the check at all. That covers a missing or unreadable schema, an unsupported file type, or no files to validate. The message goes to stderr, prefixed manni:.

A 1 means fix your document. A 2 means fix the setup, not the content. CI gates on this code, so the distinction matters when you read a raw log.

Output formats & exit codesThe exact 0/1/2 contract, plus the pretty, JSON, GitHub, SARIF, and JUnit output shapes.

Does manni meta check my prose or page content?

No. manni meta validates the presence and format of metadata, the fields in your frontmatter, and nothing about the body of the document. It won’t flag spelling, broken links, tone, or anything in the prose. A red check always points at a frontmatter field, never at your writing.

How do I exclude drafts from validation?

Exclude them by glob, in one of two places, and the difference matters.

On the command line, --exclude filters whatever this run walks:

manni meta validate docs/ --exclude "**/drafts/**"

It is repeatable and merges with the default ignores (node_modules, .git).

In config, exclude: belongs to a collection and decides what that collection contains:

manni.config.yaml

collections:
  - name: pages
    paths: ["docs/**/*.md"]
    exclude: ["**/drafts/**"]

A bare manni meta validate reads the collections, so the drafts are skipped every run, locally and in CI.

A collection's exclude does not filter a path you type

The two are not interchangeable. exclude: shapes the collection, so it applies when a run reads the collections. It does not filter a path given on the command line: manni meta validate docs/ walks exactly docs/, drafts included, because you named that directory. Use --exclude when you are naming paths yourself.

Before 1.0.0 the config key filtered every run, typed paths included. It moved onto the collection with proposal 0041. Once a repository declares several document sets, there is no principled way to choose whose exclusions apply to a directory you typed.

Configuration referenceCollections, their paths and exclude keys, schemas, and overrides, with how config merges with CLI flags.

Still stuck?

Your error may not match anything here or on the fix-it page. The Reference shelf documents every flag, output format, exit code, and resolution rule in full.

Read & fix a validation failureDecode the error line, map it to a field and line, fix it, and confirm green locally.