frontmatter-audit

Name: frontmatter-audit
Author: elastic

71stars10forks

How to install frontmatter-audit?

elastic/elastic-docs-skills/frontmatter-audit

$npx -y skills add elastic/elastic-docs-skills --skill frontmatter-audit

Installs into the current project.

Summary

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.

Files · 1

View on GitHub

SKILL.md

1	<!-- Copyright Elasticsearch B.V. and/or licensed to Elasticsearch B.V. under one
2	or more contributor license agreements. See the NOTICE file distributed with
3	this work for additional information regarding copyright
4	ownership. Elasticsearch B.V. licenses this file to you under
5	the Apache License, Version 2.0 (the "License"); you may
6	not use this file except in compliance with the License.
7	You may obtain a copy of the License at
8
9	http://www.apache.org/licenses/LICENSE-2.0
10
11	Unless required by applicable law or agreed to in writing,
12	software distributed under the License is distributed on an
13	"AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
14	KIND, either express or implied. See the License for the
15	specific language governing permissions and limitations
16	under the License. -->
17
18	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.
19
20	## Inputs
21
22	`$ARGUMENTS` is a file path or directory to audit. If empty, ask the user what to audit.
23
24	Use these configuration defaults unless the user provides overrides. Ask for confirmation only when the target scope makes the required keys or products ambiguous:
25
26	\| Setting \| Default \| Description \|
27	\|---------\|---------\|-------------\|
28	\| Required `products` \| (none) \| Which product IDs must appear (e.g., `kibana`) \|
29	\| Additional products allowed \| yes \| Whether extra product IDs beyond the required ones are acceptable \|
30
31	## Required frontmatter elements
32
33	Check each file for the following elements:
34
35	### 1. `products` (mandatory)
36
37	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.
38
39	```yaml
40	products:
41	- id: kibana
42	```
43
44	Flag files missing this element or missing required products. Don't remove existing additional products.
45	Flag `product` singular as likely incorrect unless the local repository explicitly uses that schema.
46
47	### 2. `description` (mandatory)
48
49	Validate against these rules:
50	- Present and non-empty
51	- Around 150 characters (recommended by docs-builder); flag anything over 200 characters as too long
52	- Complete sentence (not a fragment or label)
53	- No Jinja2 substitution variables (`{{kib}}`, `{{es}}`, `{{esql}}` — these aren't parsed in frontmatter)
54	- No label prefixes ("Reference -", "Tutorial -", "Guide -")
55	- Clear, user-facing summary of the page content
56	- Quoted if it contains punctuation or characters that could be misread by YAML, including colons
57
58	### 3. `navigation_title` (recommended)
59
60	Check if the H1 title exceeds ~50 characters. If so, flag that a `navigation_title` should be added.
61
62	```yaml
63	navigation_title: "Configure ML alerts"
64	```
65
66	### 4. `mapped_pages` (preserve)
67
68	If present, don't flag or suggest changes. If absent, don't suggest adding it.
69
70	## Execution
71
72	1. Glob for all `.md` files in the specified scope
73	2. Read the frontmatter of each file
74	3. Validate each element against the rules above
75	4. Read the H1 title to check length for `navigation_title`
76	5. Compile the report
77
78	## Report format
79
80	```
81	## Frontmatter audit: <scope>
82
83	Configuration:
84	- Required products: kibana
85	- Files scanned: N
86
87	### Issues found
88
89	#### Missing `products`
90	\| File \| Issue \|
91	\|------\|-------\|
92	\| path/to/file.md \| Missing `kibana` product \|
93
94	#### Invalid or missing `description`
95	\| File \| Issue \|
96	\|------\|-------\|
97	\| path/to/file.md \| Missing description \|
98	\| path/to/other.md \| Contains Jinja2 variables \|
99	\| path/to/third.md \| Exceeds 200 characters (247 chars); descriptions should usually be around 150 characters \|
100
101	#### Missing `navigation_title`
102	\| File \| H1 length \|
103	\|------\|-----------\|
104	\| path/to/file.md \| 63 chars \|
105
106	### Summary
107
108	- ✅ N files passed all checks
109	- ❌ N files have issues
110	- N missing products
111	- N invalid/missing description
112	- N missing navigation_title (recommended)
113	```
114
115	Group issues by type, not by file, so users can batch-fix related problems. Only include sections that have issues.

People who liked this also viewed

6 picks

Type

frontmatter-audit

71stars10forks

View on GitHub

How to install frontmatter-audit?

elastic/elastic-docs-skills/frontmatter-audit

$npx -y skills add elastic/elastic-docs-skills --skill frontmatter-audit

Installs into the current project.

Summary

Files · 1

View on GitHub

SKILL.md

1	<!-- Copyright Elasticsearch B.V. and/or licensed to Elasticsearch B.V. under one
2	or more contributor license agreements. See the NOTICE file distributed with
3	this work for additional information regarding copyright
4	ownership. Elasticsearch B.V. licenses this file to you under
5	the Apache License, Version 2.0 (the "License"); you may
6	not use this file except in compliance with the License.
7	You may obtain a copy of the License at
8
9	http://www.apache.org/licenses/LICENSE-2.0
10
11	Unless required by applicable law or agreed to in writing,
12	software distributed under the License is distributed on an
13	"AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
14	KIND, either express or implied. See the License for the
15	specific language governing permissions and limitations
16	under the License. -->
17
18	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.
19
20	## Inputs
21
22	`$ARGUMENTS` is a file path or directory to audit. If empty, ask the user what to audit.
23
24	Use these configuration defaults unless the user provides overrides. Ask for confirmation only when the target scope makes the required keys or products ambiguous:
25
26	\| Setting \| Default \| Description \|
27	\|---------\|---------\|-------------\|
28	\| Required `products` \| (none) \| Which product IDs must appear (e.g., `kibana`) \|
29	\| Additional products allowed \| yes \| Whether extra product IDs beyond the required ones are acceptable \|
30
31	## Required frontmatter elements
32
33	Check each file for the following elements:
34
35	### 1. `products` (mandatory)
36
37	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.
38
39	```yaml
40	products:
41	- id: kibana
42	```
43
44	Flag files missing this element or missing required products. Don't remove existing additional products.
45	Flag `product` singular as likely incorrect unless the local repository explicitly uses that schema.
46
47	### 2. `description` (mandatory)
48
49	Validate against these rules:
50	- Present and non-empty
51	- Around 150 characters (recommended by docs-builder); flag anything over 200 characters as too long
52	- Complete sentence (not a fragment or label)
53	- No Jinja2 substitution variables (`{{kib}}`, `{{es}}`, `{{esql}}` — these aren't parsed in frontmatter)
54	- No label prefixes ("Reference -", "Tutorial -", "Guide -")
55	- Clear, user-facing summary of the page content
56	- Quoted if it contains punctuation or characters that could be misread by YAML, including colons
57
58	### 3. `navigation_title` (recommended)
59
60	Check if the H1 title exceeds ~50 characters. If so, flag that a `navigation_title` should be added.
61
62	```yaml
63	navigation_title: "Configure ML alerts"
64	```
65
66	### 4. `mapped_pages` (preserve)
67
68	If present, don't flag or suggest changes. If absent, don't suggest adding it.
69
70	## Execution
71
72	1. Glob for all `.md` files in the specified scope
73	2. Read the frontmatter of each file
74	3. Validate each element against the rules above
75	4. Read the H1 title to check length for `navigation_title`
76	5. Compile the report
77
78	## Report format
79
80	```
81	## Frontmatter audit: <scope>
82
83	Configuration:
84	- Required products: kibana
85	- Files scanned: N
86
87	### Issues found
88
89	#### Missing `products`
90	\| File \| Issue \|
91	\|------\|-------\|
92	\| path/to/file.md \| Missing `kibana` product \|
93
94	#### Invalid or missing `description`
95	\| File \| Issue \|
96	\|------\|-------\|
97	\| path/to/file.md \| Missing description \|
98	\| path/to/other.md \| Contains Jinja2 variables \|
99	\| path/to/third.md \| Exceeds 200 characters (247 chars); descriptions should usually be around 150 characters \|
100
101	#### Missing `navigation_title`
102	\| File \| H1 length \|
103	\|------\|-----------\|
104	\| path/to/file.md \| 63 chars \|
105
106	### Summary
107
108	- ✅ N files passed all checks
109	- ❌ N files have issues
110	- N missing products
111	- N invalid/missing description
112	- N missing navigation_title (recommended)
113	```
114
115	Group issues by type, not by file, so users can batch-fix related problems. Only include sections that have issues.

People who liked this also viewed

6 picks

Type