Reported by @zerok while reviewing #2276, as an inline comment on actions/get-vault-secrets/README.md:
Looks like the renderer is struggling with new-lines there. It would be awesome if you/someone could fix this in a follow-up but it's not critical imo.
What happens
cleanCell in scripts/generate-input-output-docs/render.go collapses every run of whitespace so a description fits on one line of a markdown table. When the description contains a fenced code block, that flattening destroys the thing the example exists to show.
actions/get-vault-secrets/action.yaml declares (fence indented here so it nests):
repo_secrets:
description: |
Repository-specific secret mapping. ...
Ex:
```
repo_secrets: |
ENVVAR1=secretpath:key
ENVVAR2=secretpath:key2
```and the generated cell renders as:
... Ex: `repo_secrets: \| ENVVAR1=secretpath:key ENVVAR2=secretpath:key2`
One pair per line is the whole point of the example, and it is gone. The | also has to be escaped to survive the table, which adds noise.
Affected
actions/get-vault-secrets — repo_secrets, common_secretsactions/trigger-argo-workflow — parameters. Already mitigated: the README carries a separate code block below the table showing the key=value per line convention.
Options
- Move such examples into hand-written prose outside the generated markers, the way
trigger-argo-workflow already does. No generator change, but it relies on authors knowing to do it.
- Have the generator detect a fenced block in a description, keep a short summary in the table cell, and emit the example as a real code block beneath the table. More useful, more machinery.
Option 2 is the better outcome if the extra complexity is acceptable.
Worth stating either way: a markdown table cell cannot contain a multi-line code block, so the example has to live outside the table. This is a question of where it goes, not of making the flattening lossless.
Context
The generator and the CI drift check landed in #1454 and #2276. Nothing here blocks either — the affected cells are accurate, just less useful than the prose they replaced.
Reported by @zerok while reviewing #2276, as an inline comment on
actions/get-vault-secrets/README.md:What happens
cleanCellinscripts/generate-input-output-docs/render.gocollapses every run of whitespace so a description fits on one line of a markdown table. When the description contains a fenced code block, that flattening destroys the thing the example exists to show.actions/get-vault-secrets/action.yamldeclares (fence indented here so it nests):and the generated cell renders as:
One pair per line is the whole point of the example, and it is gone. The
|also has to be escaped to survive the table, which adds noise.Affected
actions/get-vault-secrets—repo_secrets,common_secretsactions/trigger-argo-workflow—parameters. Already mitigated: the README carries a separate code block below the table showing thekey=valueper line convention.Options
trigger-argo-workflowalready does. No generator change, but it relies on authors knowing to do it.Option 2 is the better outcome if the extra complexity is acceptable.
Worth stating either way: a markdown table cell cannot contain a multi-line code block, so the example has to live outside the table. This is a question of where it goes, not of making the flattening lossless.
Context
The generator and the CI drift check landed in #1454 and #2276. Nothing here blocks either — the affected cells are accurate, just less useful than the prose they replaced.