15 ms·

Compare AsciiDoc and Markdown

• 29athrowaway 5y ago
  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.
  • encryptluks2 5y ago
    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.
    • brospars 5y ago
      The core features are pretty much universal and used in a lot of apps (chats, forums, git repositories, project management). Custom flavors maybe not rendered correctly at times but this doesn't make documents unreadable
      • encryptluks2 5y ago
        The core features used in a lot of apps include different flavors, like GitHub Markdown and others. The closest thing you have to a unified Markdown is CommonMark and even that is forked for GFM. Yes, headers, bold and italics text, and lists are nice but there is a lot more to take into account when you are trying to supplement docs that other extensions add.
    • 29athrowaway 5y ago
      There are dialects of Markdown but they all respect the core features.
  • deleted 5y ago
    [deleted]
  • evacchi 5y ago
    true, but please notice that you can use asciidoc as a larger subset of md
    • 29athrowaway 5y ago
      Which is not something I want. If I wanted something more complex I would use TeX.
• taftster 5y ago
  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.
  • encryptluks2 5y ago
    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.
    • miohtama 5y ago
      Github already supports Restructured Text (reST) in READMEs, and some other markdown flavours. Do not know about AsciiDoc but looks interesting.
      • ygra 5y ago
        As can be seen here, GitHub renders Asciidoc just fine: https://github.com/asciidoctor/asciidoctor.js https://github.com/asciidoctor/asciidoctor.js
        • stock_toaster 5y ago
          Alas, no support[1] for include. [1]: https://github.com/github/markup/issues/1095 https://github.com/github/markup/issues/1095
• s9w 5y ago
  Can't be parsed by pandoc. As much as it may be the better format, that makes it unusable.
• reacharavindh 5y ago
  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.
  • timwis 5y ago
    Funny enough the GitHub file/issue editing UI handles drag and drop image uploading really well.
  • AlstZam 5y ago
    > What I’d like is a MArkDown Editor that also simply allows me to drag and drop images Have a look at Typora [0]. It's my main Markdown editor for this reason (and others). [0] https://typora.io/ https://typora.io/
  • chmike 5y ago
    Check this free markdown WYSIWYG editor https://marktext.app/ 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.
• jokoon 5y ago
  I've also used Textile https://textile-lang.com/ https://textile-lang.com/ But it's less supported, so I stopped using it.
• neetrain 5y ago
  The worst part of AsciiDoc I think is its name. It sounds so archaic.
  • rm445 5y ago
    It does tend to make one worry that all the tools will be hideously un-unicode aware and mangle any non-ASCII documents. I would like to imagine that in this day and age that isn't the case, but the name works against it.
    • oneeyedpigeon 5y ago
      Particularly when the syntax bakes in things like support for converting certain ASCII sequences into Unicode characters [0] [0] https://docs.asciidoctor.org/asciidoc/latest/text/quotation-marks-and-apostrophes/ https://docs.asciidoctor.org/asciidoc/latest/text/quotation-...
      • bloak 5y ago
        Yes, I finally got around to adding some "quail" stuff to my .emacs so that I can directly type various kinds of quotation mark and dash rather than rely on complex conversion rules that sometimes go wrong. The lack of first-class support for balanced quotation marks seems to be a major problem for computers. I think a lot of computer code, particularly scripts, would be easier to read and less buggy if the languages had been designed by someone with balanced quotation marks on their keyboard. As a thought experiment, imagine what Lisp would look like if '(' and ')' were the same character and you had to use the same work-arounds that shell scripts use for open quotation mark and close quotation mark being the same character. Instead of (a ((b c) d)) we'd write |a \|\\\|b c\\\| d\||. That's fine, right? We can live with that? Perhaps we should think ourselves lucky that 0 and O are not the same character, and 1 and l, like they were on the first mechanical typewriters. Mind you, there's one similar annoyance that predates typewriters and continues to plague us in Unicode: apostrophe and closing single quotation mark are logically quite different things, but they're the same character: ’
• thealistra 5y ago
  The funny thing is that on their page markdown has better syntax highlighting than their own markup language
  • gnull 5y ago
    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.
    • chmike 5y ago
      There is one for go which is my favorite language. And there is also one for python and javascript. Did you check ?
      • gnull 5y ago
        If you mean libasciidoc for Go, it does not support all the AsciiDoc features [1]. The JS parser is transpiled [2] from the Ruby implementation (which is not a bad thing, it's just something most languages can't have). My favourites are Rust and Haskell. Neither of them had a parcer until recently (even though the original implementation has been around for a few years now). Both are at early development stages at the moment. [1]: https://github.com/bytesparadise/libasciidoc/blob/master/LIMITATIONS.adoc https://github.com/bytesparadise/libasciidoc/blob/master/LIM... [2]: https://asciidoctor.org/docs/asciidoctor.js/ https://asciidoctor.org/docs/asciidoctor.js/
    • mogztter 5y ago
      The AsciiDoc Working Group has been formed to write a complete and comprehensive specification: https://asciidoc-wg.eclipse.org/ https://asciidoc-wg.eclipse.org/ If you are interested in an AsciiDoc processor in Haskell, you can read: https://www.tweag.io/blog/2021-06-15-asciidoc-haskell-pandoc/ https://www.tweag.io/blog/2021-06-15-asciidoc-haskell-pandoc... We had Guillem Marpons at the last AsciiDoc WG meeting and he was willing to work toward a spec-compliant implementation and help us with the spec.
• IfOnlyYouKnew 5y ago
  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: ----- Quote Quote -----
  • evacchi 5y ago
    You can use Markdown-style syntax as well https://docs.asciidoctor.org/asciidoc/latest/blocks/blockquotes/#markdown-style-blockquotes https://docs.asciidoctor.org/asciidoc/latest/blocks/blockquo...
  • qznc 5y ago
    If I remember it correctly the origin story is „Docbook as non-XML syntax“, so it really fell from the XML tree.
    • tannhaeuser 5y ago
      Actually, Docbook started as an SGML vocabulary and only in version 5 became XML-first. And SGML, as it relates to this thread, is a parser generator you can use to perform markdown-to-HTML conversion (including full HTML inlining), or AsciiDoc/rST or your own custom extension syntax to whatever XMLish angle-bracket markup you wish. So apologies, but considering we have SGML since 1986 or earlier, discussing surface syntax (markdown vs AsciiDoc vs rST vs orgmode or whatever) seems kindof moot and merely a matter of personal preference really.
• andix 5y ago
  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.
• submeta 5y ago
  While we are at it: Why not orgmode? It‘s much more versatile. But I still go back to markdown because everyone (and almost every tool I use) will accept it.
  • alpaca128 5y ago
    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.
    • JohnL4 5y ago
      2nd. I'm a heavy org-mode user but the problem w/org-mode is that it's got emacs in front of it, and you are just not going to get uptake. Pandoc's not really a solution, either, apart from a one-time extraction of org-mode to whatever other format is desired. As soon as you get multiple non-emacs editors, your pandoc trip is over.
• raspyberr 5y ago
  There's something about org-mode markup syntax that's really nice.
  • bloopernova 5y ago
    I use org-mode every day for organization and documentation in org-roam. I barely touch the text markup features though. Most of the time I don't mess with exporting either. (org-mode exports to LaTeX, HTML, or practically anything via pandoc) Have you written much using org-mode as a replacement for asciidoc/markdown etc? I should probably try to find some examples of longer-form org-mode docs and see if I can use those features.
  • dctoedt 5y ago
    For years I've been maintaining my course materials in org-mode and exporting to HTML each semester. I'm in the middle of consolidating the materials into a PDF book via LaTeX export for students to print out if they want. I really like the typeset look of the resulting PDF, even though there are no equations or formulas (I'm a part-time law professor). I'm doing just-in-time learning of the necessary LaTeX via Stack Exchange; it's crude, but effective. To be sure, the Emacs dependency is something of an entry barrier for org-mode. It helps that I've been using Emacs and various text formatters — Scribe, Final Word, and now pandoc — going back some 40 years.
• 0mp 5y ago
  FreeBSD has recently switched from DocBook to AsciiDoc for its documentation: https://docs.freebsd.org/en/books/fdp-primer/asciidoctor-primer/ https://docs.freebsd.org/en/books/fdp-primer/asciidoctor-pri... Markdown was also an option but it was missing too many features for a documentation set of this size.
  • Tomte 5y ago
    That's actually a likely switch, since AsciiDoc was specifically designed to optimally support Docbook features. So that switch should be painless.
• baby 5y ago
  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.
  • jokteur 5y ago
    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 ?
    • qznc 5y ago
      My guess: To convert it into an ebook.
      • baby 5y ago
        You can convert latex into ebooks I believe, it’s just completely overkill most of the time.
    • StevePerkins 5y ago
      LaTeX is pretty imposing for non-academic newbies. And if you're not writing a book that includes a bibliography or a lot of complex math equations, then it's arguably overkill. On the other hand, if you already know the gist of Markdown, then you could pick up reStructuredText or AsciiDoc in less than an hour. They're more feature-rich than markdown, without adding too much squeeze for the juice.
      • GordonS 5y ago
• dikei 5y ago
  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.
  • noname120 5y ago
    Have you considered using pandoc[1]? pandoc file1.md file2.md .... -o final.md or pandoc file1.md file2.md .... -o final.pdf [1] https://pandoc.org/ https://pandoc.org/
    • dikei 5y ago
      That's just concatenation though. Asciidoctor has very good support for `include`, so you can include a file in the middle of another file. Furthermore, you can even do partial include where you only include a section of another the file in the current file. I have setups where each of my files can work as a standalone document with proper Title and Appendix. These files can be compiled into another file where all the individual title are change to sub-title, and all the appendices are group together into one section.
• subpixel 5y ago
  “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.
  • MilStdJunkie 5y ago
    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.
• dkdbejwi383 5y ago
  Markdown's one of those special things that's good enough and simple enough. It doesn't do everything, but what it does do is easy to learn and use, and covers a large number of use cases.
• scoreandseven 5y ago
  Inline code was conspicuously missing in the comparison, which is more unwieldy in asciidoc (requires backtic and plus instead of just backtic). That’s probably the markdown feature I use most often.
  • mogztter 5y ago
    You only need to use backtic and plus when you want to disable text substitutions (a concept that does not exist in Markdown). Most of the time, using backtic is enough: `text`.
• happyflower 5y ago
  Comparing AsciiDoc to Markdown (instead of for instance reSructured Text/reST) is clever, but I don't think there's any widespread controversy about the shortcomings of Markdown. So that's just an easy win. I've seen this premise a lot (quoting from the article) »The most compelling reason to choose a lightweight markup language for writing is to minimize the number of technical concepts an author must grasp in order to be immediately productive.« What relevant documentation markup languages have this issue? If we already agree that documentation should be written as code, let's embrace it and not be scared of showing syntax. It's our tools that matter here - syntax highlighting, previewing, CI feedback. I see much more that people writing markup languages get extremely motivated from their first victories with coding something. Don't be afraid of showing people syntax -- Wikipedia got pretty far with a less-than-optimal markup language! I think the real issue with AsciiDoc is something more along these lines: https://xkcd.com/927/ https://xkcd.com/927/ I'm working in a large organization where we are failing to streamline and spread documentation practices because of many different standards and practices popping up everywhere. I like a lot how the Python community has centered around Sphinx and Read the Docs. It's great that for instance Sphinx support both Markdown and reST in that regards -- but then when things like Hugo/Docsy, AsciiDoc, Github Wikis, groovydoc etc. starts popping up, the unification of documentation practices in a large organization becomes harder -- and also of course across the specter of Open Source projects.
• igravious 5y ago
  I feel like this is the tech comparison equivalent of straw-manning. Take xrefs for instance. They say that the Markdown is: See [Usage](#_usage). <h2 id="_usage">Usage</h2> and that the AsciiDoc is: See <<_usage>>. == Usage 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-named-anchor-in-markdown https://stackoverflow.com/questions/5319754/cross-reference-... – 802 point answer saying to do this: 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?
  • mogztter 5y ago
    You can click the "Edit this page" button and submit an improvement. 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.
  • Symbiote 5y ago
    > 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. You can also use the Markdown-style indentation instead anyway: https://docs.asciidoctor.org/asciidoc/latest/lists/ordered/#nested-ordered-list https://docs.asciidoctor.org/asciidoc/latest/lists/ordered/#...
• deleted 5y ago
  [deleted]
• michaelcampbell 5y ago
  It always bothered me that these ascii processors don't use /for italics/. It just looks visually like italics.
  • wenc 5y ago
    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.
• lfmunoz4 5y ago
  I'm using markdown for 90 percent, then for the 10 percent use HTML
• icegreentea2 5y ago
  For the type of documentation that I do, I find that the single biggest win with AsciiDoc is it's table functionality. 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.
• jtth 5y ago
  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.
  • valarauko 5y ago
    I wrote my doctoral thesis (biology) this way (markdown + LaTeX + pandoc) and honestly, it was disappointing how much raw LaTeX I had to end up writing anyway. I had to rewrite all my tables & figures in LaTeX because it was easier than trying to figure out the odd layouts markdown + pandoc produced. If I had to do something of similar scale and complexity from scratch today, I'd look for a better solution.
• mikl 5y ago
  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 can be found at https://spec.commonmark.org/ https://spec.commonmark.org/
  • nerdponx 5y ago
    From what I remember, John McFarlane and his Pandoc project helped a lot in getting CommonMark adopted. Github used to have its own "Github-flavored Markdown" before CommonMark came along.
    • mikl 5y ago
      Correct, he (jgm on GitHub) is still by far the biggest contributor to the spec: https://github.com/commonmark/commonmark-spec/graphs/contributors https://github.com/commonmark/commonmark-spec/graphs/contrib...
  • blacktriangle 5y ago
    I'm not a Gruber fan but I think his actions in this case are totally defensible. Every month on HN there's a post about some OSS project mod stepping down due to abuse and insane expectations from the community. Gruber wrote a tool that solved his own personal problem, shared it with the world because why not, and then made damn sure he wasn't going to have to deal with any fallout put on him for his sharing.
    • mikl 5y ago
      Gruber did the exact opposite than stepping down. Even now, he insists on controlling the name “Markdown”, despite having abandoned the project over 15 years ago. It would be a bit like Tim Berners-Lee trying to police how people use “WWW” today. He might theoretically be within his legal rights, but he’d still be a jerk for doing so.
• castillar76 5y ago
  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.
• justshowpost 5y ago
  Honestly, I see both as abominations which didn't accomplish what they've been rooting for – a rich text with minimal burden. *strong* /italic/ _underline_ -strikeout-
• mrehler 5y ago
  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.