Docs renderer doesn't render correctly Markdown numbered lists

[peci1]

Description

• Expected behavior:

Markdown allows for numbered lists to by typed like:

1. item 1
1. item 2

Which should be rendered as

1. item 1
2. item 2

• Actual behavior: It renders all items as 1.

Steps to reproduce

See https://github.com/ignitionrobotics/ign-common/blob/ign-common3/tutorials/hw-encoding.md and the rendered version at https://ignitionrobotics.org/api/common/3.10/hw-encoding.html .

I'm not sure which implementation of Markdown does Ign docs support, but multiple Markdown guides show this syntax as allowed: https://guides.github.com/features/mastering-markdown/, https://www.markdownguide.org/basic-syntax/#lists-1 . Even Github renders this type of lists correctly.

[chapulina]

Just to clarify, this issue is about per-package docs, which are generated differently from the top-level docs contained in this website. This is a good place to ticket this issue, but the difference is important.

Unlike the top-level docs, the API docs are generated using doxygen and can be tested locally as instructed under Documentation. Doxygen's markdown support page lists 1., 2. for ordered lists, and the lists documentation mentions -# for auto-numbered lists. As mentioned in this answer, that's not a common standard, but that's what we have.

I don't think there's much we can do to add support for the 1. 1. style lists, but maybe making it more obvious to users how to generate the docs locally could help?

[peci1]

Thanks for clarification. I agree that making the local docs build more visible would help. If it's difficult to change the renderer, I'll fix my tutorial and try to remember that I can't use this feature.

[chapulina]

I'll close this because it's something we can't fix on our end. I added #148 for adding doc contribution documentation.