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.
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
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.
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:
mdpre came about before transclusion was widespread.
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.
I won’t claim to be an Asciidoc master by any means but I’m confused by the section headings requiring the trailing = signs e.g. = Section 1 = or == Section 2 ==. I’ve never written Asciidoc headings like that and as like Markdown it’s only at the beginning e.g. = Section 1 or == Section 2. The Asciidoctor Syntax guidance suggests the same Section Titles and Levels :: Asciidoctor Docs
Does anyone else have an opinion on this? I’m happy to try and modify/expand but I’ll have to admit my regex foo is pretty low.
Asciidoc aside for a moment (looking at the spec I agree with your assertion), the Markdown specification does include optional closing octothorpes on headings.
Right. I haven’t used closing octothorpes for headings - as they have real nuisance value when editing:
When I compose a slide I’m (obviously) using a heading for the slide heading. Often I’m plonking a graphic on the slide as well. Then I render the deck and think about what the title and the graphic say. A lot of the time I add text to the title. Positioning to the end is a single keystroke. Positioning to before the trailing octothorpes is additional bother.
(Now, though, I can add bullets below the title, with the graphic - so the problem is a little less severe. But I’m having a hard time getting used to this new freedom.)
All good points, however, when I download and use the Asciidoc syntax for Drafts 5 and set it active for the current document, headings are only styled as such if I add the trailing = symbols. It would be ideal if it worked with or without the trailing =.
I’ll fix that and implement some of the other comments on this thread next week. Definitely an example of a novice with the syntax not catching details. In my defense the AsciiDoc User Guide states:
One line titles consist of a single line delimited on either side by one or more equals characters.
From experience, neither asciidoc nor Antora tool chains require the closing equal characters. To be honest, I didn’t know the spec called for them, and I’ve never used them. Agree with making them optional in Drafts.
Oddly, I do use the closing octothorpe in Multimarkdown text, but mostly because my editor adds them automatically.
Same here with me.
I do not close the heading/title symbols because they are one line elements.
H1 is not repeated
Be aware of the h1/title synonym. There should be only one first level headin (if any) at the start of the document it will be stored as document-title attribute.
