AsciiDoc Example Syntax

I started on an example AsciiDoc syntax for Drafts to build on the new custom syntax support in v26.:

I admit to little familiarity with AsciiDoc and its conventions. I worked from the spec and sample documents, and implemented a skeleton set of features in the syntax that seemed at least to be a good start for someone more familiar to build a more complete version. Currently, it supports:

  • Navigation by == Section == style headings.
  • Highlighting of both multiline and single line sections.
  • .Block Titles
  • Emphasis using 'single quotes' or _underscores_
  • Constrained quotes like [attr]#text#
  • Bold using *asterisks*
  • Superscript using ^superscript^
  • Subscript using ~subscript~

If someone more familiar with the format wants to contribute feedback, or work on expanding the syntax, please comment.

1 Like

Cool ! Let’s improve it.
I use asciidoctor professionally for our company datasheets and fell in love with it.

The boxes (TIP: … ) should be done really on. They are important.

@technodad is a Asciidoc-user too.

1 Like

I’d love to know what benefits this has over MultiMarkdown, @Andreas_Haberle . If they are substantial I might use them in some places.

Does this help?

https://docs.asciidoctor.org/asciidoc/latest/asciidoc-vs-markdown/

1 Like

While I prefer Multimarkdown for daily use, AsciiDoc syntax really comes into its own when you are writing large documents, books, or sets of documentation. In those uses, AsciiDoc is much stronger on control over structure, and especially on cross-document linking.

Here’s the GitLab example of a book I helped develop using AsciiDoc. This illustrates another cool feature of AsciiDoc, specifically it fits very well into DevOps tool chains so you can develop a book using modern source control tools. My organization is investigating use of the Antora tool chain to produce heavily cross-linked standards documents.

So, to being this back to Drafts a bit, we should take a look at adding syntax highlighting for the various cross linking syntaxes in AsciiDoc e.g.,:
[[anchor-1]]
Paragraph or block 1

anchor:anchor-2[]
Paragraph or block 2

<<anchor-1>>
<<anchor-1,First anchor>>
xref:anchor-2[]

xref:anchor-2[Second anchor]

2 Likes

So the differences aren’t massive. I appreciate the transclusion benefit - but I do that (and more) with mdpre (in my non-Drafts work and could add an automation to Drafts to make it work - if I wanted to).

Indeed, the language differences aren’t massive until you actually need to create a book or other strongly-structured document, where AsciiDoc’s large and standardized variety of controls win out.

That said, I write in Multimarkdown multiple times a day, and AsciiDoc only when I have a specific writing assignment. I regularly use transclusion in my Multimarkdown documents- but the syntax is mustache code instead of mdpre =include syntax - underscoring the whole Markdown “whack-a-mole” syntax problem in tool chains.

2 Likes

I would point out that Markdown is designed by an author/journalist of a blog (I know - originally) but was never uplifted to a real technical language.

There are attempts but they are not very promising - as far as I monitor them.

more abou asciidoc

restructured text (rst) and asciidoc were created for a technical use case and have been implanted deeply in some communities - sadly rust was not brave enough to embrace it for their core documentation language.

As multimarkdown and other tools like mdpre try to patch the missing links in markdown. Asciidoc and Asciidoctor comes fully equipped with an extension system and a much enhanced basic set of features.

Variables and include files two important ones. (both features that mdpre has started to implement) Another one is tables from csv files.
Another topic that @martinpacker has a nice tool for.

beside the already named cross reference features there is a native table of content generation.

Another core benefit is the pdf generation based on the Prawn library in ruby. (This needs a ruby 2.x based build system). Completely with a theming engine (yaml based).

There is a great helpful community too. (does anybody now of a multi markdown community)

I would point out that the syntax in drafts will not give the full adoc feeling- but let’s see what the first sparks may bring.

I will post a link to a public github repository to create the syntax and themes. There will be some fancy examples too.

This is going to sound defensive and I don’t mean it to be but I thought I should make a couple of points:

  1. mdpre came about before transclusion was widespread.
  2. It’s what I would call a preprocessor. Hence the name. So it has conditional logic, variables, the ability to generate a TOC, ability to turn CSV data into Markdown tables. It’s not a Markdown renderer as such.

For me, it’s part of my daily workflow.

But, I agree, it illustrates the “Markdown Diaspora” point.

1 Like

I would say it points to the gaps in markdown.
And that Asciidoctor/asciidoc is covering those gaps.

As you rightly call mdpre a preprocessor, asciidoctor has one build in.

1 Like