bevyengine / bevyengine/bevy-website
Migration generator: loose lists get mangled
- Dominant language
- JavaScript
- Stars
- 249
- Forks
- 450
- Avg merge
- 16h 20m
- Merged PRs (30d)
- 6
Description
It seems that a list with a line break between two items is considered a "[loose list](https://spec.commonmark.org/0.29/#loose)"
```
- a
- b
```
Becomes this:
```
Start(List(None))
Start(Item)
Start(Paragraph)
Text(Borrowed("a"))
End(Paragraph)
End(Item)
Start(Item)
Start(Paragraph)
Text(Borrowed("b"))
End(Paragraph)
End(Item)
End(List(None))
```
when parsed by `pulldown_cmark`. This is normal/expected behavior.
Because we emit line endings for `Paragraph` tag start/end, the final markdown ends up being:
```
-
a
-
b
```
Which is rendered like this:
---
-
a
-
b
---
Here's an example in the wild:
https://github.com/bevy/bevy-website/blob/39fcf9589e236e8779b6488a2db6639a3e68a5f3/release-content/0.14/migration-guides/11989_Implement_the_AnimationGraph_allowing_for_multiple_animati.md?plain=1
(this was fixed manually in #1344)
I am not really sure how to work around this, but if I find time I may try to
- Not emit line breaks for the first paragraph start event for a particular list item
- Add indentation for subsequent paragraphs in a list item on the paragraph start event
Contributor guide
Research direction
Start at the migration generator's pulldown_cmark event handling and compare the output for the loose-list example in this issue with the manually fixed example from #1344. The work is done when loose list items retain valid markdown structure and render with each item’s text on the same list line.
Written by the indexing model from the issue text.
Assessment
- Tech stack
- javascript
- Domain
- tooling
- Issue type
- Bug
- Difficulty
- 4/5
- Estimated time
- 3-5 days
- Activity status
- Stale
- Clarity
- Mostly clear
- Newbie friendliness
- 35/100