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 markupLearn HTML and CSS with These Step by Step TutorialsLearn HTML and CSS with These Step by Step TutorialsCurious 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:

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

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.

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.

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 PandocHow to Easily Convert Between Document Formats in LinuxHow to Easily Convert Between Document Formats in LinuxSwitching 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.

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 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 novelWho Needs Scrivener? 5 Novel Writing Apps for LinuxWho Needs Scrivener? 5 Novel Writing Apps for LinuxScrivener 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:

WYSIWYG editors (as defined by those that at least provide a live preview) are much more likely to support Markdown.

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!

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 eless.org 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.

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.

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).

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.

Aaron has been elbow-deep in technology as a business analyst and project manager for going on fifteen years, and has been a loyal Ubuntu user for almost as long (since the Breezy Badger). His interests include open source, small business applications, integration of Linux and Android, and computing in plain text mode.