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...

-a NAME[=VALUE], --attribute NAME[=VALUE]
    Set or override document attribute (repeatable)

-b BACKEND, --backend BACKEND
    Output format: html5 (default), docbook5, manpage, latex, pdf, epub3

-d DOCTYPE, --doctype DOCTYPE
    Document type: article (default), book, manpage, inline

-s, --standalone
    Generate freestanding document (includes header/footer)

-S LEVEL, --safe-mode LEVEL
    Security level: SAFE (default), SERVER, UNRESTRICTED

-o FILE, --out-file FILE
    Write output to specified file

-D DIR, --destination-dir DIR
    Write output to directory

-r LIB, --require LIB
    Require Ruby library before processing (repeatable)

-T DIR, --template-dir DIR
    Custom template directory

--template-engine ENGINE
    Template engine: erb (default), slim, haml

-v, --verbose
    Enable verbose logging

-q, --quiet
    Suppress warnings

--trace
    Enable stack trace on error

--profile PROFILE
    Load attribute set from profile file

-e, --embedded
    Embedded mode (no header/footer)

--sectlinks
    Enable section links (xrefs)

--attributes FILE
    Load attributes from YAML/JSON file

-h, --help
    Show help message

--version
    Print version info

--failure-level LEVEL
    ERROR (default), WARN, INFO, UNKNOWN, SKIP

Asciidoctor is a fast, extensible, open-source text processor and publishing toolchain for converting AsciiDoc markup (.adoc, .asciidoc, .asc) files into HTML5, DocBook 5 (or 4.5), PDF, man pages, ePub, and other formats. Written in pure Ruby, it offers superior performance, standards compliance, and customization compared to the original AsciiDoc tool.

The asciidoctor command processes input files using a modular converter pipeline. It supports doctype declarations (article, book, manpage), attribute substitution, macros, includes, and conditional content. Key strengths include safe-mode execution to mitigate risks like shell execution, extension support via Ruby blocks or gems, and template engines (ERB, Slim) for output customization.

Ideal for technical documentation, books, blogs, and API references, Asciidoctor integrates with CI/CD pipelines, static site generators like Asciidoctor Web, and tools such as Antora for multi-repo docsites. Output is semantic and accessible by default, with options for CSS theming and JavaScript enhancements.

Requires Ruby >= 2.5 or JRuby; PDF backend needs asciidoctor-pdf gem; safe mode restricts includes/executables; large docs may need >1GB RAM.

asciidoctor example.adoc
Converts example.adoc to example.html.

asciidoctor-pdf example.adoc
Requires separate gem for PDF generation.

Launched in 2012 by Dan Allen (mojavelinux) as a Ruby reimplementation of AsciiDoc. Reached 1.0 in 2013; version 2.0 (2020) added major performance boosts, extension API v3, and PDF 2 support. Now dominant AsciiDoc processor with 30k+ GitHub stars.

asciidoctor-pdf(1), asciidoctor-diagram(1), pandoc(1), a2x(1), groff(1)