Productivity Programming Technology Explained

Lightweight Markup Languages: This Is Why You Should Use AsciiDoc Over Regular Markdown

Aaron Peters 15-09-2017

As you’ve likely seen from past articles, here at MakeUseOf we’re fans of Markdown. By learning this simple and intuitive format, you’re able to easily create nice-looking output. From PDF’s to web pages, your humble, plain text file becomes a sophisticated document.


But Markdown isn’t the only game in town. There are a number of other so-called lightweight markup languages similar to Markdown but with different feature sets. One of these is Asciidoc. If you like Markdown but are looking for a little bit more under the hood, it’s worth considering. Here are some reasons why.

What Is a “Markup Language” Anyway?

A markup language is a set of codes that, when applied to otherwise plain text, allows you to add one or more of the following properties (among others):

  • Define the text
  • Structure the text
  • Describe the layout of the text
  • Decorate the text

One markup language you encounter every day (unless you’re a hermit) is Hypertext Markup Language, or HTML. The web sites and applications that bring you news and show you your email are built, at least in part, with HTML markup Learn HTML and CSS with These Step by Step Tutorials Curious about HTML, CSS, and JavaScript? If you think that you have a knack for learning how to create websites from scratch -- here are a few great step-by-step tutorials worth trying. Read More . HTML makes use of tags as the mechanism to markup the raw text content. For example, consider the following snippet of HTML:

<h1>Introducing HTML</h1>
<p>Here is a paragraph in HTML... we know it's a <strong>paragraph</strong>
because the surrounding \<p\> tags define it as one.</p>

Here, the <p> tag specifies that all the text to follow, up to its closing </p> tag, is a paragraph. In this sense it defines the text as a paragraph.

But note also the <body> tags… these often serve to define the layout of a web page, such as how much margin there is from the side of the screen.


And the <strong> tags will decorate the word “paragraph” in a bold font, while the <h1> tags may both lay out the heading (spacing it from surrounding text) as well as define a larger font.

The issue with some markup languages (HTML among them) is that typing these tags manually is a very tedious affair. And with other languages like XML What Is an XML File and How Can You Open and Use It? You may have seen the term "XML." You might even have accidentally opened an XML file. What is XML and how do you use it? Read More , the tags and their attributes make up a larger portion of the overall content than the text itself! Take a look at the following DocBook snippet, an XML dialect used to create many technical publications:

asciidoc markdown docbook tags

All the text in purple represents tags that you’d need type in by yourself. The first paragraph doesn’t start until the very bottom of that picture. And if it’s not done exactly right according to the DocBook standard, you won’t be able to convert it to the pretty PDF document that is usually the end goal.


Enter the Lightweight Markup Language

If you wanted to take advantage of markup languages, for example by publishing an HTML page to the web or converting a DocBook file to PDF so it can be printed, you needed to do one of two things. On one hand you could invest time by learning these languages inside and out, writing them by hand, then triple-checking your work. Or you could invest money in a tool that manages the complexity of these for you.

Thankfully, some enterprising developers came up with a third option. They created new markup languages that contained many (in some cases most or all) of the features of the heavier counterparts, but greatly simplified the syntax. These “lightweight” languages include the familiar Markdown What Is Markdown? 4 Reasons Why You Should Learn It Now Tired of HTML and WYSIWYG editors? Then Markdown is the answer for you no matter who you are. Read More as well as Asciidoc, Emac’s Org-Mode format, and the Mediawiki syntax.

Lightweight Markup Languages Have Simple Syntax

One hallmark of these languages is that their “tags” (such as they are) should be intuitive. Let’s take a look at the previous snippet, this time written in Asciidoc:

Introducing Asciidoc

Where are the *paragraph* tags? We dont need them... Asciidoc is smart enough
to realize this is a paragraph!

Much more readable, no? Starting at the top, we can identify the heading as it’s “underlined” with dashes. You might do this if you were handwriting, just draw an underline under the title of the page in your notebook. There’s also no paragraph tags — Asciidoc considers anything between two empty lines that doesn’t have some other markup on it to be “plain” paragraph text. Finally, the asterisks around the word “paragraph” indicate bolding. Raise your hand if you’ve done this in a text message to mean the exact same thing.


Each Has One or More Corresponding Processors

The “heavyweight” markup languages typically have a dedicated application to interpret them for you. On the web, it’s your browser as well as possibly the web server that will turn the code in to flashy web pages Everything You Need to Know About Content Management Systems For the average internet surfer, viewing content is easy. You open a link, and the page appears. But what is taking place behind the scenes? Here's how your favorite CMSs take care of business. Read More . For documents in XML, it might be something like Microsoft Word, which reads and writes it’s DOCX format How to Open Microsoft Word 2007 DOCX Files Have you ever received one of those files with the .docx extension and wondered what to do with it? It can't be viewed in older Word versions, so how can you open a .docx file... Read More (which is another XML dialect). So you never have to interact directly with the source of these documents, only the pretty facades your apps show you.

Meanwhile, documents written in lightweight languages are human-readable in source form (another tenant), but only true nerds might think they’re beautiful. In order to get pretty output, you need to use a processor. These are applications that will run through your markup line by line and convert it to something else that looks good. The same projects that develop the language itself will typically produce a utility to go with it. The Markdown project offers a Perl script of the same name, and Asciidoc’s companion program is written in Python. In addition, other conversion utilities will include support for some of these languages. One such is the excellent Pandoc How to Easily Convert Between Document Formats in Linux Switching to Linux can result in problems with file compatibility. For instance, documents don't look the same in LibreOffice as they do in Word. This is just one reason why you need pandoc. Read More , which will take Markdown as well as lightweight markups reStructured Text, Mediawiki, and Org-Mode and convert them to PDF, DOCX, ODT, and more.

asciidoc markdown pandoc formats

The result is that lightweight markup languages allow you to work in plain text, the most portable data format on the planet, yet still produce nice-looking output in the end. Now that you’re convinced of its merits, which language should you choose? Markdown is undoubtedly the most popular, and has its advantages (more on these later). But Asciidoc in particular is a worthy alternative. In the next section we’ll explore a couple of reasons why.


Comparing Markdown and Asciidoc

The Asciidoc format was created in order to bring lightweight simplicity to DocBook, one of the more common formats in long-form (especially technical) writing. One of it’s claims to fame is that it’s a one-to-one translation, meaning for every element in DocBook, there’s a corresponding representation in Asciidoc. Below we’ll take a look at some of the pros and cons of Asciidoc when compared to Markdown.

Asciidoc Covers a Superset of Writing Elements

Markdown’s goal from the outset was to be a simple format for web writers. As such, the writing elements it supports (at least the original implemenation, see below) are focused around automating the more time intensive aspects of writing HTML (lists for example, which require the <ol> or <ul> tags in addition to <li> tags for each item).

asciidoc markdown complex formats

Asciidoc contains these as well, but also offers more advanced DocBook elements such as admonitions (e.g. “Note:” or “Info:” callout blocks) and complex table layouts. It doesn’t mean you need to use them all the time, but they will be there and available if you ever need them.

Asciidoc Is a Unified Format

When the popularity of Markdown began to take off, some of its users began to run into some of the shortcomings discussed above. So these users began to develop their own extensions to solve these problems, such as the ability to add tables or foot/endnotes. Soon there were many “flavors” of Markdown, including (among others):

The result is that the your document may require elements that aren’t all covered by a single flavor. In contrast, Asciidoc doesn’t suffer from the same fragmentation Markdown does at present.

Asciidoc Targets a Variety of Publishing Styles

Markdown is great for quickly getting a blog post out of your head and onto the page. But out of the box, it’s not built for structuring longer works, like a book. Asciidoc is designed for this, and one example is its “include” functions. These statements allow you to include all the content of one file in another:


This is not unlike how Master Documents work in word processors. This allows you to, for example, draft each chapter as a separate file, then “include” them all into one file representing the book. When you process that “book file,” the output will be as though all the chapters were written directly into that document.

Markdown Is Enough for Most Users

Markdown covers all the bases for a larger portion of users. For those simply looking to blog, or type up some notes in a plain text format, Markdown supports all the elements they will need. Cross-references don’t mean much to a user who just wants to create a simple memo or web page. You could even use Markdown for longer works with simple layouts, such as a novel Who Needs Scrivener? 5 Novel Writing Apps for Linux Scrivener isn't available for Linux -- so how will you keep track of where these characters go, what they've done, and how they complete their journey? Well, one of these tools should help. Read More , and combine them yourself at the end.

Markdown Is Better Supported

Since Markdown meets the needs of a larger segment of users, it’s ended up better supported in terms of the following:

Are You Willing to Give Asciidoc a Try?

While Markdown is something of a de facto choice among lightweight markup languages, Asciidoc contains all the same elements and then some. The extras of Asciidoc require some time to learn, by may better prepare you for larger and more complex writing projects.

What do you think? Are you content with the simplicity of Markdown? Or is creating your own multi-channel publishing workflow with Asciidoc enticing? Perhaps you hate plain text and it’s Word all the way for you? Let us know in the comments below!

Related topics: Markdown, Writing Tips.

Affiliate Disclosure: By buying the products we recommend, you help keep the site alive. Read more.

Whatsapp Pinterest

Leave a Reply

Your email address will not be published. Required fields are marked *

  1. Jan Steinman
    September 26, 2017 at 6:14 pm

    Looks a lot like Wikitext, as used by WikiPedia, which you can download and install for free — plus, you'll have a running wiki afterward!

    September 17, 2017 at 11:28 am

    I use Org mode (in Emacs) as my Lightweight "Markup" Language. It's readability is similar to that Markdown but has more features than AsciiDoc. Org mode is much more than a Markup language. While it supports stuff like includes, cross-references and tables, it also supports:

    - Live tables in plain text i.e. you can have table cells auto-evaluate based on formulas.
    - "Tangling" feature in Org allows you to do Literate programming. The documentation contains snippets of code and on tangling, the documented code is generated. For example, in my eless project, I generate the eless bash script[1] (and the GitHub README, Wiki, etc.) using this single file[2].
    - "Org Babel" feature allows you to document code snippets and their results. The results for those snippets are generated by Org (+ Emacs). So you don't need to do copy/paste to maintain the code results in your documentation. For example, none of the Python or Nim code result blocks here[3] are typed manually! Org Babel did that for me. (In the source Org[4] for that blog, the "#+RESULTS:" sections are filled in by this functionality.)
    - Org also has exporter backends that can export Org to HTML, Markdown, plain text without markup, ODT, LaTeX, Beamer slides, texi (Info manuals), Man pages, reveal.js slides, etc.
    - Pandoc, command line format converter utility also supported converting to and from Org to other formats including AsciiDoc, ReStructuredText.
    - Org is rendered mostly well by sites like GitHub and Gitlab.


    • Aaron Peters
      September 25, 2017 at 4:09 pm

      Hi Kaushal,

      Yes, I'm actually diving into Org-Mode myself at the moment. I'm finding it has more non-document-related features than Asciidoc (many of those you mention), but that Asciidoc supports more elements of long-form documentation (things like admonition blocks, etc.).

      To your point though, I'm thinking of trying to implement Asciidoc as another supported format for Org-Babel. So I can manage a writing project using Org-Mode features like to-do's, but without the need to learn yet another markup syntax.

  3. Arun
    September 17, 2017 at 4:35 am

    All our documents are in Asciidoc, it's brilliant and simple format. We use AsciidocFX to write all our documents.

    • Aaron Peters
      September 18, 2017 at 4:24 pm

      I agree Arun, and I've just about moved to doing all my documents in Asciidoc as well. I've tried AsciidocFX too, although I find the WYSIWYG interface a little immature for my taste. I tend to just work in a plain text editor (Emacs).

  4. Ed Borasky
    September 17, 2017 at 2:51 am

    Restructured Text is very popular with Python developers; it's baked into many of the documentation tools.

    • Aaron Peters
      September 18, 2017 at 4:31 pm

      Very true Ed, and I believe all the points I made in favor of Asciidoc above also apply to the more "middleweight" markups like reST, Textile, or (to a lesser extent) Multi-Markdown.

      So if you're a Python hacker, or (for example) you like the looks of the Pelican or Sphinx publishing systems, ReStructured Text definitely makes sense. The main thing that drew me to Asciidoc was having a Java implementation available, and support for ATX-style headers.