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

11–20 of 137 posts

Re: Compare AsciiDoc and Markdown

#11

Post by Lunatic666 »

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…

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.

Re: Compare AsciiDoc and Markdown

#12

Post by stock_toaster »

ygra wrote: post #8
miohtama wrote: post #6

Earlier quoted context omitted.

Github already supports Restructured Text (reST) in READMEs, and some other markdown flavours. Do not know about AsciiDoc but looks interesting.

As can be seen here, GitHub renders Asciidoc just fine: https://github.com/asciidoctor/asciidoctor.js

Alas, no support[1] for include.

[1]: https://github.com/github/markup/issues/1095

Re: Compare AsciiDoc and Markdown

#14

Post by timwis »

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…

Funny enough the GitHub file/issue editing UI handles drag and drop image uploading really well.

Re: Compare AsciiDoc and Markdown

#15

Post by AlstZam »

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…

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

Re: Compare AsciiDoc and Markdown

#17

Post by brospars »

encryptluks2 wrote: post #5
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.

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.

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

Re: Compare AsciiDoc and Markdown

#19

Post by [deleted] »

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.

[deleted]

Re: Compare AsciiDoc and Markdown

#20

Post by gnull »

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.

Post reply on HN