Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Markdown partly broken on docs.libretro.com site #1017

Open
OctopusButtons opened this issue Jan 4, 2025 · 0 comments
Open

Markdown partly broken on docs.libretro.com site #1017

OctopusButtons opened this issue Jan 4, 2025 · 0 comments
Labels
bug Something isn't working

Comments

@OctopusButtons
Copy link
Contributor

OctopusButtons commented Jan 4, 2025

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.

@OctopusButtons OctopusButtons added the bug Something isn't working label Jan 4, 2025
OctopusButtons added a commit to OctopusButtons/docs that referenced this issue Jan 4, 2025
Adding a few extra hyphens to work-around issue 1017 libretro#1017

The extra hyphens vitally fix wrong hierarchy rendering on the Thumbnail Folders sub-bullet list.
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment
Labels
bug Something isn't working
Projects
None yet
Development

No branches or pull requests

1 participant