Re: generic viewer for md files
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/
Reply to: