Code-block breaks up list

[omus]

Given the markdown:

1. A list item that has a really long sentence which the user
may want to manually break up.

    ```sh
    # nested code blocks shouldn't break
    # up the list
    ```

1. The second item in a list.

I would expect the rendered HTML version to look something like:

---

---

Instead the Documenter rendered version looks like:

---

---

There are a couple of issues with how this is rendering:

• The list isn't contiguous: the second number should be "2."
• The code block is not nested under the first list item
• The code block isn't using the specified syntax highlighting and is showing the backticks
• The first list item is not part of the same line.

[mortenpi]

It should work fine if the line starting with "may" gets indented to the third character.

[mortenpi]

It it true that it's not consistent with CommonMark, as far as I can tell. But the parser in Base is often not following CommonMark anyway. So at best it's an upstream issue.

[omus]

@mortenpi modifying the indentation of "may" does fix the list item issue. The following markdown works:

1. A list item that has a really long sentence which the user
   may want to manually break up.

       # nested code blocks shouldn't break
       # up the list

1. The second item in a list.

Unfortunately using fenced code blocks (using backticks) doesn't seem supported when using lists.

[mortenpi]

The code block should be indented to three (as opposed to 4) spaces as well, then it works. The parser in Base is apparently really picky about whitespace.

[omus]

Ah, thank you. Working example for those reading this later:

1. A list item that has a really long sentence which the user
   may want to manually break up.

   ```sh
   # nested code blocks shouldn't break
   # up the list
   ```

1. The second item in a list.

Maybe I missed it but is this markdown syntax documented somewhere? Besides that I can close this issue.

[mortenpi]

There's a Markdown syntax section in the manual, but it is not this detailed.

[ericphanson]

I wonder if using CommonMark.jl for parsing would make things a bit more robust for this?

I spent a long time today (well, maybe half an hour, but that’s kinda too long for this) adjusting indentation in some documentation (in a private repo) with two levels of bullets and then a code block, and it seemed very fragile and hard to get right.

[mortenpi]

I wonder if using CommonMark.jl for parsing would make things a bit more robust for this?

Almost certainly. It's on my wishlist (actually, in general allowing alternative parsers), but integrating it into Documenter is a bit of work (e.g. it has its own AST representation). Another thing to consider there is the interaction with Base docstrings.

[odow]

I'm doing a triage of open documenter issues and closing issues that are stale. If I've made a mistake, please re-open

Closing as stale. I get that the current behavior is suboptimal, but this is a wider issue than just Documenter, and it can be fixed (easily, if tediously) by the user.