On Mon, Jan 24, 2022 at 02:12:06PM +0100, Jonas Smedegaard wrote: > Personally I am of the opinion that more ideally such documentation > should be treated as a source format with two targets - html and > plaintext - and that both those target formats should be generated > during package build and installed with the binary package(s). > > For Github-flavored Markdown I recommend to render both target formats > using the command-line tool cmark-gfm. Here is an example of that: > https://salsa.debian.org/debian/doctest/-/commit/d9b848b > > For most other flavors of Markdown I recommend to render using pandoc. > Here is an example of that: > https://salsa.debian.org/js-team/twitter-bootstrap3/-/commit/f138bf1 > > For Gitlab-flavored Markdown there are currently no parser in Debian, > but depending on the actual markup used you might get away with pandoc + > a filter (but may then give up on rendering as plaintext). Here is an > example of that: > https://salsa.debian.org/matrix-team/olm/-/commit/094396d > > Feel free to reach out if you need help juggling Markdown or using > pandoc. I am no expert, but am interested, and am in touch with the > author if all else fails ;-)
I maintain "lowdown" in Debian. It supports several markup extensions including several from GFM and CommonMark, and can output in HTML5, roff (man/ms), LaTeX, ODF etc. It also has a terminal output mode, that can be used to format and view Markdown documents in a pager. Upstream is at https://kristaps.bsd.lv/lowdown/ and the package in Debian is just "lowdown". Upstream is very responsive, so if you miss a particular feature please file a bug (preferrably upstream, but I can also forward) It's written in plain C and has no dependencies apart from libbsd. That is of note, because pandoc is notorious for being hard to bootstrap (because of Haskell) and the only other alternative I had explored for my use case was ronn, which is in Ruby and thus also has a complicated dependency chain. (Depending on your package, you may or may not care about your build-dependency chain; I did.) Regards, Faidon 1: https://kristaps.bsd.lv/lowdown/