Can rumdl lint markdown in YAML files?

[polarweasel]

I've got some large AsyncAPI specs that feed into a docs pipeline, and I would love to be able to lint (auto-formatting is a stretch goal!) the markdown descriptions. Is that possible, without all the false positives that come with a [per-file-flavor] entry for YAML?

[rvben]

Markdown-in-YAML-field linting isn't built in yet: rumdl can lint markdown extracted from Rust doc comments and from fenced code blocks, but it has no YAML field extraction. And you're right that a [per-file-flavor] YAML entry would lint the whole file as markdown, which floods you with false positives on the YAML syntax itself.

What works today, using rumdl's stdin support plus yq:

yq '[.. | select(has("description")) | .description] | join("\n\n")' spec.yaml \
  | rumdl check --stdin --stdin-filename spec-descriptions.md

This pulls every description out of the spec, joins them into one markdown document, and lints it. I tested it against the official AsyncAPI streetlights/slack/gitter examples - it correctly handles both YAML block scalars (|, >) and the escaped double-quoted style streetlights uses for its main description; both decode to real markdown before linting, and trailing whitespace is preserved.

Your auto-format stretch goal works too - swap check for fmt:

yq '[.. | select(has("description")) | .description] | join("\n\n")' spec.yaml \
  | rumdl fmt --stdin -

Two caveats:

• Reported line numbers refer to the extracted markdown, not positions in the YAML file - fine for a docs-pipeline gate, less so for jump-to-line in an editor.
• select(has("description")) grabs every description (servers, parameters, one-liners), so expect some noise. Narrow it to what you care about, e.g. yq '.info.description, .channels[].description' spec.yaml. For JSON specs, use yq -p json or jq.

Native field extraction isn't on the roadmap right now, but the pipe above should keep your docs pipeline covered.

[polarweasel]

Thank you, @rvben! This was super helpful.