libretro / libretro/docs

Markdown subbullets don't display correctly on docs.libretro.com site, but preview correctly in github Preview editor

Open
#1,017 0 comments 0 reactions 0 assignees View on GitHub

Nobody has claimed this yet.

bug
Dominant language
TeX
Stars
346
Forks
860
Avg merge
5d 16h
Merged PRs (30d)
7

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).

sub-bullet losing hierarchy though displayed correctly on github page - Copy

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.

List doesn't get formatted as list

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.

Contributor guide

Open the contributing guide

First steps

  1. Read the whole issue, then the project's contributing guide.
  2. Comment on the issue to say you are picking it up — it saves two people doing the same work.
  3. Fork the repository and make your change on a branch.
  4. Open a pull request that references the issue number.

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.

Assessment

Tech stack
markdown
Domain
documentation
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.