4 ms·

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 i

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.

peteretep 8y ago
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.
mkobit 8y ago
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 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.
chubot 8y ago
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/ http://www.oilshell.org/blog/ [2] https://github.com/oilshell/blog-code/tree/master/tools-snapshot https://github.com/oilshell/blog-code/tree/master/tools-snap... [3] http://www.oilshell.org/blog/2018/02/14.htm http://www.oilshell.org/blog/2018/02/14.htm

peteretep 8y ago

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.

mkobit 8y ago

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 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.

chubot 8y ago

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/ http://www.oilshell.org/blog/ [2] https://github.com/oilshell/blog-code/tree/master/tools-snapshot https://github.com/oilshell/blog-code/tree/master/tools-snap... [3] http://www.oilshell.org/blog/2018/02/14.htm http://www.oilshell.org/blog/2018/02/14.htm