search

40ants / doc

Flexible documentation generator for Common Lisp projects.
https://40ants.com/doc/
Other
17 stars 6 forks source link

Nested Markdown lists get flattened in generated HTML #17

Open mathrick opened 2 years ago

mathrick commented 2 years ago

Nested Markdown lists result in incorrect HTML generated, which puts them all at the same level, unless there is a switch between ordered and unordered lists, in which case they're properly nested. Repro:

(defsection @repro (:title "Incorrect HTML generated from Markdown")
  "Consider this list:

- Item 1
- Item 2
  - Subitem 1
  - Subitem 2
- Item 3
  * Subitem 3
    + Sub-subitem 1
      1. Sub-sub-subitem 1
      2. Sub-sub-subitem 2")
CL-USER> (40ants-doc/builder:update-asdf-system-docs clutch/docs::@repro :clutch)
 <INFO> [18:44:10] 40ants-doc/highlight highlight.lisp (download-highlight-js) -
  METADATA file lists same languages and theme. Skipping download of Highlight.js
#P"/home/mathrick/Dev/clutch/docs/"
#P"/home/mathrick/Dev/clutch/docs/repro/index.html"

This results in the following output: flattened-list

mathrick commented 2 years ago

Actually, I think I misread the output slightly; it's not the the ordered / unordered switch that makes it actually nest the output, it's either sufficient level of nesting, or the use of + as the bullet, since sub-subitem 1 and sub-sub-subitem 1 are rendered at the same level.

mathrick commented 2 years ago

Some more testing suggests it's "sufficient amount of nesting" that makes it work properly, and the "sufficient amount" is actually determined by the level of indentation in the source Markdown. This for instance renders properly:

- Item 4
     + Subitem 4

Resutling in: deep indent

svetlyak40wt commented 2 years ago

This problem is caused by incorrect nesting handling in the underlying Markdown parser 3bmd:

Same way it requires additional indentation for code blocks inside list items. I've created an issue on this problem a year ago: https://github.com/3b/3bmd/issues/45

Also, I've even created a comprehensive test-suite for checking regressions during 3bmd fixes: https://github.com/3b/3bmd/pull/46

But seems it's author to busy to support this library :(

svetlyak40wt commented 2 years ago

I'd like to use a Common Mark compatible parser, extensible and able to return document pieces as common lisp objects. But I didn't find such library for Common Lisp yet.