Markdown's Big Brother: Say Hello to AsciiDoc

1. Crafting Interpreters

   1 53 9,554 3.3 HTML

   Repository for the book "Crafting Interpreters"

   

   > If you’ve been relying on Markdown and occasionally fighting its quirks, AsciiDoc might be the structured, fully-featured alternative you didn’t know you needed.

   No, I'm afraid it's the format I know I don't need. At least not for the kind of things I usually use markdown for.

   Readme files, technical documentation, moderately complex websites with templating and rendering engines - markdown works just fine. Sometimes with a custom `|||warning\n...\n|||\n` thrown in to render something in a box with a red border.

   I get that there's a market in the space occupied by TeX, Typst (underrated IMHO), and possibly MS Word or Quark Express (for non-techies). Libreoffice is great in theory but, again IMHO, "eh" in practice. That market is generating book-length documents with all the cross-references and other features that needs.

   That said, Robert Nystrom of "Crafting Interpreters" managed this just fine with markdown and a few custom scripts: https://journal.stuffwithstuff.com/2020/04/05/crafting-craft... , https://github.com/munificent/craftinginterpreters/tree/mast... . This is how those famous 10x writers/programmers work, I guess.

   Asciidoc is Markdown's big brother? I'll carry on playing with the little brother, thank you very much.

   Also the whole page is an ad for their own editor tool. $9.99 per month so you don't need to use your own editor and unintuitive tools like (gasp!) the terminal.

2. CodeRabbit

   coderabbit.ai featured

   CodeRabbit: AI Code Reviews for Developers. Revolutionize your code reviews with AI. CodeRabbit offers PR summaries, code walkthroughs, 1-click suggestions, and AST-based analysis. Boost productivity and code quality across all major languages with each PR.

   

3. Asciidoctor

   2 38 4,950 7.3 Ruby

   :gem: A fast, open source text processor and publishing toolchain, written in Ruby, for converting AsciiDoc content to HTML 5, DocBook 5, and other formats.

   

   The problem with asciidoc is that it doesn't support nesting. Markdown allows you to nest constructs as much as you want using syntax that are easy to use for both humans and documentation-generating applications.

   The asciidoc developers don't seem to consider this an important issue: https://github.com/asciidoctor/asciidoctor/issues/1121

   While asciidoc has some nice constructs, this made it a no go the last time I was looking for a documentation language.

4. typst

   3 144 38,441 9.8 Rust

   A new markup-based typesetting system that is powerful and easy to learn.

   

   We could be using html based DSLs and powerful importable components instead of special characters. Monaco (VSCode editor framework) allows frontend devs to make special DSL editors with autocomplete for both desktop and web. Between Spectacle and Typst approaches, I would choose Spectacle.

   I read the 2003 book The art of Unix programming where the author praises plain text config and says hand editing xml is a human rights violation, since Notepad was the most powerful ubiquitous editor then. Markdown was best then.

   https://commerce.nearform.com/open-source/spectacle/docs/api...

   https://typst.app/

5. markdoc

   4 23 7,439 5.2 TypeScript

   A powerful, flexible, Markdown-based authoring framework.

   

   Markdoc (https://markdoc.dev/) really had me excited, but I'm not sure it aspires to be all that I hoped it would.

Suggest a related project