I just wrote an entire book in asciidoc and honestly I don't like a lot of the decisions and the syntax, the tooling is also quite messy and hard to use/configure.
Having said that, I'm not sure if there's really any alternative. If you need the extensibility and diff-ability of asciidoc, then you're probably going to have to use it. If you don't need it, stick with markdown.
EDIT: so that people get an idea, I use asciidoc because it provides callouts, sidebars, captions, figures, cross references, LaTeX (via hard-to-use plugins), themes, fonts, etc. when converting to pdf or epub, etc.
RestructuredText (usually used within Sphinx) is the only alternative in the same class. Unfortunately there are hardly any comparisons. Maybe there are no people who have significant experience with both.
This question may be a bit naive, but it comes from somebody who has never used asciidoc but used a lot of LaTeX to make reports, poster, presentations, ...
Why are you using asciidoc to write a book, instead of LaTeX ? I see the advantage of using this for documentation, but for an entire book ?
I made a highly extensible markup language (inline macros, plugins, etc.) a while ago called Quaint[1] that I've been meaning to dive back into at some point. Out of curiosity, do you reckon it'd fit your use cases?
Did you do everything yourself? I'm wondering because I've always assumed that everybody you hand your book to down the line (editor and publisher) is going to want to use Word.
I really like AsciiDoc and would encourage anyone to give it a try, especially for things like software documentation (in all forms).
I very much despise the trend to write sharepoint or wiki/Confluence pages as a means for software documentation. I want my documentation to reside next to my source code, not at some obscure corporate URL.
The problem is simply that github, gitlab, and friends adopted Markdown and so it's got a heavy head start. Asciidoc is competing with small snippet documentation like README files written in Markdown and wiki pages in Confluence, Sharepoint, and the like. Asciidoc is pinched in the middle. I do hope it gets better adoption.
> I very much despise the trend to write sharepoint or wiki/Confluence pages as a means for software documentation. I want my documentation to reside next to my source code, not at some obscure corporate URL
There'd a middle-ish ground we're going with at work - you have the documentation alongside the code in git, and your CI/CD also uploads it to Confluence/whatever for less technical folks/searchability/etc.
( Tools used are Gitlab CI, mark and Confluence, but they don't really matter, the workflow does).
There is nothing really preventing GitHub and others from implementing a AsciiDoc/tor converter. AsciiDoctor is already written in Ruby, which is probably what they use on the backend for Markdown conversion. Hugo supports it as well, and I'm sure there are other static site generators. I agree 100% about documentation on Confluence or Sharepoint. Seriously, will not even work at a company that is heavily invested in either at this point.
> I very much despise the trend to write sharepoint or wiki/Confluence pages as a means for software documentation. I want my documentation to reside next to my source code, not at some obscure corporate URL.
It wouldn't be so bad if Confluence/whatever could just render the Asciidoc from the source repository. But they are generally closed systems. There's no way in or out of Confluence without significant headaches.
I have both a centralized Confluence instance and the documentation in GitHub. A GitHub action converts the markdown to Confluence to stay in sync. It's very handy, because developers like to document in markdown on GitHub, but business people tend to favor Confluence. One additional feature you get from this is the search over all repos, which doesn't work without additional tooling in GitHub.
One of the better, yet sad jokes, because it must have been one, was, when they announced "markdown support" in Confluence wiki, but barely any markdown worked. One has to ask oneself, who coded up that half-assed parser there, that manages to parse less markdown, than basically any half-serious markdown parser in any language, that I have ever used. Enterprise software for you.
Edit: Now that I think about it, the whole product palette of Atlassian seems to have issues making use of any decent markdown parser out of the myriads of parsers out there, that they could use. For example HTML in markdown on Bitbucket also does not properly work, so generating a table of contents is useless on Bitbucket as well.
The only reason there isn’t an official Markdown spec is that John Gruber blocked the effort at creating one. A bunch of people made a great spec that eliminates all the ambiguities and tried to make it “Standard Markdown”.
Gruber then threatened them with legal action (since he holds the copyright on the word Markdown and for some reason hates proper specifications), so they had to rename their spec “CommonMark”.
Most of the big Markdown-using services (GitHub, GitLab, Reddit, Stack Overflow, etc.) implement this spec, so it is basically the Markdown spec, all but in name.
“it also fulfills the objective of ensuring your content is maximally reusable”
This is a bit of a trap when it comes to teams chasing the goal of modular documentation.
AsciiDoc let’s you include other AsciiDoc files, so teams modularize content with the idea that all these modules are potentially reusable.
But unlike code which, say, might use a method that is available bc another file has been included/imported, an AsciiDoc include doesn’t reveal any of its content. It’s just a file name that will be replaced with the content of that file upon render.
This means you literally cannot read modularized content from source - you need to open up every included file and read each out of context.
Available tooling also presents previewed/rendered includes as if they are part of the parent document, which removes the ability to identify modularized content from the output.
In my experience this results in documentation that is modularized by diktat - usually after being authored in a Google Doc. Reuse never happens, in fact nobody but the author really knows what content was modularized in the first place.
The Conditional Content piece of 'component content" is one that's consistently ignored by every Big Iron vendor that I've ever talked to.
Which is 100% nuclear stupid, because, as you point out, you can't do component content without conditional content. And once you start doing conditional content, you need to have a damn good idea of what your whole product architecture looks like: what works with what, which packages are packages, obsolescence, blah blah blabbity blah. At industry conferences this makes me mad enough to spit, and all those goobers are suckering these writer teams into paying $7000 per person per (EDIT)month (!!) for a system that's going to be nothing but heartache in thirty six months.
Luckily, Asciidoc does have conditional directives, but the include directive is wayyyyy too primitive for what it's being used for right now (also as you point out). The `ainclude` directive is in extension right now, and it will probably be brought into core as a subdoc directive.
Having said that, it really is the best game in town, for generating both modern HTML alongside old-timey PDFs and DocBook XML, all from the same source.
Markdown's single best idea is that it is very readable "raw". While AsciiDoc is better than, say, html, it seems that's mostly a lucky accident because it's close to Markdown. Where it diverges, it looks like it fell from the XML tree.
Example:
.Lightweight Markup
NO THIS TEXT IS NOT LIGHT
Now, in fairness, Markdown doesn't have any methods to do that. But for quotes, Markdown gets it right:
> this is a quote
> and that's obvious
While AsciiDoc uses a block that doesn't have any meaning for the casual reader:
Markdown may be less precise from a technical perspective. But it is easier to use for most people and just good enough.
AsciiDoctor is a great framework for writing documentation and manuals. And there is also markdown support, so you can reuse/embed your existing documenentation.
The point of Markdown is having a very tiny set of features: headers, paragraphs, lists, links, pre-formatted text, etc. You can learn this in minutes.
Having Markdown with more features is against what makes Markdown useful: minimalism.
I disagree... Markdown is no longer a single unified version. There are multiple implementation, extensions, etc. The original Markdown spec by itself isn't that useful and there is a reason so many extensions have been made for it. It can maintain simplicity while still adding new features. Pandoc has some great examples of Markdown extensions that are really useful.
It's been a bit of a disappointment for me to discover that AsciiDoc's grammar is so complex that they didn't even describe it in a spec. Their spec is a collection of tests.
This must be contributing a lot to the adoption difficulty (at least for resource-limited open-source projects). There's a good chance you will not find an AsciiDoc parser library for your favourite programming language.
Take me to [pookie](#pookie)
<a name="pookie"></a>
I just switched my blog to Jekyll recently so I checked to see what Jekyll does to section headings under the hood (you most want to turn section headings into anchor points, no?) Turns out it automatically turns `<h2>Usage</h2>` into
<h2 id="usage">Usage</h2>
So clearly Jekyll does the right thing out of the box. Then all you have to do is:
See [Usage](#_usage).
somewhere else. What I'm getting at is this. Don't pretend your competitor is lamer than it is when doing comparison tables because it'll disincline people to check you out if they find out you've done that. You should steel-man your competitor and _still_ beat them. FWIW I think that Markdown (and its variants) always try to choose a syntax that aligns with how you'd write idiomatic non-HTML text-only styling. I mean compare the unordered and ordered list examples. Markdown chose right, AsciiDoc chose wrong. Objectively speaking, you'd choose the Markdown way naturally. I grant you, sometimes the choices are a little forced but what are you going to do, eh?
> I mean compare the unordered and ordered list examples. Markdown chose right, AsciiDoc chose wrong. Objectively speaking, you'd choose the Markdown way naturally.
In a trivial example, Markdown's syntax looks more natural. It might well be the more appropriate syntax for a short README, which expects to be read as plain text at least as often as rendered to HTML.
In real use, i.e. when editing a non-trivial example, AsciiDoctor's multiple-star/dot syntax makes it easier to keep track of things.
I much prefer Asciidoctor to Markdown when writing documents that's longer than a single A4 page, since it has the ability to combine multiple files into a single document if needed.
Yeah, as someone whose name contains non-ASCII characters, the association with ASCII is not exactly a positive one. I’ve wasted so much time dealing with data in non-Unicode encodings over my career that the mere word ASCII makes me want to punch something.
I also prefer .org files for anything. It does almost everything Markdown does with just as simple syntax, but then can be used for any more comprehensive purpose by being fully LaTeX compatible. Although I think this strong coupling with Emacs has unfortunately caused it to stay in that niche, even though most of those scripted interactions aren't really important for the common use-cases.
It also doesn't help that Emacs seems to be the only complete and correct parser; I tried org files as Readme in git repos, and for example Gitlab really struggles. Pandoc isn't fully compatible either.
I think it's because it's too ambiguous. Forward slashes are very common in written language (similar to apostrophes/single quotes), so users would a lot of escaping to do.
The thing with Markdown is that it does most of what you need to do with it, until it doesn't, when you can bring Pandoc to bear and put full-on LaTeX in your Markdown and it will render it however you want. I wrote a dissertation this way with inlined Rmarkdown code. It was great.
We use Dropbox Paper for team documents(not source code documentation). I actually like it.
The thing that makes MarkDown documents less appealing is the inability to handle images seamlesslessly(drag and drop). Most of the time, our documents involve images to explain stuff. Uploading them somewhere, and then manually adding a tag and correctly copy/paste the url in MD makes it less appealing that just drag & drop an image in a WYSIWYG editor and spending the focus on _documentation_.
What I’d like is a MArkDown Editor that also simply allows me to drag and drop images and it should handle uploading and linking the images transparently.
Check this free markdown WYSIWYG editor https://marktext.app/. I guess it is inspired by Typora which is the first I saw. It is very impressive. Not sure about the image drag and drop. That is app specific.
I wished we had that for ASCIIDoc because it looks more powerful than the half backed Markdown.
As someone who's spent the last several years maintaining a couple large, vaguely complex documents (CP-CPS documents for certificate authorities), AsciiDoc has been a winner. It's simple enough to be readable in git diffs and be updated by non-tech folks like managers, but supports enough features that doing things like tables, nested lists, and certificate structure notation to be workable. And it's WAY more manageable using git to build and publish to PDFs (using Pandoc) than trying to use Word docs.
As of today, there are so many incredible tools for Markdown — like Brett Terpstra’s Marked 2 and Christian Tietze’s Tableflip right off the bat — that make it so much more versatile. Obviously there are flaws, but if you find yourself working mostly in the same syntax all the time (I’m a MultiMarkdown man myself) it’s easy to make sure all your tools play well with one another.
[+] [-] baby|4 years ago|reply
Having said that, I'm not sure if there's really any alternative. If you need the extensibility and diff-ability of asciidoc, then you're probably going to have to use it. If you don't need it, stick with markdown.
EDIT: so that people get an idea, I use asciidoc because it provides callouts, sidebars, captions, figures, cross references, LaTeX (via hard-to-use plugins), themes, fonts, etc. when converting to pdf or epub, etc.
[+] [-] qznc|4 years ago|reply
[+] [-] jokteur|4 years ago|reply
Why are you using asciidoc to write a book, instead of LaTeX ? I see the advantage of using this for documentation, but for an entire book ?
[+] [-] breuleux|4 years ago|reply
[1] https://breuleux.github.io/quaint/index.html
[+] [-] criddell|4 years ago|reply
[+] [-] hutrdvnj|4 years ago|reply
[+] [-] taftster|4 years ago|reply
I very much despise the trend to write sharepoint or wiki/Confluence pages as a means for software documentation. I want my documentation to reside next to my source code, not at some obscure corporate URL.
The problem is simply that github, gitlab, and friends adopted Markdown and so it's got a heavy head start. Asciidoc is competing with small snippet documentation like README files written in Markdown and wiki pages in Confluence, Sharepoint, and the like. Asciidoc is pinched in the middle. I do hope it gets better adoption.
[+] [-] sofixa|4 years ago|reply
There'd a middle-ish ground we're going with at work - you have the documentation alongside the code in git, and your CI/CD also uploads it to Confluence/whatever for less technical folks/searchability/etc.
( Tools used are Gitlab CI, mark and Confluence, but they don't really matter, the workflow does).
[+] [-] encryptluks2|4 years ago|reply
[+] [-] globular-toast|4 years ago|reply
It wouldn't be so bad if Confluence/whatever could just render the Asciidoc from the source repository. But they are generally closed systems. There's no way in or out of Confluence without significant headaches.
[+] [-] Lunatic666|4 years ago|reply
[+] [-] zelphirkalt|4 years ago|reply
Edit: Now that I think about it, the whole product palette of Atlassian seems to have issues making use of any decent markdown parser out of the myriads of parsers out there, that they could use. For example HTML in markdown on Bitbucket also does not properly work, so generating a table of contents is useless on Bitbucket as well.
[+] [-] sa46|4 years ago|reply
I’ve had similar fun experience with Slack-ops when slack goes down.
[+] [-] mikl|4 years ago|reply
Gruber then threatened them with legal action (since he holds the copyright on the word Markdown and for some reason hates proper specifications), so they had to rename their spec “CommonMark”.
Most of the big Markdown-using services (GitHub, GitLab, Reddit, Stack Overflow, etc.) implement this spec, so it is basically the Markdown spec, all but in name.
It can be found at https://spec.commonmark.org/
[+] [-] subpixel|4 years ago|reply
This is a bit of a trap when it comes to teams chasing the goal of modular documentation.
AsciiDoc let’s you include other AsciiDoc files, so teams modularize content with the idea that all these modules are potentially reusable.
But unlike code which, say, might use a method that is available bc another file has been included/imported, an AsciiDoc include doesn’t reveal any of its content. It’s just a file name that will be replaced with the content of that file upon render.
This means you literally cannot read modularized content from source - you need to open up every included file and read each out of context.
Available tooling also presents previewed/rendered includes as if they are part of the parent document, which removes the ability to identify modularized content from the output.
In my experience this results in documentation that is modularized by diktat - usually after being authored in a Google Doc. Reuse never happens, in fact nobody but the author really knows what content was modularized in the first place.
[+] [-] MilStdJunkie|4 years ago|reply
Which is 100% nuclear stupid, because, as you point out, you can't do component content without conditional content. And once you start doing conditional content, you need to have a damn good idea of what your whole product architecture looks like: what works with what, which packages are packages, obsolescence, blah blah blabbity blah. At industry conferences this makes me mad enough to spit, and all those goobers are suckering these writer teams into paying $7000 per person per (EDIT)month (!!) for a system that's going to be nothing but heartache in thirty six months.
Luckily, Asciidoc does have conditional directives, but the include directive is wayyyyy too primitive for what it's being used for right now (also as you point out). The `ainclude` directive is in extension right now, and it will probably be brought into core as a subdoc directive.
Having said that, it really is the best game in town, for generating both modern HTML alongside old-timey PDFs and DocBook XML, all from the same source.
[+] [-] IfOnlyYouKnew|4 years ago|reply
Example:
Now, in fairness, Markdown doesn't have any methods to do that. But for quotes, Markdown gets it right: While AsciiDoc uses a block that doesn't have any meaning for the casual reader:[+] [-] evacchi|4 years ago|reply
https://docs.asciidoctor.org/asciidoc/latest/blocks/blockquo...
[+] [-] qznc|4 years ago|reply
[+] [-] andix|4 years ago|reply
AsciiDoctor is a great framework for writing documentation and manuals. And there is also markdown support, so you can reuse/embed your existing documenentation.
[+] [-] 29athrowaway|4 years ago|reply
Having Markdown with more features is against what makes Markdown useful: minimalism.
[+] [-] encryptluks2|4 years ago|reply
[+] [-] unknown|4 years ago|reply
[deleted]
[+] [-] evacchi|4 years ago|reply
[+] [-] thealistra|4 years ago|reply
[+] [-] gnull|4 years ago|reply
This must be contributing a lot to the adoption difficulty (at least for resource-limited open-source projects). There's a good chance you will not find an AsciiDoc parser library for your favourite programming language.
[+] [-] igravious|4 years ago|reply
Take xrefs for instance. They say that the Markdown is:
and that the AsciiDoc is: I mean, clear win for AsciiDoc, right? So I Google "cross reference" "markdown and get this SO post as the first hit: https://stackoverflow.com/questions/5319754/cross-reference-... – 802 point answer saying to do this: I just switched my blog to Jekyll recently so I checked to see what Jekyll does to section headings under the hood (you most want to turn section headings into anchor points, no?) Turns out it automatically turns `<h2>Usage</h2>` into So clearly Jekyll does the right thing out of the box. Then all you have to do is: somewhere else. What I'm getting at is this. Don't pretend your competitor is lamer than it is when doing comparison tables because it'll disincline people to check you out if they find out you've done that. You should steel-man your competitor and _still_ beat them. FWIW I think that Markdown (and its variants) always try to choose a syntax that aligns with how you'd write idiomatic non-HTML text-only styling. I mean compare the unordered and ordered list examples. Markdown chose right, AsciiDoc chose wrong. Objectively speaking, you'd choose the Markdown way naturally. I grant you, sometimes the choices are a little forced but what are you going to do, eh?[+] [-] Symbiote|4 years ago|reply
In a trivial example, Markdown's syntax looks more natural. It might well be the more appropriate syntax for a short README, which expects to be read as plain text at least as often as rendered to HTML.
In real use, i.e. when editing a non-trivial example, AsciiDoctor's multiple-star/dot syntax makes it easier to keep track of things.
You can also use the Markdown-style indentation instead anyway: https://docs.asciidoctor.org/asciidoc/latest/lists/ordered/#...
[+] [-] fiddlosopher|4 years ago|reply
[+] [-] mogztter|4 years ago|reply
Having said that, the fact remains that you don't have a standard syntax to add an id on a section title (without using HTML directly).
Jekyll might does the right thing but Jekyll is not Markdown. Does it work elsewhere? If not then your document is not really portable.
[+] [-] 0mp|4 years ago|reply
Markdown was also an option but it was missing too many features for a documentation set of this size.
[+] [-] icegreentea2|4 years ago|reply
Specifically the two things that are really nice is:
A) You can write out a table row over multiple lines. Default syntax/mode makes it really easy to do a cell per line.
B) You can embed (more) complex formatting easily into the table. So stuff like lists, block quote/code block, whatever.
[+] [-] raspyberr|4 years ago|reply
[+] [-] dikei|4 years ago|reply
[+] [-] noname120|4 years ago|reply
[+] [-] neetrain|4 years ago|reply
It sounds so archaic.
[+] [-] rm445|4 years ago|reply
I would like to imagine that in this day and age that isn't the case, but the name works against it.
[+] [-] Finnucane|4 years ago|reply
[+] [-] mikl|4 years ago|reply
[+] [-] submeta|4 years ago|reply
But I still go back to markdown because everyone (and almost every tool I use) will accept it.
[+] [-] alpaca128|4 years ago|reply
It also doesn't help that Emacs seems to be the only complete and correct parser; I tried org files as Readme in git repos, and for example Gitlab really struggles. Pandoc isn't fully compatible either.
[+] [-] michaelcampbell|4 years ago|reply
[+] [-] wenc|4 years ago|reply
[+] [-] jtth|4 years ago|reply
[+] [-] reacharavindh|4 years ago|reply
The thing that makes MarkDown documents less appealing is the inability to handle images seamlesslessly(drag and drop). Most of the time, our documents involve images to explain stuff. Uploading them somewhere, and then manually adding a tag and correctly copy/paste the url in MD makes it less appealing that just drag & drop an image in a WYSIWYG editor and spending the focus on _documentation_.
What I’d like is a MArkDown Editor that also simply allows me to drag and drop images and it should handle uploading and linking the images transparently.
[+] [-] AlstZam|4 years ago|reply
Have a look at Typora [0]. It's my main Markdown editor for this reason (and others).
[0] https://typora.io/
[+] [-] timwis|4 years ago|reply
[+] [-] chmike|4 years ago|reply
I wished we had that for ASCIIDoc because it looks more powerful than the half backed Markdown.
[+] [-] castillar76|4 years ago|reply
[+] [-] mrehler|4 years ago|reply