RetroPie/RetroPie-Docs

List formatting breaks when generating the doc site

cmitu opened this issue · 2 comments

cmitu commented

MD list formatting is inconsistent between Github's MD and the mkdocs using the mdx_truly_sane_lists extension.
This leads to broken lists in the generated mkdocs output, while the list looks fine when previewed on Github (like in #59).

cmitu commented

During a brief test, I compared mkdocs and Github formatting for nesting lists.

  • Github shows a sub-list with 2-4 spaces, even 5
  • mkdocs - default - uses the Python Markdown parser/generator, accepts 4 spaces for the sub-lists
  • when mdx_truly_sane_lists is added to mkdocs, only 2 spaces produce the correct list (3 spaces work for level 2, but break level 3 sub-lists).
    The number of spaces is configurable for mdx_truly_sane_lists, is set to 2 for compatibility with other implementations.

Since we want to use mdx_truly_sane_lists, it doesn't matter if we configure 2 or 3 spaces in order to be compatible with Github, but for compatibility with existing content, we can leave it at 2. If left this way, we should add a note in the contributing guidelines page to explain this.