Compare AsciiDoc and Markdown
docs.asciidoctor.org
Compare AsciiDoc and Markdown
1–10 of 137 posts
Re: Compare AsciiDoc and Markdown
#2I 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.
Re: Compare AsciiDoc and Markdown
#3The 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.
Re: Compare AsciiDoc and Markdown
#4I 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 either at this point.
Re: Compare AsciiDoc and Markdown
#5The 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.
Re: Compare AsciiDoc and Markdown
#6I 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…
Github already supports Restructured Text (reST) in READMEs, and some other markdown flavours. Do not know about AsciiDoc but looks interesting.
Re: Compare AsciiDoc and Markdown
#7Can't be parsed by pandoc. As much as it may be the better format, that makes it unusable.
Re: Compare AsciiDoc and Markdown
#8Earlier quoted context omitted.
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…
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
Re: Compare AsciiDoc and Markdown
#9We 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.
Re: Compare AsciiDoc and Markdown
#10I 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 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).