docs: fix code-block lint errors across plugin READMEs#18830
Conversation
InfluxData docs-v2 added a parse/compile lint check for fenced code
blocks. JSON, YAML, and TOML blocks that fail to parse block CI on
the docs site. The plugin READMEs in this repo are mirrored verbatim
into docs-v2 by the sync process, so several blocks that were never
valid JSON or TOML now break the docs build downstream.
These fixes preserve the original intent and content where possible.
Where a block is genuinely illustrative (placeholders, ellipses, mixed
HTTP-method-line plus body, vendor query languages) the fence is
relabeled to the closer-fit language so the lint check skips it.
TOML fixes (6 files):
- inputs/jti_openconfig_telemetry: `sensors = [...]` was redefined
twice; commented out the alternative-form example.
- inputs/opcua_listener: `// ... default values ...` C-style
comments inside an inline-table list. TOML uses `#` for comments;
converted to trailing `#` comments.
- inputs/postgresql_extensible: `sqlquery = "...where \` line
continuations in basic strings are invalid TOML. Switched to
multi-line basic strings (`"""..."""`) which preserve the `\`
line-end continuation form for readability and parse cleanly per
the TOML 1.0 spec (`mlBasicBody <- ... / escape newline wsnl` in
influxdata/toml's parse.peg).
- inputs/win_eventlog: `xpath_query = '''` opened a TOML literal
multi-line string but never closed; the surrounding text says
"set xpath_query empty" — replaced with `""`.
- outputs/dynatrace: `api_token = "..." // hard-coded ...` —
converted `//` to `#`.
- processors/converter: `timestamp_format = "unix` missing close
quote.
JSON fixes (8 files):
- inputs/bind: BIND nameserver config (`statistics-channels { ... };`)
was tagged `json`. Relabeled `text`.
- inputs/ctrlx_datalayer (3 blocks): `"key" : value` lines (the OPC
UA server's address-value rendering) are not JSON. Relabeled `text`.
- inputs/docker (2 blocks): `docker_label_exclude = [...]` and
`docker_label_include = [...]` are TOML config snippets, not JSON.
Relabeled `toml`.
- outputs/azure_data_explorer: KQL function definition (`.create-or-
alter function ... { ... }`) tagged `json`. Relabeled `kusto`.
- outputs/clarify: `"signal" { ... }` and `"values" { ... }` are
Clarify's representation, not JSON. Relabeled `text`.
- outputs/elasticsearch (2 blocks): `PUT /_cluster/settings` and
`POST https://...` are HTTP request lines mixed with a JSON body.
Relabeled `text`.
- outputs/zabbix (2 blocks): line-delimited multiple JSON objects.
Relabeled `jsonl`.
- processors/lookup: illustrative template with `...` ellipsis
relabeled `text`; the actual data block had a trailing comma
that was removed.
No code or behavior changes — README content only.
|
@jstirnaman changes to the configuration should be made to the corresponding Note In Telegraf the configs embedded in the |
|
Superseding this bundled PR with focused, per-plugin changes so the Per your note about Tracking issue: #19201 Genuine-error fixes (each verified by loading in Telegraf 1.39.1):
Fence-language mismatches are tracked as individual issues (#19190–#19200), and Thanks @srebhan for the pointer. |
Summary
InfluxData docs-v2 (influxdata/docs-v2#7136) added a parse/compile lint check for fenced code blocks. JSON, YAML, and TOML blocks that fail to parse block CI on the docs site.
The plugin READMEs in this repo are mirrored verbatim into docs-v2 by the sync process, so several blocks that were never valid JSON or TOML now break the docs build downstream. The corresponding influxdata/docs-v2 fixes and JSON fixes explicitly defer these 14 files to upstream because any in-place fix would be overwritten on the next sync.
These changes preserve the original intent and content where possible. Where a block is genuinely illustrative (placeholders, ellipses, mixed HTTP-method-line plus body, or vendor query languages), the fence is relabeled to the closer-fit language so the lint check skips it.
TOML fixes (6 files)
inputs/jti_openconfig_telemetry/README.mdsensors = [...]was redefined twice; commented out the alternative-form exampleinputs/opcua_listener/README.md// ... default values ...C-style comments inside an inline-table list. Converted to trailing#commentsinputs/postgresql_extensible/README.mdsqlquery = "...where \line continuations in basic strings are invalid TOML. Switched to multi-line basic strings ("""...""") which preserve the\line-end continuation form for readability and parse cleanly per the TOML 1.0 specinputs/win_eventlog/README.mdxpath_query = '''opened a literal multi-line string but never closed; surrounding text says "set xpath_query empty" — replaced with""outputs/dynatrace/README.mdapi_token = "..." // hard-coded ...— converted//to#processors/converter/README.mdtimestamp_format = "unixmissing close quoteJSON fixes (8 files)
inputs/bind/README.mdstatistics-channels { ... };) taggedjson. Relabeledtextinputs/ctrlx_datalayer/README.md(3 blocks)"key" : valuelines (the OPC UA address-value rendering) are not JSON. Relabeledtextinputs/docker/README.md(2 blocks)docker_label_exclude = [...]/docker_label_include = [...]are TOML config snippets. Relabeledtomloutputs/azure_data_explorer/README.mdjson. Relabeledkustooutputs/clarify/README.md"signal" { ... }/"values" { ... }are Clarify's representation, not JSON. Relabeledtextoutputs/elasticsearch/README.md(2 blocks)PUT /_cluster/settingsandPOST https://...HTTP request lines mixed with JSON body. Relabeledtextoutputs/zabbix/README.md(2 blocks)jsonlprocessors/lookup/README.md...ellipsis relabeledtext; data block had a trailing comma that was removedWhy this approach
\line-end continuation. Confirmed byinfluxdata/toml/parse.peg:mlBasicBody <- ... / escape newline wsnland exercised byconfig/testdata/special_types.toml.postgresql_extensibleSQL queries are functionally identical before and after — the multi-line form folds whitespace per TOML 1.0, so the resulting query string is unchanged.textfor non-syntax-language blocks is the standard fix when a snippet was only ever illustrative (HTTP request examples, vendor query languages, partial fragments with placeholders).Verification
Linted locally with the same script as docs-v2 CI:
Test plan
"""..."""continuation parses to identical query strings; relabeled fences render with appropriate or no syntax highlighting)