What is the proper way to ‘transpile’ Markdown to HTML?
I know there are static site generators out there, this has already been done, etc. I’m curious about the best way to do it, and if you can, pointing me to an example.
If you want proper as in “canonical”, John Gruber’s original is your best choice. It is effectively the definition of markdown. But markdown has moved on beyond Gruber’s original vision, mostly without him. Still, his original vision in collaboration with Aaron Swartz is still very usable, especially for blogging.
Once you move beyond the original Perl code, you have numerous choices. Here are a few:
And there’s no shortage of online converters and other versions.
I’ve used pandoc for years. It doesn’t just convert markdown to html. It converts from multiple formats to multiple formats, including various slide formats as well as PDF. It supports Python and Haskell scripts, as well as Lua scripting. The Lua scripting is very interesting because it manipulates the AST in memory as opposed to Python and Haskell where pandoc marshalls the AST to a JSON representation, pipes it to the script, and then receives the output.
Lowdown is interesting because it’s a fork of hoedown. @kristaps went through it and added a proper AST representation internally as well as pledge and privilege separating it. He doesn’t expose the AST (yet?), but it’s fast and efficient.
Multimarkdown is a good choice if you want to stay in Markdown but target more than one output format. Like pandoc, mmd can export to several slide formats and pdf by way of LaTeX.
Lastly, the lua and awk versions are noted above because I like little languages that do so much. ;-)
For most of what markdown was originally designed for, text files converted to HTML, you almost can’t go wrong. Where you’re going to find your choices both expanded and somewhat complicated is when you move beyond basic markdown and start trying to write slides, documentation, books, or use add-on features like tables.
I’d suggest start with basic markdown as described on Gruber’s Markdown page, pick one of the simpler converters like his Perl script, and see whether you need anything beyond that. Then look at Pandoc and Multimarkdown. If you don’t need more features but want more speed, then look at Lowdown.
since you tagged this with C++, I’m assuming you are familiar/would like to use to C++, in that case, CommonMark written in C, by the same author as Pandoc should be of interest to you.
Pandoc has served me well for the basic variants of this problem.
thanks! I’ll check it out.
If you want proper as in “canonical”, John Gruber’s original is your best choice. It is effectively the definition of markdown. But markdown has moved on beyond Gruber’s original vision, mostly without him. Still, his original vision in collaboration with Aaron Swartz is still very usable, especially for blogging.
Once you move beyond the original Perl code, you have numerous choices. Here are a few:
And there’s no shortage of online converters and other versions.
I’ve used pandoc for years. It doesn’t just convert markdown to html. It converts from multiple formats to multiple formats, including various slide formats as well as PDF. It supports Python and Haskell scripts, as well as Lua scripting. The Lua scripting is very interesting because it manipulates the AST in memory as opposed to Python and Haskell where pandoc marshalls the AST to a JSON representation, pipes it to the script, and then receives the output.
Lowdown is interesting because it’s a fork of hoedown. @kristaps went through it and added a proper AST representation internally as well as pledge and privilege separating it. He doesn’t expose the AST (yet?), but it’s fast and efficient.
Multimarkdown is a good choice if you want to stay in Markdown but target more than one output format. Like pandoc, mmd can export to several slide formats and pdf by way of LaTeX.
Lastly, the lua and awk versions are noted above because I like little languages that do so much. ;-)
For most of what markdown was originally designed for, text files converted to HTML, you almost can’t go wrong. Where you’re going to find your choices both expanded and somewhat complicated is when you move beyond basic markdown and start trying to write slides, documentation, books, or use add-on features like tables.
I’d suggest start with basic markdown as described on Gruber’s Markdown page, pick one of the simpler converters like his Perl script, and see whether you need anything beyond that. Then look at Pandoc and Multimarkdown. If you don’t need more features but want more speed, then look at Lowdown.
lowdown does have its library exposed! pkg_add lowdown, man 3 lowdown.
Thanks for the detailed answer!
since you tagged this with C++, I’m assuming you are familiar/would like to use to C++, in that case, CommonMark written in C, by the same author as Pandoc should be of interest to you.
cmark codebase
exactly. I was wondering if someone would notice (maybe others did but didn’t say anything). Thanks!
Did you find anything wrong with the static site generators? They tend to work really well.
Nothing wrong at all! I just want to build one for the fun of it, mostly