# Asciidoctor — Fast AsciiDoc Processor and Publishing Toolchain

> A fast, open-source text processor written in Ruby for converting AsciiDoc content to HTML5, DocBook, PDF, and other formats.

## Install

Save as a script file and run:

# Asciidoctor — Fast AsciiDoc Processor and Publishing Toolchain

## Quick Use
```bash
# Install via RubyGems
gem install asciidoctor

# Convert an AsciiDoc file to HTML
asciidoctor README.adoc

# Convert to PDF (requires asciidoctor-pdf)
gem install asciidoctor-pdf
asciidoctor-pdf document.adoc
```

## Introduction
Asciidoctor is an open-source text processor that converts AsciiDoc markup into HTML5, DocBook 5, PDF, and other publishing formats. Written in Ruby, it provides a faster and more feature-rich alternative to the original AsciiDoc Python implementation, and has become the standard toolchain for technical documentation, books, and API references in the AsciiDoc ecosystem.

## What Asciidoctor Does
- Parses AsciiDoc source files into a document model and renders them to multiple output formats
- Produces semantic HTML5 with built-in styling and syntax highlighting
- Generates PDF documents through the asciidoctor-pdf extension
- Supports DocBook 5 output for integration with XML-based publishing pipelines
- Provides an extensible architecture for custom converters, preprocessors, and macros

## Architecture Overview
Asciidoctor is a Ruby library with a CLI wrapper. It processes AsciiDoc input in two phases: parsing (building an abstract syntax tree from the markup) and conversion (rendering the AST into the target format). The converter is pluggable — the core ships HTML5 and DocBook converters, while extensions like asciidoctor-pdf and asciidoctor-epub3 provide additional output formats. The extension API allows custom blocks, macros, and tree processors.

## Self-Hosting & Configuration
- Install via `gem install asciidoctor` on any system with Ruby 2.7+
- Also available as a Docker image, Homebrew formula, and Linux distribution package
- Configure document attributes (author, version, TOC, theme) in the document header or via CLI flags
- Use asciidoctor-pdf for PDF generation and asciidoctor-diagram for diagram rendering
- Integrate into build pipelines with Gradle (asciidoctor-gradle-plugin) or Maven plugins

## Key Features
- Processes AsciiDoc documents 100x faster than the legacy Python implementation
- Rich syntax support including tables, admonitions, cross-references, and conditional includes
- Built-in syntax highlighting for code blocks via Rouge, Pygments, or highlight.js
- Extensible with a well-documented Ruby API for custom processing
- Active ecosystem with PDF, EPUB, reveal.js, and diagram extensions

## Comparison with Similar Tools
- **Markdown / CommonMark** — simpler syntax with fewer features; AsciiDoc handles complex technical documents better
- **Sphinx (reStructuredText)** — Python-based doc generator; Asciidoctor offers lighter setup and faster processing
- **Pandoc** — universal document converter; Asciidoctor provides deeper AsciiDoc support and a richer extension API
- **LaTeX** — typesetting for academic publishing; Asciidoctor is more accessible for software documentation
- **MkDocs** — Markdown-based static sites; Asciidoctor supports richer markup for books and specifications

## FAQ
**Q: Is AsciiDoc the same as Asciidoctor?**
A: AsciiDoc is the markup language. Asciidoctor is the processor that converts AsciiDoc files to output formats.

**Q: Can I use Asciidoctor without Ruby?**
A: Yes. AsciidoctorJ runs on the JVM, and Asciidoctor.js runs in Node.js and browsers. Both are official ports.

**Q: Does it work with GitHub?**
A: Yes. GitHub natively renders .adoc files in repositories using Asciidoctor.

**Q: How does it compare to Markdown for documentation?**
A: AsciiDoc supports tables, admonitions, includes, cross-references, and conditional content natively — features that require nonstandard extensions in Markdown.

## Sources
- https://github.com/asciidoctor/asciidoctor
- https://docs.asciidoctor.org/

---
Source: https://tokrepo.com/en/workflows/asset-ba54da5d
Author: Script Depot