Paragraphs in lists are rendered as paragraphs interspersing lists

[Aksej]

Using this docstring:

  "…
 - `(REGISTER REGISTER-NAME &OPTIONAL VALUE)`

    If VALUE is not NIL, write VALUE into local register REGISTER-NAME.

    If VALUE is NIL, read the saved value from register REGISTER-NAME.

    Writing to a set register and reading from an unset register are errors.

 - `(PARTICLE INDEX)`

    Returns tha `INDEX`th particle from the particle list.

 - `PARTICLES`

    refers to the set of all particles."

the generated markdown looks like this:

   …
    - `(REGISTER REGISTER-NAME &OPTIONAL VALUE)`
    
    If VALUE is not `NIL`, write VALUE into local register `REGISTER-NAME`.
    
    If VALUE is `NIL`, read the saved value from register `REGISTER-NAME`.
    
    Writing to a set register and reading from an unset register are errors.
    
    - `(PARTICLE INDEX)`
    
    Returns tha `INDEX`th particle from the particle list.
    
    - `PARTICLES`
    
       refers to the set of all particles.

while this is the expected output:

   …
    - `(REGISTER REGISTER-NAME &OPTIONAL VALUE)`
    
       If VALUE is not `NIL`, write VALUE into local register `REGISTER-NAME`.
    
       If VALUE is `NIL`, read the saved value from register `REGISTER-NAME`.
    
       Writing to a set register and reading from an unset register are errors.
    
    - `(PARTICLE INDEX)`
    
       Returns tha `INDEX`th particle from the particle list.
    
    - `PARTICLES`
    
       refers to the set of all particles.

[melisgl]

The short answer is that the paragraphs belonging to the list item should be indented 4 spaces in compared to the bullet, while it's only 3 spaces in your example. Long story follows.

Consider the following example, where "paragraph" is indented 4 spaces and is parsed as part of the list item:

(3bmd-grammar:parse-doc "
- bullet line

    paragraph
")
=> ((:BULLET-LIST
     (:LIST-ITEM (:PARAGRAPH "bullet" " " "line")
                 (:PARAGRAPH "paragraph"))))

Good. 3bmd tolerates the bullet being indented 1 space in:

(3bmd-grammar:parse-doc "
 - bullet line

    paragraph
")
=> ((:BULLET-LIST
     (:LIST-ITEM (:PARAGRAPH "bullet" " " "line")
                 (:PARAGRAPH "paragraph"))))

but doesn't work if the "paragraph" is indented only 3 spaces:

(3bmd-grammar:parse-doc "
- bullet line

   paragraph
")
=> ((:BULLET-LIST
     (:LIST-ITEM (:PLAIN "bullet" " " "line")))
    (:PLAIN "   " "paragraph"))

In fact, this last version is what your example ended up looking like due to how pax guesses and strips the indentation from docstrings (see https://github.com/melisgl/mgl-pax#921-indentation and https://github.com/melisgl/mgl-pax#x-28MGL-PAX-3ADOCUMENT-OBJECT-20-28METHOD-20NIL-20-28STRING-20T-29-29-29).

[Aksej]

I thought indenting four times would create an inline code block, I misunderstood github markdown in that respect. Sorry for the false bug report!