docs-validate-code-samples

Name: docs-validate-code-samples
Author: elastic

71stars10forks

How to install docs-validate-code-samples?

elastic/elastic-docs-skills/docs-validate-code-samples

$npx -y skills add elastic/elastic-docs-skills --skill docs-validate-code-samples

Installs into the current project.

Summary

Validate code samples in Elastic documentation markdown files. Checks language identifiers, substitution attributes, callout usage, JSON validity, ES|QL syntax, and Painless scripts. Use when reviewing docs PRs, auditing content, or writing new examples.

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 code sample validator for Elastic documentation. Check every code block in one or more markdown files against the docs-builder style rules and report all violations.
19
20	Never modify documentation source files. Only analyze and report.
21
22	---
23
24	## Step 1: Resolve files
25
26	Parse `$ARGUMENTS` for an optional `--output <path>` flag (strip it before continuing). Resolve the target:
27
28	- Single `.md` file — analyze that file only.
29	- Directory — find all `.md` files recursively with `find <dir> -name "*.md" -type f \| sort`.
30	- Glob — expand with `bash -O globstar -c 'printf "%s\n" <glob>'`.
31	- No argument — ask: "Please provide a file path, directory, or glob pattern."
32
33	---
34
35	## Step 2: Extract code blocks
36
37	For each file, use Grep with pattern `` ^``` `` to find fence line numbers, then Read the file to extract blocks. Also search for indented fences (`` ^\s+``` ``) to catch blocks inside list items.
38
39	- Skip blocks inside HTML comments (`<!-- ... -->`).
40	- Skip MyST directive blocks where the info string starts and ends with `{}` (e.g., `` ```{note} ``).
41
42	For each block capture: opening line number, fence info string, language identifier (first word), attributes (remaining tokens), and body.
43
44	---
45
46	## Step 3: Run checks A through H
47
48	### Check A — Missing or wrong language identifier
49
50	Flag any block with an empty fence info string. Also flag blocks where the language identifier is clearly wrong for the content (e.g., `js` used for a JSON-only response, `console` used for response-only data with no HTTP method line).
51
52	Common valid identifiers: `bash`, `sh`, `console`, `console-result`, `json`, `yaml`, `python`, `javascript`, `js`, `typescript`, `java`, `go`, `ruby`, `sql`, `esql`, `eql`, `painless`, `kql`, `kuery`, `txt`, `text`, `xml`, `toml`, `ini`, `diff`.
53
54	Infer the correct identifier from content: HTTP method line → `console`; starts with `{`/`[` → `json`; `key: value` lines → `yaml`; `curl`/`apt-get` → `bash`; `import`/`def`/`print(` → `python`; `public class` → `java`; `const`/`let`/`=>` → `javascript`.
55
56	### Check B — Variable substitution missing `subs=true`
57
58	Walk up from the target file to find `docset.yml` and parse its `subs:` section for valid variable names. Stop at the git root (presence of `.git/`) or after 6 directory levels, whichever comes first. Flag any block containing `{{var}}` where `var` is a defined substitution key but the fence info lacks `subs=true`. Also flag the inverse: `subs=true` on a block with no `{{...}}` patterns.
59
60	If no `docset.yml` is found, flag any `{{word}}` pattern (single identifier) as a potential substitution variable.
61
62	### Check C — Inline comments that should be callouts
63
64	For blocks with language `bash`, `sh`, `shell`, `console`, `yaml`, `python`, `javascript`, `js`, `typescript`, `java`, `go`, or `ruby`: flag lines where `#` or `//` appears after code on the same line and the comment reads as a reader-facing explanation.
65
66	Exemptions: shebang lines, standalone comment lines (no code on the same line), `#` inside strings, lines already using callout markers (`<1>`).
67
68	Suggestion: replace with explicit callout markers (`<N>`) and a numbered list after the block.
69
70	### Check D — JSON validation in `console` and `console-result` blocks
71
72	`console` blocks are API requests (customers copy-paste them); `console-result` blocks are responses (display only). Each `console` block contains one or more API calls: an HTTP method+p

People who liked this also viewed

6 picks

Type

docs-validate-code-samples

71stars10forks

View on GitHub

How to install docs-validate-code-samples?

elastic/elastic-docs-skills/docs-validate-code-samples

$npx -y skills add elastic/elastic-docs-skills --skill docs-validate-code-samples

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 code sample validator for Elastic documentation. Check every code block in one or more markdown files against the docs-builder style rules and report all violations.
19
20	Never modify documentation source files. Only analyze and report.
21
22	---
23
24	## Step 1: Resolve files
25
26	Parse `$ARGUMENTS` for an optional `--output <path>` flag (strip it before continuing). Resolve the target:
27
28	- Single `.md` file — analyze that file only.
29	- Directory — find all `.md` files recursively with `find <dir> -name "*.md" -type f \| sort`.
30	- Glob — expand with `bash -O globstar -c 'printf "%s\n" <glob>'`.
31	- No argument — ask: "Please provide a file path, directory, or glob pattern."
32
33	---
34
35	## Step 2: Extract code blocks
36
37	For each file, use Grep with pattern `` ^``` `` to find fence line numbers, then Read the file to extract blocks. Also search for indented fences (`` ^\s+``` ``) to catch blocks inside list items.
38
39	- Skip blocks inside HTML comments (`<!-- ... -->`).
40	- Skip MyST directive blocks where the info string starts and ends with `{}` (e.g., `` ```{note} ``).
41
42	For each block capture: opening line number, fence info string, language identifier (first word), attributes (remaining tokens), and body.
43
44	---
45
46	## Step 3: Run checks A through H
47
48	### Check A — Missing or wrong language identifier
49
50	Flag any block with an empty fence info string. Also flag blocks where the language identifier is clearly wrong for the content (e.g., `js` used for a JSON-only response, `console` used for response-only data with no HTTP method line).
51
52	Common valid identifiers: `bash`, `sh`, `console`, `console-result`, `json`, `yaml`, `python`, `javascript`, `js`, `typescript`, `java`, `go`, `ruby`, `sql`, `esql`, `eql`, `painless`, `kql`, `kuery`, `txt`, `text`, `xml`, `toml`, `ini`, `diff`.
53
54	Infer the correct identifier from content: HTTP method line → `console`; starts with `{`/`[` → `json`; `key: value` lines → `yaml`; `curl`/`apt-get` → `bash`; `import`/`def`/`print(` → `python`; `public class` → `java`; `const`/`let`/`=>` → `javascript`.
55
56	### Check B — Variable substitution missing `subs=true`
57
58	Walk up from the target file to find `docset.yml` and parse its `subs:` section for valid variable names. Stop at the git root (presence of `.git/`) or after 6 directory levels, whichever comes first. Flag any block containing `{{var}}` where `var` is a defined substitution key but the fence info lacks `subs=true`. Also flag the inverse: `subs=true` on a block with no `{{...}}` patterns.
59
60	If no `docset.yml` is found, flag any `{{word}}` pattern (single identifier) as a potential substitution variable.
61
62	### Check C — Inline comments that should be callouts
63
64	For blocks with language `bash`, `sh`, `shell`, `console`, `yaml`, `python`, `javascript`, `js`, `typescript`, `java`, `go`, or `ruby`: flag lines where `#` or `//` appears after code on the same line and the comment reads as a reader-facing explanation.
65
66	Exemptions: shebang lines, standalone comment lines (no code on the same line), `#` inside strings, lines already using callout markers (`<1>`).
67
68	Suggestion: replace with explicit callout markers (`<N>`) and a numbered list after the block.
69
70	### Check D — JSON validation in `console` and `console-result` blocks
71
72	`console` blocks are API requests (customers copy-paste them); `console-result` blocks are responses (display only). Each `console` block contains one or more API calls: an HTTP method+p

People who liked this also viewed

6 picks

Type