Markdown subbullets don't display correctly on docs.libretro.com site, but preview correctly in github Preview editor
Nobody has claimed this yet.
Assessment
- Difficulty
- 4/5
- Estimated time
- 3-5 days
- Newbie friendliness
- 35/100
- Issue type
- Bug
- Clarity
- Mostly clear
- Activity status
- Stale
- Tech stack
- markdown
- Domain
- documentation
Research direction
Compare the linked Markdown source in roms-playlists-thumbnails.md with its rendered page on docs.libretro.com, then trace the docs site's Markdown engine or configuration. Done means nested bullet levels and lists without a preceding blank line render consistently with GitHub's preview.
Written by the indexing model from the issue text.
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.
- Dominant language
- TeX
- Stars
- 346
- Forks
- 860
- Avg merge
- 5d 16h
- Merged PRs (30d)
- 7
Contributor guide
First steps
- Read the whole issue, then the project's contributing guide.
- Comment on the issue to say you are picking it up — it saves two people doing the same work.
- Fork the repository and make your change on a branch.
- Open a pull request that references the issue number.
More from libretro/docs
-
Difficulty 2/5 1-3 hours Newbie friendliness 72/100
-
bug
Difficulty 2/5 1-3 hours Newbie friendliness 75/100
-
bug
Difficulty 1/5 Under an hour Newbie friendliness 88/100
-
Difficulty 1/5 Under an hour Newbie friendliness 65/100
-
bug
Difficulty 1/5 1-3 hours Newbie friendliness 65/100
Similar issues
-
agent-ready documentation needs-triage
Difficulty 1/5 1-3 hours Newbie friendliness 88/100
-
untriaged
Difficulty 1/5 Under an hour Newbie friendliness 88/100
dotnet/dotnet-api-docs#13095 ·
-
documentation
Difficulty 1/5 Under an hour Newbie friendliness 91/100
-
workflow-status page template still says reusable workflows are "triggered only by workflow_call:" Open
Difficulty 1/5 Under an hour Newbie friendliness 92/100
-
refactor
Difficulty 2/5 1-3 hours Newbie friendliness 78/100