AsciiDoc is one of the underrated markup languages when Markdown is dominent.
I know everybody knows markdown and markdown is simple, but I have seen so many people who ended up with HTML hacks for more "advanced" features like image size/position, complex tables, and even comments.
I higly recommend trying AsciiDoc to people who needs more features than Markdown.
Also, it is much more PDF-friendly than Markdown so that you don't need weird renderer workarounds to print.
For what it is worth, GitHub supports rendering AsciiDoc. You just have to name your files .adoc I instead of .md
I do have to mention that sometimes advance features have tripped me and I have to spent some time figuring out why. I am sure the cli tools could use help and get better
Agreed. The ease of Markdown, but well structured and complete enough to write a whole book in it. I love it.
I've even fantasized about creating a new AsciiDoc mimetype, called AsciiWeb. It would be a subset of AsciiDoc that is relevant for browsing and would sit somewhere in the middle of Gopher or text browsing on one hand and the "normal" HTML/CSS/Javascript on the other. Very easy to create, suitable for minimal document browsing and structured enough that graphical clients can make it pretty and accessible. Oh wel.. one day I'll get to it.
This is a great idea. Implemented as a browser plug-in that transforms the AsciiDoc the user would control the document, instead of the server/host. Users could set their own fonts and styles, change accessibility, restructure the content, hide blocks/quotes, overlay other data or links, etc...
Changing who controls the content is a feature the web doesn't offer, except to technical people who can F12 to edit.
Considering that the original implementation of Markdown was a Markdown to HTML renderer, your claim that it's not meant to be rendered is a bit suspect.
They are not that different, are they? AsciiDoc looks just like an specific dialect of markdown.
Maybe a problem with AsciiDoc is that its name is scary. By the name "ascii" it seems to imply that there is a specific markup for typing non-ascii stuff, instead of simply typing the regular unicode characters (in whatever encoding).
Prevalence of Markdown is to a certain extent accidental. It is one of those many markup languages that are easy-enough to reimplement which helped with the spread and I think it was supported on Github early on.
Asciidoc is much more complex and so we only have 2 implementations around (a2x, asciidoctor).
I think it's an example of a phenomenon where there is a new-ish category of things, and that category is good, and there is one thing in that category that becomes well-known, so even though that thing is not the best in its category, it becomes wildly successful.
No, problem is the covered complexity. For Markdown I have never resort to any documentation - within its original scope. This is his big advantage and I appreciate this.
If you need more, you have almost certainly to look up things. This is true for AsciiDoc as well as for example ReST, the syntax of the former being a bit more appealing to me (just compare simple links for example) .
For this reason, I'm using a blogging system (Pelican) that supports all of them (including Pythons Markdown extensions). I'm completely free to apply the best suiting variant to the topics requirements.
Or reStructuredText, or Org-Mode : ) I think there are multiple great alternatives to markdown. Markdown is like the smallest common subset of features, that is never quite satisfying.
One of the biggest misses for asciidoc is that it's core libraries are ruby only. The javascript renderers are autogenerated and unmaintained.
This is also the reason why community uptake for asciidoc has been hard. Fundamentally we do not have any pastebin or hackmd for asciidoc.. because it is hard to build for it. Pastebin and hackmd have consistently refused to include asciidoc.
Momentum exists in the JAMSTACK space. Yet Gatsby and Nextjs play with markdown variants (MDX?) for markup. There are no asciidoc examples even in their repos .
Asciidoc is undoubtedly superior to markdown..and more importantly, is a well defined standard. But unless the core team engages with the ecosystem more, this is DOA.
I share your comment on tooling. At my former job we developed a documentation portal with Antora and AsciiDoc https://antora.org/ . I say developed rather than deployed as we ended up adding a ton of extra features to Antora (think authentication, authorizations, image previews, full-text search as you type, etc.).
Antora is quite nice and writing documentation in AsciiDoc was very enjoyable, but it was very clear how the JS implementation of AsciiDoctor was not on par with the Ruby one. We had multiple cases where the JS version would handle documents differently, or support a different feature set than the asciidoctor-cli. Moreover, the build times for the portal were extremely long (like 20-30 minutes for ~100 pages)
To write documents we all used VS Code + the Firefox/Chrome ASciDoctor preview plugin, and that worked much better than AsciiDocFx.
Going back I would probably suggest to look into other platforms, as the benefits of AsciiDoc are smaller than the amount of tooling frustrations.
Huh? The core/reference implementation was python-only. (Was python2-only for a while, actually--I helped change that.) Asciidoctor (ruby) is a prominent implementation, granted, but afaik there are quite a few other implementations in other languages.
Not so much. And the original Python variant is a) slowly growing old in features, b) the Python3 variants are unfinished and are missing support. I don't remember exactly in what respect, but I evaluated things some months ago and reluctantly installed the ruby gem of AsciiDoctor. I would have prefered a Python solution very much in my Python-driven environment. Also, a 'pip install asciidoc' would be very welcome.
I'm talking about where the momentum is. Sure I can use asciidoctor (through docker,etc)..but what I'm really talking about is the adoption in the wider ecosystem.
Which needs javascript, tooling, support,etc.
Asciidoc as a community has not gone down that path.
Dan Allen’s stewardship of AsciiDoctor — the most complete implementation of AsciiDoc available — is truly inspiring.
The level of documentation available and the amount of work that’s gone into the software is an enormous effort. Any missing-features or quirks I’ve googled have usually led to an existing GitHub issue that Dan is working on himself, with a carefully considered fix in the pipeline or an explanation as to how to implement the feature using the AsciiDoctor API.
AsciiDoc-the-standard is lucky to have a developer of his temperament and caliber, for his own work and for the way he encourages contributions from others.
I'm surprised that no publishers are included in the "Companies and Organizations" list. Asciidoc is a supported tool for Manning authors and probably others.
I just recently discovered Asciidot. I was browsing Micronaut's documentation and was impressed by it- how it allowed code lines/fragments to be annotated. Did some RE and discovered Asciidot. So far, I am pretty impressed. I hope more and more tooling will support it.
I love writing documentation in asciidoc (using asciidoctor actually). However I keep running into certain issues. For example, if a document includes pictures, and the file path has spaces in it, then you have issues. I believe you can replace spaces using HTML escapes if your output doc is HTML, however that falls apart if you want to make a PDF from the same source.
I'm also still trying to wrap my head around the presentation side. You can use something like style sheets, but it doesn't look like the same style sheets are compatible with both HTML and PDF output (if memory serves). And if you want to output to docx format, you can do it, but again the output looks different.
Another downside is that rendering larger documents to PDF will become incredibly slow. We have documented a REST API with AsciiDoc via Spring RestDocs and the build takes like 10 minutes for the PDF only. That doesn't include generating the snippets with RestDocs, which is rather fast. I suspect it has to do with AsciiDoctor being written in Ruby.
We use Dockbooker for technical documentation: https://github.com/l3nz/dockbooker and has been working well for a number of years. Builds PDF, EPUB and chunked-html very easily.
Is anyone aware of BiDi and-or Asian script support in AsciiDoc (or reStructuredText or Markdown ...)? I will likely need it in a coming project, and so far the only markup language that I've verified can properly do non-european-language layout is (ta dum!) HTML
The origins of AsciiDoc is informative. AsciiDoc is a lightweight successor to the XML DocBook format used originally to write O'Reilly computer books/manuals. Both DocBook and ePub XML add semantic elements required to describe book structure.
The Lightweight Markup Languages arose to avoid the tagsoup that is not author/writer friendly. There is a place for readable/writable content that is free of GUI editor requirements. I was once told that there is a right tool for every job.
I know everybody knows markdown and markdown is simple, but I have seen so many people who ended up with HTML hacks for more "advanced" features like image size/position, complex tables, and even comments.
I higly recommend trying AsciiDoc to people who needs more features than Markdown.
Also, it is much more PDF-friendly than Markdown so that you don't need weird renderer workarounds to print.