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 tomkdocs
, 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 formdx_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.
cmitu commented
Note and examples added to https://github.com/RetroPie/RetroPie-Docs/blob/master/docs/Style-Guide.md