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. HTML makes use of tags as the mechanism to markup the raw text content. For example, consider the following snippet of HTML:

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

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, 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 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. For documents in XML, it might be something like Microsoft Word, which reads and writes it's DOCX format (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, 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:

        include::somefile.adoc
    

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

  • WYSIWYG editors (as defined by those that at least provide a live preview) are much more likely to support Markdown.
  • Online services, such as the aforementioned Github, are more likely to accept Markdown directly or through the use of addons.
  • Though publishing systems like static site generators often support Asciidoc with plugins, that they support Markdown out of the box is almost a given.

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!