asciidoctor

Convert a specific .adoc file to HTML (the default output format)

$ asciidoctor [path/to/file.adoc]

$ asciidoctor [[-a|--attribute]] stylesheet [path/to/stylesheet.css] [path/to/file.adoc]

$ asciidoctor [[-e|--embedded]] [path/to/file.adoc]

$ asciidoctor [[-b|--backend]] [pdf] [[-r|--require ]][asciidoctor-pdf] [path/to/file.adoc]

asciidoctor [OPTION...] FILE...
asciidoctor [OPTION...] -

-o, --output-file <file>
    Specifies the path to the output file. If omitted, the output filename is derived from the input file with the backend's default extension.

-D, --destination-dir <dir>
    Specifies the directory where the output file will be written.

-b, --backend <backend_name>
    Sets the backend for conversion. Common backends include 'html5', 'docbook5', and 'pdf' (requires asciidoctor-pdf gem).

-a, --attribute <key[=value]>
    Defines a document attribute or sets its value. Can be used multiple times to define several attributes.

-r, --require <library>
    Requires a Ruby library before conversion, useful for loading extensions or custom converters.

-S, --safe-mode <level>
    Sets the safe mode level, controlling access to the file system and external resources. Levels include 'safe', 'server', 'secure', and 'unsafe'.

-s, --no-header-footer
    Suppresses the document header and footer, producing a partial document rather than a standalone one.

-d, --doctype <type>
    Sets the document type. Common types are 'article', 'book', 'manpage', and 'inline'.

-q, --quiet
    Suppresses all output except for errors, useful for scripting or automated environments.

-v, --verbose
    Enables verbose output, showing more details about the conversion process.

--trace
    Enables a backtrace for exceptions, which is very useful for debugging conversion issues.

asciidoctor is a powerful, open source text processor written in Ruby that converts AsciiDoc source files into a variety of output formats, including HTML5, DocBook, and PDF. AsciiDoc is a human-readable markup language designed for writing technical documentation, books, articles, and more, emphasizing semantic structure over presentation. asciidoctor serves as a modern, faster, and more feature-rich successor to the original Python-based asciidoc processor. It provides comprehensive support for standard AsciiDoc syntax elements such as sections, paragraphs, lists, tables, images, and source code blocks. Its highly extensible architecture allows for custom backends, preprocessors, and postprocessors, making it a versatile tool for authors and technical writers seeking to automate their documentation workflows and publish high-quality content from plain text.

Using asciidoctor requires a Ruby environment to be installed on your system. While it can generate HTML5 and DocBook out-of-the-box, generating PDF documents requires the separate asciidoctor-pdf Ruby gem to be installed. Similarly, other specialized output formats or custom extensions may require additional Ruby gems. Be cautious when using --safe-mode unsafe as it disables security restrictions, potentially allowing arbitrary file system access or external resource loading from the processed AsciiDoc content.

AsciiDoc heavily relies on document attributes, which are variables that can be defined within the document or passed via the command line using the -a option. These attributes control various aspects of the output, such as image paths, conditional content inclusion, and styling. Understanding and utilizing attributes is crucial for advanced AsciiDoc authoring and customization.

The Asciidoctor ecosystem is rich with extensions that enhance its capabilities. These include custom backends (like asciidoctor-pdf for PDF generation), syntax extensions for diagrams (e.g., using Asciidoctor Diagram), and integrations with build tools like Gradle and Maven. This extensibility allows Asciidoctor to fit into diverse documentation workflows.

Asciidoctor was developed by Dan Allen and the Asciidoctor project maintainers as a modern, high-performance replacement for the original Python-based asciidoc.py processor created by Stuart Rackham. The Ruby implementation aimed to address performance bottlenecks and provide a more extensible architecture. Since its inception, Asciidoctor has gained significant traction, becoming the de facto standard for processing AsciiDoc content and serving as the foundation for various documentation toolchains, including Antora and Jekyll-based sites.

pandoc(1), markdown(1), man(1), ruby(1)