What are AsciiDoc and Markdown? A thorough comparison of their uses, benefits, and differences!

Table of Contents

1. What are AsciiDoc and Markdown?
1-1. What is a lightweight markup language?
1-2. What is AsciiDoc?
1-3. What is Markdown?
2. How to Differentiate Between AsciiDoc and Markdown? Usage Examples for Different Scenarios
2-1. How to Utilize AsciiDoc
2-2. How to Use Markdown
2-3. Differentiating Between AsciiDoc and Markdown
3. Benefits of AsciiDoc and Markdown
3-1. Benefits of AsciiDoc
3-2. Benefits of Markdown
4. Comparing the Differences Between AsciiDoc and Markdown!
4-1. Automatic Table of Contents Generation
4-2. Superscript/Subscript
4-3. Cell Merging in Tables
4-4. External File Import
4-5. Other Advanced Features
5. Use Cases of AsciiDoc

Introduction to Document Solutions for IT Companies

1. What are AsciiDoc and Markdown?

AsciiDoc and Markdown are both lightweight markup languages that can be written in plain text, but they have different features and uses.
This article provides a clear explanation of the characteristics of each and suitable usage scenarios for those who want to streamline technical document creation or are struggling with the differences between AsciiDoc and Markdown.

1-1. What is a lightweight markup language?

A lightweight markup language is a language used to describe the structure and decoration of text using simple symbols. Traditional markup languages (such as HTML and XML) express structure and decoration by enclosing text with symbols called tags. However, as the number of tags increases, the text becomes harder to read, and the writing becomes more complex. This is where lightweight markup languages are gaining popularity. In lightweight markup languages, simpler symbols are used to describe the structure and decoration of text. As a result, the text is easier to read, and writing becomes simpler. However, since it is a simplified markup, there may be limitations in expressiveness compared to traditional markup languages.
Additionally, because it can be written in plain text, no special software is required, and it can be edited with a standard text editor. However, it cannot be displayed in a web browser or printed as is. Therefore, it needs to be converted into formats such as HTML or PDF.

1-2. What is AsciiDoc?

AsciiDoc is a powerful markup language that can be written in plain text, particularly suitable for creating documents with complex structures, such as technical documents and manuals. Compared to Markdown, it is characterized by its ability to describe more advanced document structures. Additionally, it supports various output formats, including HTML, PDF, and EPUB, allowing the created documents to be published across different media.
The specifications of AsciiDoc are clearly defined, which helps in maintaining consistency in document creation. Therefore, it is also suitable for collaborative work among multiple people or for creating documents that require long-term maintenance. However, compared to Markdown, the syntax can be more complex, which may take time to learn. Nevertheless, it offers advanced expressiveness and flexibility, meeting the needs for creating complex documents.

1-3. What is Markdown?

Markdown is one of the most widely used lightweight markup languages for creating documents simply and efficiently. By using just a few special characters, you can represent the structure and decoration of text, such as headings, lists, and emphasis. There is no need to remember complex tags like HTML, so anyone can easily start writing. The written text is designed to be understandable as is, and the source code is easy to read, making modifications and edits straightforward. Due to its high versatility, Markdown is used in various situations, such as creating blog posts and writing technical documents. Additionally, written Markdown documents can be converted into various formats, such as HTML, PDF, and Word, allowing for flexible adaptation to different needs.

2. How to Differentiate Between AsciiDoc and Markdown? Introducing Usage by Different Scenarios

2-1. How to Utilize AsciiDoc

AsciiDoc is suitable for the following purposes due to its advanced document structure and rich features.

• Technical Documents, Manuals: Suitable for creating technical documents and manuals with complex structures. Features such as tables, cross-references, and includes allow for the creation of accurate and easy-to-understand documents.

• Books and Papers: Suitable for creating books and papers that extensively use figures and formulas. It supports various output formats, allowing for publication in different media such as print and e-books.

• Specifications: Clear specifications allow for consistent document creation. It is suitable for collaborative work among multiple people and for creating documents that require long-term maintenance.

• Large-scale document creation: It is suitable for creating large documents because it has the ability to split and manage long documents, allowing them to be compiled into one later.

2-2. How to Utilize Markdown

Markdown is characterized by its simple and easy-to-learn syntax, making it suitable for the following applications.

• Blog articles, web content: You can easily create web content with simple markup. It is supported by many blog services and CMS.

• README files, documentation: Suitable for creating software README files and simple documentation. Widely used in code sharing services such as GitHub.

• Notes, Minutes: You can quickly create notes and minutes with a simple notation. It can be easily used as it can be edited in a text editor.

• Communication tools: These may be used for text decoration in chat tools and messaging apps.

2-3. Differentiating Between AsciiDoc and Markdown

It is important to choose the optimal language according to the type and purpose of the document being created. Markdown is suitable for creating simple documents and web content. On the other hand, AsciiDoc is more effective when complex structures and advanced expressiveness are required. By understanding the characteristics of both, and using them appropriately, efficient and effective document creation becomes possible.

Introduction to Document Solutions for IT Companies

Download here

3. Benefits of AsciiDoc and Markdown

We will summarize the benefits of AsciiDoc and Markdown respectively.

3-1. Benefits of AsciiDoc

AsciiDoc is a powerful markup language for creating documents with complex structures, such as technical documents and books. Compared to HTML and Markdown, it offers more advanced features and flexibility.

• High readability: By not using complex tags like HTML, it remains very readable even as plain text. Additionally, the structure of the text becomes clear, making it easier to understand the content.

• Various output formats: Can be converted into various formats such as HTML, PDF, EPUB, and DocBook. This allows for support across diverse media such as web publishing, printing, and e-books.

• High expressiveness: It allows for a relatively advanced document structure compared to Markdown. Features like the following streamline the creation of complex documents.

◦ Automatic Table of Contents Generation: Automatically generates a table of contents based on the document structure.
◦ Superscript/Subscript: Allows specific characters in the text to be displayed as superscript or subscript.
◦ Table Cell Merging: Merges table cells to create complex tables.

• External file import: You can import other AsciiDoc files and image files, and incorporate them into the document.

• Integration with GitHub: You can edit AsciiDoc files on GitHub and manage change history. This makes collaboration among multiple people and version control of documents easier.

3-2. Benefits of Markdown

Markdown is a lightweight markup language that allows you to describe the structure of text using a simple syntax, and it is widely used in various fields due to its convenience.

• High readability: Since it does not use complex tags like HTML, the content is easy to understand even when read as a plain text file. Additionally, by expressing the structure of the text with simple symbols, the source code is also easy to read and edit.

• Diverse output formats: Documents written in Markdown can be converted into various formats such as HTML, PDF, docx, pptx, etc. This allows for a wide range of applications, including creating web pages, documents, and presentation materials.

• Reversibility: Markdown can be converted from formats such as HTML and Word, and then converted back to Markdown format. This reversibility makes editing and modifications easier, and facilitates smooth data exchange between different formats.

4. Comparing the Differences Between AsciiDoc and Markdown!

Features	AsciiDoc	Markdown
Expressiveness*	Superior to Markdown	Inferior to AsciiDoc
Readability	Expensive	Expensive
Reversibility	none	Exists
Complex Structure	Possible	Limited
Output Format	Diversity	Web Center
Usage	Manuals, technical documents, papers, etc.	Documents, blogs, specifications, etc.
Specifications	Clear	There are many dialects
Table Function	High Functionality	Functionality is limited
Awareness	Low	High (adopted by various tools, etc.)

*About the differences in expressiveness
It is said that AsciiDoc is more expressive than Markdown because it has a wealth of features that allow for more complex document structures and advanced formatting. Below, I will explain the differences while comparing specific syntaxes.

4-1. Automatic Table of Contents Generation

AsciiDoc: You can automatically generate a table of contents based on heading levels.
By using the TOC macro, you can easily create a table of contents based on the structure of the document.
Example: TOC
Markdown: Automatic table of contents generation is not supported by default.
While some Markdown processors and extensions can generate a table of contents, they are not as flexible as AsciiDoc.

4-2. Superscript/Subscript

AsciiDoc: You can directly write superscripts and subscripts.
Example: H~2~O, E=mc^2^
Markdown: Superscripts and subscripts are not supported in standard features.
You can achieve similar expressions using HTML's <sup> and <sub> tags, but readability decreases.

4-3. Merging Table Cells

AsciiDoc: You can merge table cells both horizontally and vertically.
Example:
|===
| Column 1 | Column 2
| a | b
| 2+^| c
| d | e
|===
Markdown: Cell merging is not supported by default.
While similar expressions can be achieved using HTML's colspan and rowspan attributes, the syntax becomes more complex.

4-4. External File Import

AsciiDoc: You can import other AsciiDoc files and source code using the include macro.
Example: include::other_file.adoc[]
Markdown: Importing external files is not supported by default.
Similar functionality can be achieved using some Markdown processors and extensions, but it is not as flexible as AsciiDoc.

4-5. Other Advanced Features

Cross-references: You can easily create references to specific sections or figures within the document.
Conditional descriptions: You can show/hide parts of the document based on specific conditions.

As these examples show, AsciiDoc offers a wealth of features that enable more advanced document creation than Markdown. Therefore, it is suitable for creating documents with complex structures, such as technical documents and books.

5. Use Cases of AsciiDoc

As a case study of the use of AsciiDoc, we will introduce the case of Yamaha Corporation.

●Challenges
・In the production of manuals for network products, we want to eliminate the challenges of direct HTML coding without compromising on appearance.
・We want to resolve the issues associated with manual production using traditional DTP tools.

●Solutions
・Adopting Asciidoc (a lightweight markup language) to create HTML manuals
・Building a new manual production system aimed at efficiency and cost reduction

●Implementation Details
・Established a system to automatically generate HTML/PDF data simultaneously using a data conversion converter (Asciidoctor, Asciidoctor-PDF) from manuscript data written in a lightweight markup language.
・Enhanced layout design

●Implementation Effects
Achieved cost reduction of over 30%

Detailed information about the case of Yamaha Corporation is introduced on the following page.
Please take a look.
Centralized management of PDF and HTML manuals data across departments using AsciiDoc and GitHub

6. Summary

Lightweight markup languages are utilized in various tools and documents today to describe the structure and decoration of text using simple symbols. While their expressiveness may be inferior compared to traditional HTML and XML, they are easy to edit and highly readable. By constructing manuals in Asciidoc or Markdown, we believe it is possible to enhance maintainability, facilitate the expansion into various document formats, improve production efficiency, and reduce production costs.
Human Science provides one-stop support from the creation of manuals in Japanese to English and multilingual translation. We have a long track record of handling numerous manuals since 1985.
If you are struggling with the construction and operation of manuals, please take advantage of Human Science's implementation support services.
We support efficient and consistent document creation through the use of GitHub and lightweight markup languages.
Please feel free to consult with us.

Introduction to Document Solutions for IT Companies

Download here

Introduction to Document Solutions for IT Companies