Our great sponsors
-
Asciidoctor
: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.
-
WorkOS
The modern identity platform for B2B SaaS. The APIs are flexible and easy-to-use, supporting authentication, user identity, and complex enterprise features like SSO and SCIM provisioning.
-
pagliascii
Due to reasons I am unable to follow up to this project, see the linked gist if you are interested in taking over the project instead.
-
-
-
InfluxDB
Power Real-Time Data Analytics at Scale. Get real-time insights from all types of time series data with InfluxDB. Ingest, query, and analyze billions of data points in real-time with unbounded cardinality.
-
pandoc-latex-admonition
A pandoc filter for setting admonition on specific div or codeblock elements
-
github-orgmode-tests
This is a test project where you can explore how github interprets Org-mode files
For extending markdown capabilities, there are many plugins/filters. Example [1].
I remember using extensions/filters for citations, etc.
Ultimately it is just some custom tooling around pandoc; so whatever you can do in pandoc, you can get done in the book.
[1] - https://github.com/chdemko/pandoc-latex-admonition
[2] - https://pandoc.org/
AsciiDoc is so close to being good. It slam dunks Markdown, but they just have a few nagging issues that they refuse to fix, for 9 years now:
https://github.com/asciidoctor/asciidoctor/issues/1087
If you like AsciiDoctor, another option to take a look at is https://djot.net/.
I love AsciiDoc and want to use it more. The main problem is, as noted, that it's hard to get this ruby library into whatever platform you want to deploy to. Consequently it's hard to build tooling based on AsciiDoc.
I've had a brief play with trying to implement AsciiDoc in Rust (and others have too, see https://github.com/Veykril/pagliascii). I got bored of trying to figure out what the semantics should be by reading the implementation and decided to wait until the upcoming specification effort at https://asciidoc-wg.eclipse.org/ bears fruit, the Zulip seems a bit more active recently
The problem I have with AsciiDoc (AD) and Markdown (MD) is that they are too effective (in the best way)! Follow my reasoning for a moment, please...
I was reviewing a command-line MD reader today. I think it was the nth time I've looked it over. It's called glow : https://github.com/charmbracelet/glow
I always come to the same conclusion. I don't need it. I don't need to remember to use (yet) another command line program to read MD or perform a very specific (and non-vital) function.
The reason is that MD and AD are so very easy to read. They are too effective at their jobs. They aren't like HTML tags that get in the way of the text. You barely even notice MD/AD in most(?) cases. Text plus MD/AD are incredibly easy to read without a 3rd-party program "rendering" the results.
Having said that... the only time I got really excited about MD/AD was when there was a post about Textual Markdown : https://news.ycombinator.com/item?id=34028765
It wasn't that the "rendered" text looked great (it looked beautiful, btw) but I could see 'Textual Markdown' turning into a command-line, online browser just for MD text! Think about that...
I even thought about how great it would be if the GeminiSpace folks : https://en.wikipedia.org/wiki/Gemini_(protocol)?useskin=vect... : embraced MD/AsciiDOC instead of their limited markup language.
It's exciting to think of MD/AD making themselves an alternative lightweight tagging system on the web. Exciting to think about a lightweight web in general - no tracking, adware, tons of JS, etc...
Exciting to think about a bunch of browsers growing out of this (ie; you don't need billions/yr to support MD/AD browsers) - from full-blown GUIs to, well... "Textual-Markdown".
Anyway... MD/AD would be great if it grew beyond offline use. For offline use only... you really don't need rendering. Maybe it helps a bit with really long files but otherwise...
I've written a ~300 page book in MD using book-template [1], and I must say, it was a wonderful experience. I did 1 chapter = 1 file. It had tables, images, etc with a nice TOC along with references and appendix. All the basics for writing a book work just fine with md, I'd say.
[1] https://github.com/alessandrocucci/book-template
For extending markdown capabilities, there are many plugins/filters. Example [1].
I remember using extensions/filters for citations, etc.
Ultimately it is just some custom tooling around pandoc; so whatever you can do in pandoc, you can get done in the book.
[1] - https://github.com/chdemko/pandoc-latex-admonition
[2] - https://pandoc.org/