bevyengine / bevyengine/bevy-website

Migration generator: loose lists get mangled

Open
#1,355 0 comments 1 reaction 0 assignees View on GitHub
A-Migration Guides C-Automation C-Bug
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

Open the contributing 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

Get new issues in your inbox

A short digest of beginner-friendly GitHub issues.