Markdown subbullets don't display correctly on docs.libretro.com site, but preview correctly in github Preview editor #1017
Description
Note: I'm submitting a PR to work-around the sub-bullet example in the attached picture, so please use screenshot rather than what the current docs page may look like.
Bullet and sub-bullet leveling that displays correctly on github site does not display correctly on docs.libretro.com. Seems like markdown version/engine problem, or maybe some toggle setting somewhere about standard strictness.
Writers / checkers can't see the problem until after the merge and visiting the docs site, because the github preview and page-view markdown looks fine.
Example 1: Sub-bullet tiers rendering incorrectly. Correct markdown for 3-tier bullet list displays correctly on github.com page but not on the resulting docs.libretro.com page. So it breaks technical hierarchy info like demonstrations of subfolders (beyond just a cosmetic issue).
Work around. To force more/correct indentation of a sub-bullet, a writer can add more spaces in the indent like this:
[flush left edge]- Top level
[4 spaces]- Second level. Normally it should require 2 spaces.
[6 spaces]- Third sub-bullet level. Normally it should only require 4 spaces.
Example 2: List is not rendered due to linebreak standard difference between github preview and libretro docs site.
We already merged a fix for that example. The github.com preview displayed the list correctly despite the lack of a line break before the list.
Workaround: adding a line-break before that list code makes it appear correctly on docs.libretro.com. (But github.com preview and page-view handled the list well regardless. So authors wouldn't know that an issue will occur on the final docs site.)
I'll maybe eventually add a few points on the markdown section of the docs contribution guide page to explain.