Hacker News Reader

Comment by chubot | Hacker News Reader

FWIW, I use a macro processor with markdown. Markdown supports arbitrary inline HTML, which makes it very convenient to use like this. You can create a macro for the warning box. I have another one to insert not just code snippets, but the result of running the code snippet.

I've used asciidoc before, and I don't recall it having arbitrary programmability? I'd be interested in how that works.

View on HN

Can you please elaborate on how exactly you create the macros? I started using asciidoc because I could not find a neat way of embedding code snippets (stored in separate file) into markdown text. Asciidoc has this as built in feature.

This is one of my favorite features, too. I've found it works amazing when you generate the documentation or render it locally. Unfortunately, it doesn't work in "safe" mode sites like GitHub or GitLab where having a lightweight include feature for samples or tests would be useful.

For macros in AsciiDoc, I've made do with the little bit of support mentioned at https://asciidoctor.org/docs/user-manual/#pass-macros . Everything I found for Markdown always required an additional tool or "something else". I like that AsciiDoctor, for the most parts, has nearly everything I want built-in.

I'm not suggesting this as the right solution, but I wrote a lot of assignments for my MSc with Markdown + build scripts + a heavy amount of Perl.

Variously this did things like running embedded unit tests in code examples, validating XSL schemas, making sure GraphViz images were created and up-to-date, running a Z-Notation type-checker, and code that created both SQL and Relational Algebra from a simplified SQL-like DSL.

I'm not saying this is a superior approach to AsciiDoc, just that it's amazing what you can create when you turn your mind to avoiding working on your MSc assignments and let your OCD about creating perfect assignments run wild.

I wrote a script which preprocesses the .md file, passes certain sections to shell scripts, and inserts the result of the script back into the .md file.

It's very much a Unix stdin-stdout thing. My whole blog [1] uses this, especially the code examples highlighted with pygments, and also links to the glossary, etc.

I dumped a snapshot here [2] awhile ago. It may or may not be of use if asciidoc already works for you.

The bad thing about this format is that it's not pure markdown anymore, so Vim syntax highlighting gets messed up sometimes. If I had to do it again, I would probably try to hook into a CommonMark [3] library to parse HTML blocks. So basically certain <div></div> blocks would get transformed into others.

How does asciidoc do it?

[1] http://www.oilshell.org/blog/

[2] https://github.com/oilshell/blog-code/tree/master/tools-snap...

[3] http://www.oilshell.org/blog/2018/02/14.htm

Reply on news.ycombinator.com