[Bug] Colon in parser description field generates invalid markdown header

[echoix]

Describe the bug

I'm filing the problem here, even if the page in question is from addons.

The page v.stream.network docs page has some text that should probably be in the yaml front matter, but is being spit out as text. No tags are shown, but rather

name: v.stream.profiler description: Build a linked stream network: each link knows its downstream link keywords: [ vector, stream network, hydrology, geomorphology ]

To reproduce

1. Go to https://grass.osgeo.org/grass-devel/manuals/addons/v.stream.profiler.html
2. See the top of the page, where some extra text is spit out instead of tags/keywords

Expected behavior

Screenshots

Bad:

Good:

Source of the issue is in: https://github.com/OSGeo/grass-addons/blob/f2a0cbb2f14932f50cdb1668282a292eb864584a/src/vector/v.stream.profiler/v.stream.profiler.py

The description line contains a colon in the text, here: https://github.com/OSGeo/grass-addons/blob/f2a0cbb2f14932f50cdb1668282a292eb864584a/src/vector/v.stream.profiler/v.stream.profiler.py#L24

System description

Additional context

It reminds me of a similar think I reported to the ruff repo once, https://github.com/astral-sh/ruff/issues/14976, but it was for backticks. Rereading it, it really hints to the solution. The PR that fixed this explains a bit more the cause: https://github.com/astral-sh/ruff/pull/14980 When using plain scalars in yaml, they must never contain some sequences, like : or #. The linked docs on yaml note:

Plain scalars must never contain the “: ” and “ #” character combinations. Such combinations would cause ambiguity with mapping key/value pairs and comments. In addition, inside flow collections, or when used as implicit keys, plain scalars must not contain the “[”, “]”, “{”, “}” and “,” characters. These characters would cause ambiguity with flow collection structures. https://yaml.org/spec/1.2.2/#733-plain-style

The PR that fixed the issue in ruff's docs changed to use a block scalar with strip block chomping. I just checked and these lines are still in use on their main branch since.

The solution is to tweak the script that transforms the markdown files

[wenzeslaus]

I used |- elsewhere, r.mask.status I think, to avoid need to deal with special characters. I would prefer to generate that on parser level in C, but that means, we need to read this more full YAML syntax in Python.