Add to Chrome
Add to Edge
Add to Firefox
Add to Opera
Add to Brave
Add to SafariWhen comparing Markdown vs AsciiDoc, the Slant community recommends Markdown for most people. In the question“What are the best markup languages?” Markdown is ranked 1st while AsciiDoc is ranked 4th. The most important reason people chose Markdown is:
Designed to be easy for a human to enter with a simple text editor, and easy to read in its raw form.
Question Ranking
Pros
Pro Human-readable
Designed to be easy for a human to enter with a simple text editor, and easy to read in its raw form.
Pro Widely used
Markdown is quickly becoming the writing standard for academics, scientists, writers, and many more. Websites like GitHub and reddit use Markdown to style their comments.
Pro De facto standard
Markdown is ubiquitous. It's supported by nearly everything. The markup available in the common subset of all the many dialects isn't that rich, but it's usually enough to get the job done.
Pro Multi-directional
You can convert HTML to Markdown or Markdown to HTML. You can use tools like pandoc to convert to other formats as well.
Pro Revision friendly
It is easy to track changes for markdown documents as compared to other formats like doc, html, etc. You only need to place your markdown documents under some version control system.
Pro Standardized format
The formatting of Asciidoc is standardized so there is only one 'flavor' unlike in Markdown. The definitive user guide is here.
Pro Human-readable
Simple, easy-to-read style similar to Markdown. Designed to be easy for a human to enter with a simple text editor, and easy to read in its raw form.
Pro Technical Documentation
The DocBook format which Asciidoctor can convert to was originally developed with the creation of computer books in mind and thus has a rich array of formatting options which are powerful enough to manage the formatting of lengthy technical books.
Pro Supported by GitHub and GitLab
Both GitHub and GitLab support AsciiDoc syntax in repositories, wikis and Gists/Snippets (powered by the Asciidoctor Ruby gem).
Pro It's structured
Cleanly transforms to DocBook and HTML5.
Pro Supports semantic markup
Pro Native support for colored output
AsciiDoc has offered the ability to define both the color of any text output as well as its background, almost since its inception. It accepts several standard chromatic notations for them, too, including hexadecimal and decimal RGB values, decimal HSL and named CSS.
Pro Embedded metadata
The AsciiDoc standard defines a number of metadata values which can be defined inside a document primarily for contextual purposes that aren't rendered in its standard output such as author, date, license, document title and version, etc. These can be especially useful when searching through a large number of files/documents or documenting the evolution of one as part of a larger codebase.
Pro Shorter, more concise than Markdown
Pro Good tool support
There are plugins to support editing AsciiDoc for many editors/IDEs.
Cons
Con Lacks a coherent standard
Lacks a coherent standard, just many semi-compatible dialects (MultiMarkdown, etc). This inconsistency can cause problems if the person writing the Markdown is using a different dialect from the one that will be used to render it.
Con Bad support for table
It has poor support for table, while table is an important part of article.
Con Bad support for larger documents
Works good for single file documents like READMEs.
Lack support for cross-references, TOCs, document index etc.
Con It doesn't support semantic markup
It's unstructured.
Con Not as popular/widely used as Markdown
The Asciidoc format is not as popular/widely used as Markdown. Notwithstanding the foregoing, Asciidoc is used for some of the following projects:
- O'Reilly and Maker Press
- NFJS, the magazine
- other examples
Con Limited output options
Asciidoctor can only convert directly to HTML or DocBook. However, you can always use another converter such as pandoc to convert from one of the output formats to another format.
