How to use the command 'asciidoctor' (with examples)

The ‘asciidoctor’ command is a processor that converts AsciiDoc files to a publishable format. It is a powerful tool for generating documentation from AsciiDoc files and supports various output formats such as HTML, PDF, and others. The command provides several options to customize the output, including the ability to link CSS stylesheets, generate embeddable HTML, and specify a backend for PDF generation.

Use case 1: Convert a specific .adoc file to HTML

Code:

asciidoctor path/to/file.adoc

Motivation:

The first use case demonstrates how to convert an AsciiDoc file to HTML using the default output format. This can be useful for generating HTML-based documentation or web pages from AsciiDoc files. By simply supplying the path to the input file, the ‘asciidoctor’ command will convert it to HTML and produce an HTML file as output.

Explanation:

• asciidoctor - The command to run the ‘asciidoctor’ processor.
• path/to/file.adoc - The path to the AsciiDoc file that should be converted to HTML.

Example output:

The output of this command will be an HTML file that represents the content of the input AsciiDoc file in a publishable format. The file will have the same name as the input file, but with the extension changed to .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:

In this use case, we want to convert an AsciiDoc file to HTML while applying a custom CSS stylesheet to the output. This can be useful for styling the document to match a specific theme or branding. By specifying the path to the CSS stylesheet using the -a option, the ‘asciidoctor’ command will include the stylesheet in the generated HTML file.

Explanation:

• asciidoctor - The command to run the ‘asciidoctor’ processor.
• -a stylesheet=path/to/stylesheet.css - Specifies the path to the CSS stylesheet that should be applied to the HTML output.
• path/to/file.adoc - The path to the AsciiDoc file that should be converted to HTML.

Example output:

The output of this command will be an HTML file that includes the content from the input AsciiDoc file and is styled using the specified CSS stylesheet. The file will have the same name as the input file, but with the extension changed to .html.

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

Code:

asciidoctor --embedded path/to/file.adoc

Motivation:

Sometimes, we only need the actual body content of an AsciiDoc file without any additional styling or navigation elements. In such cases, we can utilize the --embedded option with the ‘asciidoctor’ command to generate embeddable HTML that only includes the body content. This can be useful when embedding AsciiDoc documentation into other web pages or applications.

Explanation:

• asciidoctor - The command to run the ‘asciidoctor’ processor.
• --embedded - Specifies that the output should be embeddable HTML, removing everything except the body content.
• path/to/file.adoc - The path to the AsciiDoc file that should be converted to embeddable HTML.

Example output:

The output of this command will be an HTML file that contains only the body content from the input AsciiDoc file, without any additional styling or navigation elements. The file will have the same name as the input file, but with the extension changed to .html.

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:

The last use case demonstrates how to convert an AsciiDoc file to a PDF using the asciidoctor-pdf library as the backend. This is suitable when you need to generate PDF documents from AsciiDoc files, for example, for printing or sharing offline. By specifying the --backend=pdf option and requiring the asciidoctor-pdf library using --require=asciidoctor-pdf, the ‘asciidoctor’ command will generate a PDF file as output.

Explanation:

• asciidoctor - The command to run the ‘asciidoctor’ processor.
• --backend=pdf - Specifies that the output should be in PDF format.
• --require=asciidoctor-pdf - Requires the asciidoctor-pdf library as the backend for PDF generation.
• path/to/file.adoc - The path to the AsciiDoc file that should be converted to PDF.

Example output:

The output of this command will be a PDF file that is generated from the input AsciiDoc file. The file will have the same name as the input file, but with the extension changed to .pdf.

Conclusion:

The ‘asciidoctor’ command is a versatile tool for converting AsciiDoc files to various publishable formats. With different options like linking CSS stylesheets, generating embeddable HTML, and specifying a backend for PDF generation, it provides flexibility to customize the output based on specific requirements. Whether you need to create HTML-based documentation, styled web pages, embeddable HTML, or PDF documents, the ‘asciidoctor’ command has you covered.