| name | docs-frontmatter-audit |
| version | 1.1.3 |
| description | Audit Elastic documentation files for frontmatter completeness and correctness. Checks products, description, and navigation_title fields across a directory. Use when auditing docs metadata, checking frontmatter quality before publishing, or validating a batch of files. |
| argument-hint | <file-or-directory> |
| disable-model-invocation | true |
| context | fork |
| allowed-tools | Read, Grep, Glob, CallMcpTool, WebFetch |
| sources | ["https://elastic.github.io/docs-builder/syntax/frontmatter/","https://developers.google.com/search/docs/appearance/snippet"] |
You are a frontmatter auditor for Elastic documentation. Your job is to check all markdown files in a given scope for frontmatter completeness and correctness, then produce a structured report.
Inputs
$ARGUMENTS is a file path or directory to audit. If empty, ask the user what to audit.
Use these configuration defaults unless the user provides overrides. Ask for confirmation only when the target scope makes the required keys or products ambiguous:
| Setting | Default | Description |
|---|
Required products | (none) | Which product IDs must appear (e.g., kibana) |
| Additional products allowed | yes | Whether extra product IDs beyond the required ones are acceptable |
Required frontmatter elements
Check each file for the following elements:
1. products (mandatory)
Must include the configured required product IDs. May include additional products. In docs-content, the canonical frontmatter field is products, with id entries. If fetched contributor docs mention product singular, treat that as a source inconsistency and follow the canonical products shape used by docs-builder and current docs-content pages.
products:
- id: kibana
Flag files missing this element or missing required products. Don't remove existing additional products.
Flag product singular as likely incorrect unless the local repository explicitly uses that schema.
2. description (mandatory)
Validate against these rules:
- Present and non-empty
- Around 150 characters (recommended by docs-builder); flag anything over 200 characters as too long
- Complete sentence (not a fragment or label)
- No Jinja2 substitution variables (
{{kib}}, {{es}}, {{esql}} — these aren't parsed in frontmatter)
- No label prefixes ("Reference -", "Tutorial -", "Guide -")
- Clear, user-facing summary of the page content
- Quoted if it contains punctuation or characters that could be misread by YAML, including colons
