Crystal: Numbered list not rendered correctly in docs when using code block

[r00ster91]

This is how the current Installation section looks in the generated docs:

1 and 1 instead of 1 and 2.
Even if this is actually in the README:

`````md

Installation

1. Add the dependency to your shard.yml:

dependencies:
  library:
    github: user/library

1. Run shards install
   ``````

[asterite]

That's probably a bug with the markdown renderer

[r00ster91]

The bug is very likely here: parser.cr:253.

[j8r]

Another solution is to stop investing time for this in the stdlib and use e.g. markd

[straight-shoota]

Let's just ignore the error for now and change the list to be unordered. A fix can be delayed until we have some final decision on how to provide proper markdown support to the compiler. Or maybe we don't even need that if the compiler just outputs plain markdown and an external doc generator renderes it to HTML or whatever format.

[Sija]

There are battle tested markdown libraries, that's not a problem if we'd like to go in that direction.

[RX14]

We've been through the logistics of the compiler depending on external shards before and it's not going to happen any time soon. There's a big disagreement on how to do it.

[r00ster91]

@bcardiff shouldn't this be rather fixed before releasing 0.27.0?

[asterite]

I'd say not necessarily, the readme is usually read from GitHub, etc. The docs are used for the API (yes, the readme appears there too but someone will have read GitHub before, or having 1., 1. isn't a big deal).

[r00ster91]

Unfortunately now after #7118, the Installation section is rendered even buggier:

``````md

Installation

1. Add the dependency to your shard.yml:

   dependencies:
    library:
      github: user/library
   

2. Run shards install
   ``````

[straight-shoota]

IMHO the only sane way to proceed is to invest in a proper markdown implementation. I don't think it makes sense apply makeshift patches to the Markdown library every now and then when a new flaw is detected. This continuously requires attention and effort.

The stdlib Markdown implementation is very rudimentary and flawed. It's safe to assume it would require a complete rewrite to push it to an acceptable Markdown support level.

I proposed #4613 a long time ago, but it has been sidetracked from the main issue to discussions about the organization of the compiler code etc.. So it's still inconclusive and lacks any path to action.

Until there is any progress in that issue, I think it's best to simply avoid any flaws in the Markdown parser. I.e. change ordered list to unordered and revert #7118.