How to Use the Command 'asciidoctor' (with examples)

Asciidoctor is a fast, open-source, text processor and publishing tool that converts AsciiDoc files into various output formats, such as HTML, PDF, and more. AsciiDoc is a lightweight markup language that uses plain text formatting conventions to create well-structured and styled documents suitable for technical documentation, articles, books, and even presentations. Asciidoctor provides a straightforward way to transform your AsciiDoc files into professionally styled and designed documents.

Use case 1: Convert a specific .adoc file to HTML (the default output format)

Code:

asciidoctor path/to/file.adoc

Motivation:

Imagine you have just completed writing a technical document in AsciiDoc, and now you’re looking to share it with others on the web. HTML is a universally accessible format for web content, making it a perfect choice for distribution. Converting an AsciiDoc file to HTML allows you to easily share your document with a broader audience via a web page without needing them to have specific tools or software to view the content.

Explanation:

• asciidoctor: This command calls the Asciidoctor tool, which starts the conversion process.
• path/to/file.adoc: This argument specifies the path to the AsciiDoc file you wish to convert. Replace path/to/file.adoc with the actual path and filename of your document.

Example Output:

Upon executing this command, a new HTML file with the same base name as the original AsciiDoc file will be generated in the same directory. If the file was named document.adoc, the output will be document.html.

Use case 2: Convert a specific .adoc file to HTML and link a CSS stylesheet

Code:

asciidoctor -a stylesheet path/to/stylesheet.css path/to/file.adoc

Motivation:

By default, Asciidoctor applies its own styling to converted HTML documents. However, you might want to apply custom styles to better match your brand or design preferences. Linking a specific CSS stylesheet allows you to personalize the aesthetic of the document, ensuring consistency with broader stylistic guidelines or existing web assets.

Explanation:

• asciidoctor: Initiates the Asciidoctor command for conversion.
• -a stylesheet: This attribute option allows you to specify a CSS stylesheet to be linked with the generated HTML file. It alters the appearance of the resulting output according to the styles defined in the CSS.
• path/to/stylesheet.css: This specifies the path to the custom CSS file you wish to use. Replace this with the path to your actual stylesheet.
• path/to/file.adoc: Indicates the AsciiDoc file to be converted.

Example Output:

The generated HTML file will now include a link to the specified CSS stylesheet in its header, leading to the visual style defined in the stylesheet being applied to the document.

Use case 3: Convert a specific .adoc file to embeddable HTML, removing everything except the body

Code:

asciidoctor --embedded path/to/file.adoc

Motivation:

There are particular scenarios where you might want to integrate the content of an AsciiDoc file directly into another HTML-based system, such as a content management system (CMS) or an existing web page structure. In such cases, having only the body content available without additional HTML tags or headers is essential for seamless integration.

Explanation:

• asciidoctor: The command that triggers the conversion process.
• --embedded: This flag tells Asciidoctor to strip out everything except the actual body content of the document, skipping any additional wrappers, headers, or meta tags.
• path/to/file.adoc: Specifies the AsciiDoc file to be processed.

Example Output:

The resulting output will be a minimal HTML snippet containing only the body content of your document, ideal for embedding into other HTML structures without unnecessary elements or duplication of headers.

Use case 4: Convert a specific .adoc file to a PDF using the asciidoctor-pdf library

Code:

asciidoctor --backend pdf --require asciidoctor-pdf path/to/file.adoc

Motivation:

Documents intended for print or distribution in a format that preserves layout and design integrity, like PDF, require conversion from the original AsciiDoc format. PDF format is particularly useful for sharing finalized documents that require consistent presentation across different devices and operating systems. Using Asciidoctor with the additional PDF backend ensures that you can generate high-quality PDFs directly from your AsciiDoc content.

Explanation:

• asciidoctor: The command line tool used for the conversion process.
• --backend pdf: This option switches the backend of the conversion process to PDF. It tells Asciidoctor to output a PDF format rather than the default HTML.
• --require asciidoctor-pdf: This flag ensures that the asciidoctor-pdf library is required and loaded for the conversion. It enables Asciidoctor to handle PDF creation.
• path/to/file.adoc: The specific AsciiDoc file you wish to convert into a PDF document.

Example Output:

Running this command will generate a PDF file with the same base name as the original AsciiDoc file. For example, if the input file is report.adoc, the output will be report.pdf, located in the same directory.

Conclusion:

The Asciidoctor command-line tool is a versatile solution for transforming plain text, AsciiDoc-formatted files into various professional output formats such as HTML and PDF. By utilizing different options and backends, users can customize the conversion to meet their specific needs, whether it’s styling HTML with custom CSS, creating embeddable HTML content, or generating polished PDF documents. Asciidoctor helps streamline the documentation workflow, enabling writers and developers to produce and share content swiftly and effectively.