Hacker News Board Hacker News, browsed like a classic message board
Live data from Hacker News

Compare AsciiDoc and Markdown

docs.asciidoctor.org

Post reply on HN
Print view View original

21–30 of 137 posts

Re: Compare AsciiDoc and Markdown

#21

Post by IfOnlyYouKnew »

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
    -----

Re: Compare AsciiDoc and Markdown

#22

Post by toastal »

encryptluks2 wrote: post #4
taftster wrote: post #2

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…

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…

GitLab also support AsciiDoc.

SourceHut unfortunately does not. You can go through the hoops of POSTing to its GraphQL API from CI a new README from any format to HTML.

Re: Compare AsciiDoc and Markdown

#23

Post by evacchi »

29athrowaway wrote: post #3

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.

true, but please notice that you can use asciidoc as a larger subset of md

Re: Compare AsciiDoc and Markdown

#24

Post by evacchi »

IfOnlyYouKnew wrote: post #21

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…

You can use Markdown-style syntax as well

https://docs.asciidoctor.org/asciidoc/latest/blocks/blockquo...

Re: Compare AsciiDoc and Markdown

#25

Post by andix »

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.

Re: Compare AsciiDoc and Markdown

#28

Post by chmike »

gnull wrote: post #20
thealistra wrote: post #18

The funny thing is that on their page markdown has better syntax highlighting than their own markup language

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.

There is one for go which is my favorite language. And there is also one for python and javascript. Did you check ?

Re: Compare AsciiDoc and Markdown

#29

Post by alpaca128 »

submeta wrote: post #26

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.

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.

Re: Compare AsciiDoc and Markdown

#30

Post by chmike »

reacharavindh wrote: post #9

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 a…

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.

Post reply on HN