Nested list with `markdown.lua`

[aignas]

I have a problem with this file. It has many indented nested lists, but the parser tries to interpret those as code blocks, which is wrong.

How could I fix it?

[stevedonovan]

I see that the gh Markdown parser is having difficulty as well with the nested lists, since they are indented past four spaces. I think we can make this work, but might need to edit the file itself? (Not sure if formatting changes to a legal license is acceptable)

[aignas]

Personally, I have solved this by just linking to the GNU website containing an HTML of the said license. I will try to see how well different parsers cope with nested lists and will update this issue.

[GrahamHannington]

I have the same issue as @gns-ank. Attempting to nest a list in a list using an indent of four spaces results in a code block.

The Markdown syntax documentation on the Daring Fireball website does not contain an example of nesting a list in a list.

I can fall back on HTML, but is there a way to nest lists in lists using markdown.lua, the Markdown processor supplied with LDoc 1.4.2? If not, does one of the other Markdown processors that I can use with LDoc support this?

The GitHub Markdown processor supports nested lists:

• Level 1, item 1
  • Level 2, item 1
  • Level 2, item 2
• Level 1, item 2

[jirutka]

I have the same problem. I’d like to use nested lists in my ldocs, but without success.

[elliottslaughter]

There must be some sort of pre-processing that's messing this up before it hits the markdown parser. I was able to run with the lunamark processor, and if I copy-and-paste the exact same contents into an independent markdown file it renders correctly.

Here are the input files I used for the comparison:

• in.lua (note: rename to .lua when you download this, Github doesn't allow .lua attachments)
• in.md (same, rename to .md)

You can see from the diff that the files are nearly identical:

$ diff -u in.lua in.md
--- in.lua	2020-04-15 15:44:06.000000000 -0700
+++ in.md	2020-04-15 15:43:58.000000000 -0700
@@ -1,4 +1,3 @@
---[[--
 Summary.
 
 *   List entry.
@@ -12,4 +11,3 @@
         with contents wrapped to next line.
 
 @module in
-]]

Command I ran:

ldoc -f lunamark in.lua
lunamark -t html in.md > in.html

Outputs:

• doc.tar.gz (output from ldoc)
• in.html (output from lunamark, rename to .html)

When I look at the results, I see that (a) the nested list is flattened, and (b) some of the soft-wrapped lines have been converted to code blocks. But this isn't the case in the direct lunamark output, which suggests there's some sort of pre-processing going before the contents of the text are even hitting the markdown processor.

This is with lunamark but I get similar results with the other markdown processors.

[elliottslaughter]

The problem is here: https://github.com/stevedonovan/LDoc/blob/f91c3182cf0b3ac29a8f677491aa32493067b5e1/ldoc/markup.lua#L177

The code is using regular expressions to preprocess code blocks (either with ``` or via indentation). If you change that (and the preceding check for fenced blocks) to if false then you get back the markdown processor's default behavior.

As best I can tell, the purpose of the prettifier seems to be for code highlighting. I can think of a couple possible solutions to this:

1. Switch to a markdown processor like Pandoc that has built-in support for code highlighting, so that this no longer needs to be done as an independent processing step.
2. Switch to a client-side code highlighting library.
3. Change the prettifier to a post-processing pass instead of a pre-processing pass. At least lunamark appears to spit out the code as <code> blocks, which do not seem too difficult to parse, assuming there's a readily available HTML parser you can use. Though there may be some differences between the HTML that the various Markdown processors produce, so that might be a sticking point.
4. At the very least, add an option to disable this prettification, so that users can choose what set of features they want (full-featured Markdown vs code highlighting).

[elliottslaughter]

I pushed a workaround here based on option (1) above. It would need a bit of CSS to get the code highlighting to show up in color, but otherwise it seems to be working. Not necessarily in a state I'd recommend merging, but it at least demonstrates that this can be done.

[elliottslaughter]

Ok, I pushed a workaround based on (4) to #326. This makes it possible to set pretty="none", which should work for any Markdown parser, but obviously disables syntax highlighting if it's not natively supported by the Markdown parser itself.