fix(lint): resolve TOML blocking errors (43 of 49); add elide-marker normalizer rule#7166
Merged
jstirnaman merged 2 commits intomasterfrom May 1, 2026
Merged
Conversation
…rule
Validator improvement:
scripts/lib/codeblock-normalizer.mjs — add a third normalization
rule that comments out standalone elide markers (..., ...., [...])
before parsing. These markers are pervasive in Telegraf and
InfluxDB TOML examples and YAML config snippets to indicate
omitted content, but neither parses as valid TOML/YAML. The new
rule rewrites them as language-appropriate comments (# ... for
TOML/YAML/bash/python, // ... for JS) so blocks with otherwise
valid syntax pass without forcing authors to manually comment
every ellipsis. JSON has no comment syntax, so JSON fences with
ellipses must still be fixed at the source. For YAML, the
substitution skips column-0 ... (the YAML stream document-end
marker) — only indented occurrences are treated as ellipsis. This
alone clears 22 of the 49 originally-flagged TOML errors.
Content fixes (toml fence preserved):
- cloud-dedicated / cloud-serverless / clustered v1 API guides:
Replace curly close-quote (U+201D) in `content_encoding = "gzip”`
with the straight ASCII `"` so the string terminates correctly.
- kapacitor reference/event_handlers/post.md (5 errors):
Strings containing literal `{{index . "time"}}` template
expressions had inconsistent quoting — outer "..." with
unescaped inner ". Switched to TOML literal strings (single-
quoted) for url and row-template values; inner double quotes
are now safe and verbatim.
- kapacitor administration/subscription-management.md (2 errors):
`db_name = <list of retention policies>` had literal angle
brackets, invalid TOML. Changed to a commented pattern.
- kapacitor reference/event_handlers/zenoss.md:
Bare inline table `{ ... }` lacked a key. Added `severity-map = `.
- kapacitor reference/nodes/alert_node.md:
Bare `timeout = 10s` is not valid TOML (TOML has no duration
primitive). Quoted as "10s" — matches the convention used by
39 other duration values across Kapacitor docs. Kapacitor's
config parser still decodes the string into its Duration type.
- kapacitor administration/configuration.md:
Two alternative configs (v1 / v2-or-Cloud) shared the same
[[influxdb]] section, producing duplicate `enabled` and
`default` keys. Split into two separate ```toml fences with
intervening prose. Each block now parses on its own.
- kapacitor administration/auth/kapacitor-auth.md:
`auth-enabled: true` used YAML colon syntax inside a TOML block.
Changed to `auth-enabled = true`.
- kapacitor guides/event-handler-setup.md:
`parse-mode = Markdown` had a bare value; quoted as "Markdown".
- influxdb v1 administration/https_setup.md:
Lone `>` and bracketed `[...]` markers inside a TOML block were
blockquote/elide leakage from rendering. Replaced with
descriptive TOML comments.
- enterprise_influxdb v1 administration/configure/config-data-nodes.md:
Mangled prose-mixed-with-TOML around the [[collectd]] section
(`Default is `false.`, stray backticks). Cleaned up to a
standard commented-defaults block.
- enterprise_influxdb v1 administration/configure/security/ldap.md:
A 12-line comment block was duplicated verbatim, each followed
by the same client-tls-certificate / client-tls-private-key
assignments — producing duplicate-key errors. Removed the second
(byte-identical) block; the original block above documents the
keys.
- enterprise_influxdb v1 tools/influxd-ctl/ldap/sample-config.md:
Shell prompt `meta1:/# influxd-ctl ldap sample-config -h` was
embedded mid-TOML. Moved to a TOML comment showing the producing
command.
- telegraf v1 configuration.md:
Block demonstrates Telegraf's preprocessor `${VAR}` substitution,
which uses bare unquoted form for non-string values
(`skip_database_creation = ${VAR}`). That syntax is a Telegraf
extension to TOML and not parseable by strict TOML validators.
Relabeled the fence as `text` with an HTML comment explaining why.
- telegraf v1 data_formats/input/json_v2.md:
Inline parenthetical `false (or true, just not both)` was not a
valid TOML comment. Changed to a proper trailing `#` comment.
Deferred to upstream telegraf README sync (6 errors):
- input-plugins/jti_openconfig_telemetry, opcua_listener,
postgresql_extensible, win_eventlog
- output-plugins/dynatrace
- processor-plugins/converter
These docs are generated from influxdata/telegraf README files
per content/telegraf/CLAUDE.md. Any fix here would be reverted on
the next sync; they need to be filed and fixed upstream first.
Test coverage: 59/59 lint-codeblocks tests still pass.
Contributor
Vale Style Check Results
Errors (blocking)
Warnings (7)
❌ Check failed — fix 1 error(s) before merging. |
github-actions
Bot
added
product:kapacitor
Contributor
|
2 tasks
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
1 participant
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
Summary
Fixes 43 of the 49 TOML blocking errors flagged by
yarn lint-codeblocksoncontent/. Keeps thetomlfence label everywhere it makes sense.Validator improvement
scripts/lib/codeblock-normalizer.mjs— adds an "elide marker" normalization rule that comments out standalone...,...., and[...]lines before parsing. These ellipsis markers are common in Telegraf and InfluxDB config examples to indicate omitted content but neither form parses as valid TOML/YAML. The new rule rewrites them as language-appropriate comments (# ...for TOML/YAML/bash/python,// ...for JS) so blocks with otherwise valid syntax pass without forcing authors to manually comment every ellipsis.JSON has no comment syntax, so JSON fences with ellipses must still be fixed at the source. For YAML, column-0
...(the stream document-end marker) is preserved — only indented occurrences become comments.This rule alone clears 22 of the 49 originally-flagged TOML errors.
Content fixes (
tomlfence preserved)cloud-dedicated,cloud-serverless,clusteredv1 API guides (3)"gzip”with straight ASCII"kapacitor/v1/reference/event_handlers/post.md(5)url/row-templatevalues containing nested"..."template tokenskapacitor/v1/administration/subscription-management.md(2)db_name = <list>literal angle brackets with a commented patternkapacitor/v1/reference/event_handlers/zenoss.mdseverity-map =prefix to bare inline table{ ... }kapacitor/v1/reference/nodes/alert_node.mdtimeout = 10s→"10s"(matches 39 other duration values across Kapacitor docs)kapacitor/v1/administration/configuration.md[[influxdb]]section into separate fences (no more duplicate keys)kapacitor/v1/administration/auth/kapacitor-auth.md:syntax → TOML=forauth-enabledkapacitor/v1/guides/event-handler-setup.mdparse-mode = Markdowninfluxdb/v1/administration/https_setup.md>blockquote and bare[...]ellipses with TOML commentsenterprise_influxdb/v1/administration/configure/config-data-nodes.md[[collectd]]enterprise_influxdb/v1/administration/configure/security/ldap.mdclient-tls-*key assignmentsenterprise_influxdb/v1/tools/influxd-ctl/ldap/sample-config.mdtelegraf/v1/configuration.md${VAR}preprocessor (TOML-extension); relabel fence astextwith explanatory HTML commenttelegraf/v1/data_formats/input/json_v2.md(or true, just not both)to a proper#commentDeferred to upstream
influxdata/telegraf(6 errors)These docs are generated from
influxdata/telegrafplugin READMEs (percontent/telegraf/CLAUDE.md). Any fix indocs-v2would be reverted on the next sync; they need to be filed and fixed upstream first:content/telegraf/v1/input-plugins/jti_openconfig_telemetry/_index.mdcontent/telegraf/v1/input-plugins/opcua_listener/_index.mdcontent/telegraf/v1/input-plugins/postgresql_extensible/_index.mdcontent/telegraf/v1/input-plugins/win_eventlog/_index.mdcontent/telegraf/v1/output-plugins/dynatrace/_index.mdcontent/telegraf/v1/processor-plugins/converter/_index.mdWill file an upstream issue/PR after this lands.
Verification
yarn test:lint-codeblocks: 59/59 passyarn lint-codeblockson the affected files: 0 TOML errors remain in editable files, 6 remain in generated telegraf-plugin docs (listed above)\``toml` blocks across the repo continue to parse (no regressions from the normalizer change)Test plan
text-relabeled telegraf configuration block)