1. 17
  1.  

  2. 3

    asciidoc and rst are both popular and capable languages for writing documentation, I’m not sure why the author seems to dismiss them so readily.

    1. 3

      Where do I dismiss them? I think asciidoc is really nice. It’s a much better choice than md.

      1. 1

        Hmm, re-reading that I just got that kind of impression. They both just seemed to me like options you had looked at and dismissed. I think that FreeRADIUS does all it’s documentation as inline asciidoc, which means it’s really easy to change the documentation as you change the code.

        That’s the main problem I’m having with my documentation for terminator which lives in a separate repo so I don’t always remember to change it when I update the code, but I haven’t had any trouble with the RST formatting, though it did take me a while to get used to.

    2. 2

      What about mdbook?

      1. 1

        I’m a bit puzzled that there aren’t many extensible Markdown implementations out there, especially for the web. We have Pandoc, which is a fantastic achievement, and easy enough for a Haskeller to modify, but not quite accessible enough to people using web tech. The de-facto standard is markdown-it, but the source is a bit messy and there’s a lot of global state which makes it hard to predict how two syntax extensions might interact. It’s also focused on direct Markdown -> HTML conversion, whereas I would find it most useful to work with an intermediate AST.

        1. 3

          Then you’re in for a treat with the unified ecosystem! I’m using it for my (dormant) static site generator and it’s incredibly powerful. It uses a Markdown AST (MDAST) and an HTML AST (HAST) as intermediate formats.

          1. 1

            Wow, this looks great. I thought I had thoroughly scoured the web for markdown parser implementations looking for a good one, but somehow I missed this one. Thanks for sharing! I can’t wait to banish markdown-it from my package.json !