@hawkeyexl/manni

中文文档
4.28.0发布于 2026/11/02MITTypeScriptES Module构建来源已验证近 30 天下载 7458

One command line for documentation that is meant to be checked. manni meta validates the presence and format of document metadata (Markdown frontmatter and more) against JSON Schema, built for CI. Formerly docmeta.

原始使用文档
文档目录9 节
  1. Install
  2. Coming from docmeta?
  3. Quick start
  4. Run it in CI
  5. Fill in what's missing
  6. Supported formats
  7. Documentation
  8. Contributing
  9. License

manni

One command line for documentation that is meant to be checked. manni meta validates the presence and format of document metadata against JSON Schema, built for CI. It was published as docmeta up to 4.13.1; see Coming from docmeta.

npm CI node license

manni meta checks the metadata in your documents (Markdown frontmatter and more) against one or more JSON Schemas. It verifies that required fields are present and correctly formatted: a type, an ISO 8601 timestamp, a URI resource. It does not judge prose quality. It ships with 45 built-in schemas. They cover content vocabularies such as the Open Knowledge Format (OKF), Diátaxis, The Good Docs Project, and the Seven-Action model. They also cover the front matter contracts of site generators such as Docusaurus 3.10, Hugo, Jekyll, and MkDocs Material. Twenty-six are manni's own metadata vocabularies and their strict overlays. Run manni meta schemas for the full list. It follows clig.dev conventions and returns a nonzero exit code (plus optional GitHub annotations) when validation fails.

It can also fill in the metadata that is missing, so adopting a standard on an existing docset is not a data-entry project.

Install

npm install -g @hawkeyexl/manni
# or run it without installing:
npx @hawkeyexl/manni meta validate "**/*.md"

Requires Node.js 24 or later.

Once a repository sets up a few of the tools, manni status says which are in play and manni check runs all of them as one gate. In Claude Code, the manni plugin runs the same check after each edit an agent makes. Install it with claude plugin marketplace add hawkeyexl/manni, then claude plugin install manni@manni. See Gate every check and Keep an agent's docs green.

Coming from docmeta?

The metadata tool used to be the whole package. Three things changed:

  • The command. docmeta validate … is now manni meta validate …. The package still installs a docmeta bin that runs the same program, so existing scripts keep working while you move them.
  • The config file. manni.config.yaml, shared by every tool in the family, with the metadata tool's keys under meta:. A docmeta.config.yaml is still read, with a warning.
  • The GitHub Action. uses: hawkeyexl/manni@v4 now runs manni check, every check the repository has set up. Add command: meta validate to run the metadata check alone, with the inputs it took before.

The rename changed nothing else. The exit codes, the output formats and the programmatic API carry over, and so do the built-in schemas and their published URLs. The old …/docmeta/schemas/ URLs stay served and resolve offline.

Quick start

Point manni meta validate at a file, a directory (walked recursively), or a glob. With no --schema, it validates against the default set of eleven built-in schemas. The OKF schema requires type, and the manni core vocabulary requires title and description. passo-uno:seven-action:1.0 and the other eight manni vocabularies check a field only when a page carries it.

manni meta validate docs/intro.md
✗ docs/intro.md
    (root)      must have required property 'type'                  [google:okf:0.1]
    (root)      must have required property 'description'           [manni:core:1.0.0]
    /timestamp  must match format "date-time"             (line 9)  [google:okf:0.1]

1 file checked, 0 passed, 1 failed, 0 errors

A clean run exits 0; validation failures exit 1; operational errors (no input, unknown schema, parse error) exit 2.

A config's meta.schemas add to the default set, and meta.defaults: false makes them replace it. meta.register names your own schemas by their $id, and meta.strict: true stacks each strict version beside its base. The configuration reference has every key.

Run it in CI

On GitHub Actions, use the packaged action. It sets up Node, pins the CLI, and runs manni check, every check the repository has set up, as inline PR annotations:

- uses: actions/checkout@v7
  with:
    fetch-depth: 0
- uses: hawkeyexl/manni@v4

command: runs any one manni command instead, such as meta validate. Every input is in the Action reference. Other platforms run the CLI directly. The CI recipes cover GitLab CI, Jenkins, and the rest.

To catch problems before they reach CI, manni meta publishes a pre-commit hook. The whole configuration is three lines, and the file-matching pattern is derived from the extensions manni meta actually reads rather than hand-written:

repos:
  - repo: https://github.com/hawkeyexl/manni
    rev: v4.28.0
    hooks:
      - id: manni-meta

Fill in what's missing

manni meta fill infers the metadata properties your schema asks for but a page does not carry, and writes back the values it is confident about. It is the fast way to clear the backlog on a repo that has never enforced metadata.

manni meta fill docs/ --dry-run     # preview; writes nothing
manni meta fill docs/               # apply
✓ docs/intro.md
    /description  A tour of the CLI and its four commands.  0.91
    below 0.7: /resource 0.38

anthropic/claude-sonnet-4-5 · Threshold 0.7 · 1 file · 1 field written · 1 skipped

Confidence is the last gate, not the only one. A proposal must first satisfy the target property's own subschema. It must name a property your schema declares, and it must leave the document still valid after the merge. Only then does --confidence (default 0.7) apply. Values below it are skipped and reported by name. They are never written with a caveat, and the score itself never reaches your document.

fill writes in place by default, so run it on a clean tree and review the diff.

It picks an LLM provider by detecting one. The order is ANTHROPIC_API_KEY, then OPENAI_API_KEY, then a claude CLI that runs, then a local model that needs no credentials at all. That means it works with whatever you have, and it reports which provider it used. Pass --provider to pin one. That is worth doing in CI. Left to detect, a runner that loses its key falls back to the local model, and downloads it rather than failing the build.

Pass --local when the document must not leave the machine. It runs inference on-device with llama-cpp and overrides any provider the config names, saying which one it set aside. It never picks the claude CLI, which runs locally while its inference does not. See the fill reference for every flag and for what the local fallback costs.

Supported formats

Markdown, MDX, AsciiDoc, reStructuredText, XML (including DITA topics and maps), and HTML. Run manni meta schemas to list the built-in schemas, every supported format, and which formats fill can write back to.

fill writes to all of them. It splices the exact character range of the value rather than re-serializing the document. Comments, entity spellings, attribute order, indentation, and a DOCTYPE all survive untouched.

Documentation

Full guides, recipes, and reference live on the documentation site:

https://hawkeyexl.github.io/manni/meta/**

TrackWhat it covers
Get startedInstall and run your first validation.
Set up validationStand up validation for a repo: manni.config.yaml, per-folder schema overrides.
Run it in CIGitHub Actions and other CI recipes, exit codes, and PR annotations.
Define & evolve schemasAuthor a schema, wire up resolution, and version it without breaking the build.
ReferenceEvery CLI flag, Action input, config key, the schema-resolution precedence chain, and output formats.

Contributing

Contributions are welcome. See CONTRIBUTING.md for dev setup, the test loop, and how to add support for a new input format.

License

MIT

版本与发布记录

@hawkeyexl/manni 共发布 96 个版本,首次发布于 2026/09/06;过去 12 个月发布了 96 个版本。最新版本附带 npm provenance 构建来源证明,可追溯到公开的 CI 构建记录。

版本发布日期距今
4.28.0latest2026/11/0215 天前
4.27.22026/10/2919 天前
4.27.12026/10/2919 天前
4.27.02026/10/2919 天前
4.26.22026/10/2820 天前
4.26.12026/10/2523 天前

其他发布通道:cite-follow-moved-sources → 2.9.0-cite-follow-moved-sources.2,cite-marker-ids → 2.10.0-cite-marker-ids.1。

关于 @hawkeyexl/manni 的常见问题

@hawkeyexl/manni 是什么?

One command line for documentation that is meant to be checked. manni meta validates the presence and format of document metadata (Markdown frontmatter and more) against JSON Schema, built for CI. Formerly docmeta.

如何安装 @hawkeyexl/manni?

在项目目录运行 npm install @hawkeyexl/manni,或使用 pnpm add / yarn add / bun add。它还提供命令行工具 manni、docmeta,可以用 npx manni 直接运行。

@hawkeyexl/manni 支持 TypeScript 吗?

支持。包内自带 TypeScript 类型声明(package.json 声明了 types 入口),安装后即可获得类型提示,无需再安装 @types 包。

@hawkeyexl/manni 支持 ESM 还是 CommonJS?

以 ES Module 形式发布,推荐使用 import 引入。在 CommonJS 项目中,Node.js 20.19+ / 22.12+ 可以直接 require() 不含顶层 await 的 ES Module,更早的版本需要改用动态 import()。

@hawkeyexl/manni 需要什么版本的 Node.js?

package.json 的 engines 字段要求 Node.js >=24。版本不符时 npm 默认只给出警告,开启 engine-strict 后会拒绝安装。

@hawkeyexl/manni 可以商用吗?

@hawkeyexl/manni 使用 MIT 许可。宽松许可:允许商业使用、修改和再分发,通常只需在分发时保留原版权与许可声明。以上为概括,不构成法律意见,请以许可原文为准。

@hawkeyexl/manni 的下载量有多少?

根据 npm 官方下载统计,@hawkeyexl/manni 在 2026/10/18 – 2026/11/16 这 30 天内被下载 7,458 次,日均约 249 次。下载量会把 CI 构建、镜像同步和作为其他包依赖的安装一并计入,适合横向比较热度,不能直接等同于使用人数。

@hawkeyexl/manni 还在维护吗?

最新版本 4.28.0 发布于 2026/11/02(15 天前);至今共发布 96 个版本,其中过去 12 个月发布了 96 个;首次发布于 2026/09/06。发布频率只是参考信号:功能稳定的工具可能很少需要更新,建议结合源码仓库的 issue 和提交记录判断。