Stop Using Markdown For Documentation

include::source_code.js []

// tag::code_example[]
function multiply(num1,num2) {
  var result = num1 * num2;
  return result;
}
// end::code_example[]

include::source_code.js[tag=code_example]

[options="header,footer,autowidth"]
|===
| Cell A | Cell B
|===

:toc: right
:document_version: 1.1.0

The current document version is {document_version}.

ifdef::github[]
This content will be displayed for GitHub users only.
endif::[]

ifdef::github[]
This content will not be displayed for GitHub users.
endif::[]

ifeval::[{api_version} < 2.0.0]
If you want to use API methods available in version {api_version}, use the following endpoint: {% raw %}`https://example.com/api/v1/
endif::[]
```

### Building Blocks

Building blocks are special components to include non-paragraph text, such as code listings, quotes, tables, etc. This gives you a greater flexibility in adding versatile content in your document.

For example, you can add a listing block like this:

```
----
This is an example of a _listing block_.
The content inside is displayed as <pre> text.
----
```

or like this by adding callouts for additional information right in the sample:

```
[source,ruby]
----
require 'asciidoctor'  # <1>

Asciidoctor.convert_file 'mysample.adoc'  # <2>
----
<1> Imports the library
<2> Reads, parses, and converts the file
```

![Asciidoctor-callouts](https://dev-to-uploads.s3.amazonaws.com/uploads/articles/qtcq5i4sm9bmm26byc92.png)

Another powerful block is an _open block_. It can act as any other block and contain any information you want. This may be useful as a non-intrusive way of including content. For example:

```
[sidebar]
.Related information
--
This is aside text.

It is used to present information related to the main content.
--
```

### Admonitions

AsciiDoc supports 5 types of admonitions out-of-the-box: Note, Tip, Important, Caution, Warning. The great thing here is that admonition can also encapsulate any block content. If you remember, in Markdown admonitions are some sort of blockquotes and writing a section that includes examples with special formatting is a total disappointment. In AsciiDoc, you just add the desired content with the selected type of the admonition.

### IDs, anchors, and classes

In Markdown (I mean, base syntax), the only thing you can do is to override the auto-generated heading anchor with your own user-friendly slug. With AsciiDoc, you can add a custom anchor almost anywhere: on a section title or discrete heading, on a paragraph, on a block, on a link or inline image, on listing or literal block, on a phrase, and so forth.

For example:

ID for a paragraph

```
[[notice]]
This paragraph gets a lot of attention.

or

[#notice]
This paragraph gets a lot of attention.
```

Furthermore, classes and additional attributes are available for links. The base syntax looks as follows:

```
link:url[optional link text, optional target attribute, optional role attribute]
```

So, you can write something like that:

```
Mister Gold Blog was created by https://mister-gold.pro/[*Antonio*^, role="green"].
```

and receive a link with bold green text that will be opened in a new tab. Again, these manipulations are possible with no hints of inline HTML or hardcoded CSS classes in it.

![Asciidoctor-link](https://dev-to-uploads.s3.amazonaws.com/uploads/articles/a9r8b2z3d4lsf6xwudhh.png)

### Tables

Tables are available in Markdown as well. But what can you do with them? Align content... aaaand... that's it. Asciidoc provides a variety of ways to control the size, style, and layout of content within columns. Span over columns and rows, add nested tables, duplicate content across columns, and even display table in landscape mode - I bet this is the best experience with table formatting you ever had.

Some examples:

**Different table width**

```
[cols="50,20,30"]
|===
|Cell in column 1, row 1
|Cell in column 2, row 1
|Cell in column 3, row 1

|Cell in column 1, row 2
|Cell in column 2, row 2
|Cell in column 3, row 2
|===
```

![Asciidoctor-table-width](https://dev-to-uploads.s3.amazonaws.com/uploads/articles/hkd1rearb80mhlwahzub.png)

**Spanned rows**

```
|===

|Cell in column 1, row 1 |Cell in column 2, row 1 |Cell in column 3, row 1

.2+|Content in a single cell that spans rows 2 and 3
|Cell in column 2, row 2
|Cell in column 3, row 2

|Cell in column 2, row 3
|Cell in column 3, row 3

|===
```

![Asciidoctor-table-spanned](https://dev-to-uploads.s3.amazonaws.com/uploads/articles/rfd08yw7gwy5z7aifhqf.png)

**Nested table**

```
[cols="1,2a"]
|===
| Col 1 | Col 2

| Cell 1.1
| Cell 1.2

| Cell 2.1
| Cell 2.2

[cols="2,1"]
!===
! Col1 ! Col2

! C11
! C12

!===

|===
```

![Asciidoctor-table-nested](https://dev-to-uploads.s3.amazonaws.com/uploads/articles/gbsj9p0l5pn6ogey5g1y.png)

### Other

Besides the joker features that stand out, AsciiDoc also has lots of syntax "tricks" that make documents more consistent. I will not dive into too many details here, just list some of them:

* hard breaks: you no longer need to insert blank lines to separate two paragraphs or pieces of content. Just add a plus sign at the end of the line and you're done!
* list continuation: add a descriptive paragraph or a building block directly to the parent or child list items.
* block titles: a small visual enhancement that makes content more readable.
* lists: with the help of built-in attributes you can make interesting modifications, like defining the starting number, creating a list with reversed numbering, or even a list with command listing without any text.
* math equations and formulas: to insert a math equation of any complexity, just set the `stem` attribute in the document’s header.

These tricks are almost unlimited - you will find more cool aspects, as you learn [AsciiDoc](https://asciidoctor.org/docs/asciidoc-writers-guide/) better.

## Conclusion

Actually, I was surprised by the fact that so many people think Markdown is a really powerful tool for documentation. Especially, considering the number of articles with the similar topic that appear on Medium. The premises for all these stories are almost identical. You start with a simple document or a set of documents. At this point, the instinct to choose Markdown is good. The fast learning curve and primitive syntax seem to be a winning combination. However, as your documentation evolves and you need something more complex, Markdown simplicity becomes the greatest shortcoming. Ultimately, you end up using flavors (to overcome native limitations) that wreck portability or searching for better alternatives.

It reminded me of two interesting blog posts that I found some time ago. In the first one, Eric Holscher (the co-founder of Read the Docs and Write the Docs) told [why you shouldn't use Markdown for documentation](http://ericholscher.com/blog/2016/mar/15/dont-use-markdown-for-technical-docs/). His article looked convincing, as I tend to trust the opinion of a person who has arguments against Markdown, while he is working on a product that supports both Markdown and reStructuredText. In the second [article](https://www.dabapps.com/blog/why-i-use-markdown-for-documentation/), Tom Christie tried to refute Eric's arguments. But his arguments were rather controversial as Tom described only his cases to use Markdown. The answer why Tom was sticking to Markdown was clear - his project is large (hosted with MkDocs), but has nothing more than code blocks under the hood. Markdown is good enough here, for sure.

As I said before, Markdown has lots of limitations out-of-the-box that cannot be resolved based on the existing CommonMark specifications. For example, sections reusage, source code inclusion or dynamic variables. As the result, Markdown fits only for creating basic documents like READMEs or simple knowledge bases.

AsciiDoc, in turn, offers better semantic richness, standardization, and support of multiple output formats (HTML, DocBook, PDF, and ePub). It also supports a broader range of syntax than Markdown, so the main focus was set on ensuring the maximum reusability of the content, whereas the syntax was designed to be extended as a core feature. This truly makes AsciiDoc the right investment as a complete, all-sufficient tool for creating documentation of any size, including auto-generated API docs.

And finally...

[According to John Gruber](https://daringfireball.net/projects/markdown/syntax#html), the inventor of Markdown:

> Markdown's syntax is intended for one purpose: to be used as a format for writing for the web.

So, I want to finish this article with the simplest conclusion ever:

> Do not use Markdown for things it was not designed to do. For example, to write documentation.