How to Convert Asciidoc｜HTML and PDF Output with Asciidoctor

1. Features and Benefits of AsciiDoc

Introducing the features and benefits of AsciiDoc.

1-1. Readable and Highly Expressive

AsciiDoc is one of the lightweight markup languages, so the following points are fundamental characteristics.

・Can be written in plain text
・Can explicitly indicate the nature of information through markup such as headings, numbered lists, and bullet lists
・Readable for both humans and computers

In addition to these, there are the following two points unique to AsciiDoc.

Syntax is standardized

AsciiDoc's syntax is standardized by the Eclipse Foundation.
Because the method of extending the notation is defined in the official language specification, you hardly ever have to worry about differences in "dialects" sometimes seen in Markdown.

Supports advanced expression methods

AsciiDoc supports advanced expression methods. For example, you can add titles to figures and tables, or merge cells in tables.
The following images show an AsciiDoc document and the HTML output result (the output result by Asciidoctor mentioned later).

 

Table: AsciiDoc

 

Table: HTML

In addition to footnotes, code blocks, and block quotes, labeled block elements such as "Warning" and "Note" are also provided. Especially, styles like "Warning" and "Note" are essential expressions in manual-type documents.

 

Note Style: AsciiDoc

 

Note Style: HTML

 

1-2. Good Compatibility with Version Control Systems

AsciiDoc is plain text, so it has excellent compatibility with version control systems such as Git. In particular, it demonstrates its true value when used with collaboration platforms like GitHub for shared team management.
In development environments, applying processes such as code reviews and pull requests, which are routinely performed, to document creation offers the advantage of maintaining documents more quickly and accurately.
Additionally, GitHub natively supports rendering AsciiDoc, allowing AsciiDoc documents within repositories to be viewed with formatted appearance.

1-3. Embedding Separate Files Within a Document

You can embed content from other AsciiDoc files or text files into an AsciiDoc document. This feature is called the include directive.
According to the official documentation (Includes | Asciidoctor Docs), typical use cases include splitting large documents into subdocuments and bundling them together, or quoting parts of separate files.
In manual production, for example, there may be requests such as "changing the chapters output for each volume of the manual" or "managing common content used across multiple manuals in one place." By skillfully utilizing include, these requests can be fulfilled without significant effort.

1-4. Various Output Formats

Using the open-source AsciiDoc processor "Asciidoctor," you can convert AsciiDoc into various formats.
The next section provides a detailed explanation of conversion using Asciidoctor.

2. Converting AsciiDoc to Other Media with Asciidoctor

2-1. What is Asciidoctor?

Asciidoctor is currently the most widely used implementation (processing engine) of AsciiDoc.
The current AsciiDoc is maintained assuming implementation with Asciidoctor, so if you start managing AsciiDoc documents, in many cases you will also introduce Asciidoctor together.

2-2. Formats Convertible with Asciidoctor

In an environment where Asciidoctor is installed, AsciiDoc documents can be converted into formats such as HTML, PDF, EPUB, and DocBook. In other words, you can create web pages, e-books, printed documents, and more using AsciiDoc as the source.
In manual production, there are many cases where both web manuals and PDF manuals are used together, and the ability to easily achieve one-source multi-use with Asciidoctor is a significant advantage.

What are the disadvantages of creating manuals using Word/Excel? Introducing the latest trends in manual creation

2-3. Immediate HTML Conversion by Running a Command

Once you have prepared your AsciiDoc document and installed Asciidoctor, you can immediately convert the document.
For example, let's convert it to HTML. By specifying the document and running a single command, an HTML file will be created. Asciidoctor provides a default stylesheet for HTML that is ready to use as is, so you might consider the creation complete at this point.
If you want to customize the appearance, create a separate stylesheet and specify its path within the AsciiDoc document. Running the conversion command in this state will produce an HTML file with the stylesheet applied.
You can also customize the appearance and functionality in advanced and complex ways, but the steps to "first convert and get the output" are very simple.

3. Common Challenges in Utilizing AsciiDoc and Their Solutions

This section explains the challenges and solutions when managing AsciiDoc documents within a company.

3-1. Need to Learn the Syntax

Learning AsciiDoc syntax requires a bit of time investment.
There are syntax references available online, so the basic approach is to refer to those and learn, but one effective method is to first memorize only the frequently used syntax.
When creating standardized documents, it is convenient to prepare a template AsciiDoc file in advance with each element placed, so that by copying and pasting, you can naturally become familiar with using the syntax.

Official Quick Reference:
AsciiDoc Syntax Quick Reference | Asciidoctor Docs

3-2. IT Literacy is Required

Some preparation is necessary to view, edit, and output AsciiDoc documents in other formats.

・Editing

Writing AsciiDoc itself can be done with just a text editor, but to edit while previewing or to seamlessly convert the edited document to another format, the use of a high-function editor like Visual Studio Code and the installation of extensions are naturally required.

・Environment Setup

To output AsciiDoc documents as PDF or HTML, it is necessary to install a Ruby environment and Asciidoctor.

・Output Customization

To customize output, such as setting theme files, stylesheets, and applying Japanese fonts, relevant knowledge is required.

Information on all of these can be found on the web.
Conversely, if you are in an environment where you do not feel these challenges are hurdles, I believe you can smoothly start managing AsciiDoc documents.

4. Summary: Streamlining Document Management with Asciidoc Conversion

AsciiDoc is a language with excellent expressiveness and extensibility, and using Asciidoctor allows for various output formats. It can be a powerful choice, especially for manual creation and team document management.

Human Science provides one-stop support from creating Japanese manuals to English and multilingual translations. We have a long track record of handling numerous manuals since 1985.
If you are struggling with building or managing manuals, please make use 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 contact us.

GitHub/Markdown/Asciidoc Implementation Support Services