What Are Lightweight Markup Languages? An Easy-to-Understand Explanation of Types and Examples like Markdown and AsciiDoc!

1. What is a Lightweight Markup Language?

First, to gain a deeper understanding of "lightweight markup languages," we will compare them with traditional "markup languages (such as HTML)" and then summarize their relationship with "AI."

1-1. What is a Markup Language?

A markup language is a language that specifies the structure of a document (such as headings and paragraphs) and decorations (such as bold text and links) using tags or symbols so that a computer can correctly recognize them.
Representative examples include the following.

• HTML: A language used for creating web pages
• XML: A general-purpose language used for describing data
• TeX: A language strong in describing mathematical formulas and writing academic papers

These are highly functional, but their syntax rules are strict, and the amount of tag writing tends to be large.

1-2. Characteristics of Lightweight Markup Languages

In contrast, a lightweight markup language is, as the name suggests, a language designed to be written using simple symbols that are easy for humans to read and write.
For example, to make text bold in HTML, you need to write <strong>強調</strong> It is necessary to write like this, but with lightweight markup languages (e.g., Markdown), **強調** you only need to enclose it like this.

1-3. Differences from Markup Languages

The biggest difference between traditional markup languages like HTML and lightweight markup languages like Markdown is whether they are designed to be read directly by humans.

 

1. Visibility (Human-Readable)

• HTML: Contains a large number of "tags" for the computer to interpret. Structural definitions such as <div class=”content”> and <span style=”color:red;”> stand out more than the text itself, making it hard to read.
• Lightweight markup: The symbols are minimal. Because decorative symbols (such as # and *) do not interfere with the text, you can read the original text file before conversion just like an email or memo.

2. Writing Burden (Writeability)

• HTML: Closing tags (such as </h1>) need to be entered, resulting in a high number of keystrokes. Layout breakage due to typing errors is also common.
• Lightweight markup: Closing tags are often unnecessary, allowing you to write without moving your hands far from the keyboard’s home position. You can focus on writing without interrupting your train of thought.

[Comparison Table: HTML vs Lightweight Markup (Markdown)]

Features	Standard Markup (such as HTML)	Lightweight Markup (such as Markdown)
Main Uses	Building web pages, data exchange between systems	Document creation, notes, chat, bulletin boards
Readability	Low (source code is hard to read)	High (can be read as text as is)
Learning Cost	High (need to memorize many tags and attributes)	Low (can write by remembering a few symbols)
Expressiveness	Very high (can specify design and layout in detail)	Limited (mainly defines document structure)

1-4. Compatibility with Generative AI

Lightweight markup languages are said to be highly compatible with AI.

• Token Consumption Savings (Cost & Speed): AI is charged or limited based on the number of characters (tokens). HTML has a huge number of characters due to tags, but lightweight markup languages are very compact. For the same content, Markdown requires overwhelmingly fewer tokens, allowing AI to handle longer texts.
• AI Easily Understands Structure: Large language models (LLMs) are trained on vast amounts of source code from places like GitHub, so AI is well-versed in the structure of Markdown. When instructed with commands like "Make this a heading" or "Summarize in a table format," AI often naturally outputs in Markdown.
• Reduction of the Risk of Hallucination (Malfunction): Complex XML tags carry the risk that AI might forget closing tags or fabricate non-existent attributes. Lightweight markup languages, which use simple notation, tend to have a relatively lower error rate in this regard.

Points to Note

• Variations in Notation Due to Dialects: Markdown has "dialects" with slightly different specifications, such as "GitHub Flavored Markdown (GFM)" and "CommonMark." Depending on which dialect the AI bases its output on, tables may break or line breaks may not be reflected when pasted into tools.
• Poor at handling complex layout instructions: Complex layout instructions such as "align the image to the right and have the text wrap around it" cannot be expressed by lightweight markup languages alone. Forcing AI to follow such instructions may result in embedding CSS or mixing broken HTML, which can compromise the "simplicity" that is the strength of lightweight markup.

2. Characteristics and Writing Samples by Type of Lightweight Markup Language

There are several types of lightweight markup languages, each with its own strengths and writing rules. Here, we introduce five representative ones, along with their characteristics and actual writing examples (writing samples).

2-1. Markdown

Currently, it is the most widely used lightweight markup language, not only among engineers. Many tools such as GitHub, Qiita, Slack, and Notion support it, making it the de facto standard.

・Features:

• The biggest feature is that the symbols are intuitive and easy to remember, resulting in a low learning curve.
• There are abundant tools for converting not only to HTML but also to Word and PDF.
• Uses: README files, technical blogs, manuals, chat tools, simple specifications.

[Sample Description]

# 大見出し（h1）
## 中見出し（h2）

- 箇条書きリスト
- リストの項目です

ここは段落です。文章中の強調したい部分は **太字** にしたり、 `コード` として埋め込んだりできます。
[リンク](https://example.com) も簡単に設置可能です。

2-2. AsciiDoc

It is a language that maintains the "simplicity" of Markdown while enhancing the "expressiveness" required for commercial documents. It is chosen when you want to describe complex structures that cannot be fully expressed with Markdown.

・Features:

• Advanced table formatting is possible, such as merging table cells and specifying column widths.
• You can easily create icon-attached blocks like "Note" and "Warning."
• It has an external file inclusion feature, making it ideal for managing large-scale manuals.
• Usage: Company manuals, technical specifications, books (also adopted by O’Reilly, etc.).

Related Blog
How to Convert Asciidoc｜HTML and PDF Output with Asciidoctor

 

[Sample Description]

= ドキュメントタイトル（h1）
== セクションタイトル（h2）

* 箇条書きリスト
* *太字* で強調

.テーブルタイトル
|===
|列1 |列2

|セルA
|セルB
|===

NOTE: 補足情報は、このように専用の記法で見やすく表示できます。

2-3. Textile

It is a language developed with the purpose of simplifying the writing of HTML tags. It is used in project management tools such as Redmine.

・Features:

• There are many notations that resemble HTML tags, such as h1. and p..
• You can finely control text decoration and layout specifications, but in recent years it has been gradually losing share to Markdown.
• Usage: Ticket descriptions in Redmine, JIRA, and some CMSs.

[Sample Description]

h1. 大見出し

* 箇条書きリスト
* *太字* で強調

p. ここは段落です。"リンク":https://example.com も記述できます。

2-4. Wikitext

A markup language designed for collaborative editing on Wiki systems such as Wikipedia.

・Features:

• The biggest feature is that you can easily create links between pages (internal links) using [[Page Name]].
• Be aware that there are significant dialects (differences in notation) depending on the system (such as MediaWiki, PukiWiki).
• Usage: Internal Wiki, Knowledge Base, Wikipedia.

[Sample Description]

== 見出し（h2） ==

* 箇条書きリスト
* '''太字''' で強調

[[内部リンク]] を簡単に作成して、ページ同士をつなげることができます。

2-5. reStructuredText (reST)

It is known as the standard documentation format for the programming language Python.

・Features:

• It has very high extensibility and is suitable for academic papers and technical reference manuals.
• There are strict rules for indentation, and the difficulty of writing is slightly higher compared to Markdown and others.
• Usage: For Python documentation and use with Sphinx (documentation generation tool).

[Sample Description]

セクションタイトル
==================

サブセクション
--------------

* 箇条書きリスト
* **太字** で強調

.. note::
ここに注釈ブロックを記述します。インデントが重要です。

3. Case Study of AsciiDoc Utilization: Yamaha Corporation

Here, we introduce the case of Yamaha Corporation, which adopted AsciiDoc—a lightweight markup language particularly suitable for manual creation—and achieved significant results.

3-1. Challenges Before Implementation

In the production of manuals for network products, they faced the following challenges.

• Writing HTML directly is time-consuming, but we did not want to compromise on appearance or quality.
• We wanted to eliminate the manual production workflow using conventional DTP tools (the effort involved in version control and revisions).

3-2. Solution: Adoption of AsciiDoc

Therefore, we chose to adopt the "lightweight markup language (AsciiDoc)" and build a new manual production system.
By creating an environment where engineers can write documentation using the same workflow as development, we aimed to improve efficiency and reduce costs.

3-3. Implementation Effects

As a result, the following achievements were obtained.

• Achieved cost reduction of over 30%

3-4. Mechanism of Lightweight Markup Language Using AsciiDoc

The system built by Yamaha is structured as follows.

• Manuscript Writing: Create manuscript data using a lightweight markup language (AsciiDoc).
• Automatic Conversion: Use data conversion converters (AsciiDoctor, AsciiDoctor-PDF).
• Simultaneous Generation: Automatically generate HTML and PDF data simultaneously from a single manuscript file.

This eliminates the need to create separate versions for each medium and makes it easier to maintain information consistency. Another major advantage is the ability to centrally manage data across departments.

 

[Details of the Case Study Here]
Centralized Management of PDF and HTML Manual Data Across Departments Using AsciiDoc and GitHub (Yamaha Corporation Case Study)

4. Summary

Lightweight markup languages hold the potential to improve the efficiency of document creation, including the utilization of AI.
In particular, "Markdown" is suitable for simple notes and manuals, while "AsciiDoc" is appropriate for creating structured, somewhat complex manuals and specifications.

In-house production of manuals and technical documents, as well as streamlining the production process, are important challenges for many companies.
Human Science provides one-stop support from creating Japanese manuals to English and multilingual translations. Leveraging our extensive experience and expertise in handling numerous manuals since 1985, we contribute to solving our customers' challenges.
If you are struggling with building and managing manuals, please make use of Human Science’s implementation support services. Through the use of GitHub and Markdown/AsciiDoc, we support efficient and consistent document creation.
Please feel free to contact us.

 

GitHub/Markdown/AsciiDoc Implementation Support Service