Asciidoc(tor) and why Markdown users consider it

Do not get me wrong Markdown is a great way to format text and write articles.

But if you go deeper, you will find its limitations.

For documentation and knowledge management you will miss some basic features that are very obvious like footnotes and info boxes or even variables, snippets (text blocks) and including other documents or graphs.

Even extensions like Git Flavored Markdown are a first step but are not visibly moving further.

Commonmark tries to create a base for extending markdown but as far as I read it is kind of stuck.

There is a standard called ascidoc, that was adopted by the ruby community and enhanced as the asciidoctor standard. If you use a non mobile operating system (OS) you will able to set up a ruby based or nodeJS based workflow to get all these and more features inside your markup text document.

I looked into it and fell in love with it.

why do I put it here?

Because Drafts soon will be able to define own syntax highlighting capabilities for the users and I hope to stirr up some fellow users that would like to use asciidoc inside drafts.

A small side note: asciidoctor adds the basic markdown syntax to its specification so that you can easily use your already written markdown inside its eco system.

So look at it and report back on this thread if it is to your liking or if you think I am wrong…


Just be mindful that one of the main reasons many people use Markdown is because of the proliferation of tools that can work with it and transform it. Drafts has engines built-in allowing for transformation to HTML, many web CMS’s support it, it’s a staple for tools like Shortcuts and Pandoc. Markdown is a bit of a lingua franca in that respect. In fact I suspect that the majority of users simply don’t hit that much in the way of limitations, and those that really do hit them probably turn to adding in HTML (including MathJax, etc.) or jumping to the do whatever you need LaTeX (note that MultiMarkdown does officially have some LaTeX aspects to it too of course).

While the syntax options that are planned to come to Drafts will allow you to make working with the text that much easier, do be aware that unless you also port over/link up some tools that are compatible with Drafts to do any transformations for things like changing document types, web previews, etc. you could end up with a poorer experience in Drafts using a richer syntactic structure. Setting up a node server to support it is certainly a bit of a barrier for entry, and as you noted, you would then be limiting yourself to making use of the workflows when on the Mac, and accepting more constrained when on iOS/iPadOS. I suspect it is not an insurmountable task to create something that would bring the benefits cross-platform, but the question then becomes how much effort, or can you simply get by with having the lesser experience on iOS/iPadOS. Will it matter to people? I don’t know.

I’m certainly interested to see how this pans out.

Good luck :+1:t2: :grinning:

1 Like

found the Drafts: Exploded Markdown Preview | ThoughtAsylum and it’s corresponding TADpole actions

That’s in the direction of asciidoctors power (include other files/drafts)

Thank you @sylumer